Context Engineering¶
The Problem Context Solves¶
AI coding assistants are stateless — every conversation starts from zero. The context window (the "oxygen tank" from the Blue Square track) is finite. These two constraints mean that without deliberate context engineering, every new conversation requires re-explaining your project, your conventions, and your constraints.
The Blue Square solution is a project context file — a file your AI coding assistant reads automatically at the start of every session. The bootstrap pattern keeps it lean: point to documentation rather than duplicating it. "INDEX, not ENCYCLOPEDIA."
That works for a single contributor working on a single project. The risk here is what happens when you scale.
From File to Architecture¶
When you're directing multiple parallel workstreams — each with its own conversation, its own sub-agents, its own context window — a single project context file isn't enough. You need a layered architecture:
The hierarchy:
| Layer | Scope | What Goes Here | Loaded When |
|---|---|---|---|
| User-level | All your projects | Personal preferences, style conventions | Every session |
| Project root | This project | Project structure, tech stack, team conventions | Every session in this project |
| Rules directory | Conditional | Path-scoped rules that activate only when relevant files are touched | On demand |
| Subdirectory | Specific area | Domain-specific context for a module or subsystem | When working in that directory |
Path-scoped rules are the key elevation from Blue Square. Instead of loading every convention into every conversation, you write focused rules that activate conditionally. A rule scoped to **/tests/** only loads when AI is working with test files. A rule scoped to **/*.sh only loads when working with shell scripts.
The tradeoff: unfollowed rules are actively harmful. Every instruction your AI coding assistant ignores dilutes its attention on the instructions it should follow. A monolithic context file full of rules that don't apply to the current task creates noise. Path-scoped rules solve this by ensuring AI only sees what's relevant.
Rules go in .claude/rules/ as individual markdown files with YAML frontmatter specifying paths: globs. Claude Code loads them conditionally based on which files are being read or edited.
Use AGENTS.md at the project root. Codex supports directory-level context files for scoped instructions.
Use AGENTS.md at the project root. Subdirectory context files scope instructions to specific areas of the project.
Progressive Disclosure¶
The design principle behind layered context: scope by default. Every conversation should see the minimum context required for its task. Agents reach for more information explicitly (by reading files, consulting documentation) rather than being flooded with everything upfront.
This is the same principle behind the bootstrap pattern — point to docs, don't dump them — applied at the architecture level. Your project context file is the table of contents. Your rules directory adds conditional chapters. Your subdirectory context adds domain-specific appendices. Each layer loads only when needed.
Team Discussion: Context Architecture¶
Format: Team Discussion Time: ~2 minutes
Your project is a multi-zone alerting engine with data ingestion, analysis, alerts, and a dashboard. Each subsystem has different conventions and constraints.
Discuss: What would go in the project root context vs. a rules file vs. a subdirectory context? Where would you put data format conventions? Alert threshold rules? Dashboard component patterns? What happens if you put everything in the root file instead?
Key Insight¶
Context engineering at scale is architecture, not authoring. The project context file is your foundation — same bootstrap pattern, same "INDEX, not ENCYCLOPEDIA" principle. What changes is that you add conditional layers: path-scoped rules for context that only applies sometimes, subdirectory context for domain-specific knowledge. The discipline is knowing what loads when, and keeping each layer focused. Unfollowed rules are worse than no rules — they teach your AI coding assistant to ignore instructions.