Shared Context Architecture¶
Context at the Individual Level — and What Changes¶
In Lift 1, you recapped context engineering: the project context file as bootstrap (the "INDEX, not ENCYCLOPEDIA" principle), path-scoped rules for conditional context, subdirectory context for domain-specific knowledge. That architecture works for one practitioner directing one system.
At the team level, context is no longer authoring — it's architecture. The question shifts from "what does my AI coding assistant need to know?" to "what does every contributor's AI coding assistant need to know — and what should each one know differently?"
The design challenge: every AI coding assistant on the team should produce consistent output for shared conventions (naming, schema, error handling), while each assistant also needs domain-specific context for its contributor's workstream (CAIC pipeline vs. UAC pipeline). Shared rules with specialized extensions.
The Layered Hierarchy at Organizational Scale¶
The context hierarchy you know — user-level, project root, subdirectory — becomes a deliberate architectural decision when multiple contributors share a codebase:
| Layer | Scope | What Goes Here | Who Maintains It |
|---|---|---|---|
| Project root | Every contributor, every session | Shared conventions, build commands, unified schema definition, quality standards | Team lead or designated maintainer — changes via PR |
| Subdirectory | Contributors working in that domain | Domain-specific guidance (e.g., pipeline/caic/ gets CAIC format documentation, pipeline/uac/ gets UAC format documentation) |
The pair owning that domain — changes via PR |
| Path-scoped rules | Contributors touching matching files | Conditional rules that activate only for specific file patterns (e.g., rules about API error handling apply only when editing src/api/**/*.ts) |
Anyone, reviewed by domain owner |
| Local overrides | One contributor only | Personal preferences, experimental settings — excluded from version control | Individual contributor, not shared |
The architectural discipline: root-level context must be universally applicable. Every line in the project root context file uses limited context window capacity for every contributor. A rule about CAIC date formatting that only matters to the CAIC pair wastes context for the UAC pair. That rule belongs in the pipeline/caic/ subdirectory context.
The practical test: if a rule doesn't apply to at least half your contributors, it doesn't belong at the root level.
Context as Infrastructure¶
Research on AI-assisted development in complex codebases has quantified something practitioners intuit: context is load-bearing infrastructure, not optional configuration.
The finding: for every 100 lines of production code, effective AI-assisted systems maintain roughly 24 lines of structured context — project-level conventions, domain-specific agent specifications, and reference documentation. This knowledge-to-code ratio represents the investment required to make AI agents reliably effective.
The system-level implication: when you design a shared context architecture, you're not writing documentation. You're building the infrastructure that determines whether every contributor's AI coding assistant produces consistent, high-quality output. Skimping on context architecture is like skimping on the deployment pipeline — everything downstream degrades.
Three categories of context serve different coordination functions:
| Category | What It Coordinates | Staleness Risk |
|---|---|---|
| Technical context | Coding standards, architecture decisions, build/test commands | Low — changes with major refactors |
| Project context | Current priorities, scope boundaries, in-progress work | High — changes every sprint |
| Business context | Why the system exists, compliance requirements, domain rules | Medium — changes with strategy shifts |
The primary failure mode is context staleness — outdated context that causes AI coding assistants to generate code conflicting with recent changes. Bootstrapping context is trivial (your AI coding assistant can generate an initial context file in seconds). Keeping it accurate as the codebase evolves is the hard, ongoing work. Treat context files as maintained software artifacts: versioned, reviewed, and tested — not written once and forgotten.
Cross-Tool Portability¶
A practical concern for teams with diverse tooling: every major AI coding tool has its own context file format. Claude Code reads CLAUDE.md. Cursor reads .cursorrules. GitHub Copilot reads .github/copilot-instructions.md. The content across all of these is nearly identical — coding standards, build commands, architectural patterns.
The emerging standard: AGENTS.md as a cross-tool context file, now supported by Claude Code, Cursor, GitHub Copilot, Gemini CLI, and others. The practical strategy for mixed-tool teams: maintain AGENTS.md as the single source of truth. Tool-specific files can reference it rather than duplicating content.
The design principle remains the same regardless of the file format: bootstrap, don't dump. Point to documentation. Keep the root context focused and small. Use the layered hierarchy for specialization.
Mob Session: Design the Context Architecture¶
Format: Mob Session Time: ~3 minutes Setup: One person drives, everyone navigates.
Your multi-center platform has shared conventions (unified schema, quality standards, deployment pipeline) and domain-specific pipelines (CAIC ingestion vs. UAC ingestion). Design the context architecture.
Ask your AI coding assistant:
We're building a multi-center avalanche platform with two center-specific pipelines (CAIC and UAC) that feed into a unified dashboard. Design a context architecture: what goes in the project root context, what goes in subdirectory context for each pipeline, and what rules should be path-scoped to specific file patterns? Show the directory layout and what each context file should contain.
Claude Code designs the architecture and can create the actual directory structure and context files.
Codex designs the architecture. Create the files manually based on its recommendation.
pi designs the architecture. Create the files manually based on its recommendation.
Evaluate the result: does the root-level context apply to every contributor? Are domain-specific rules scoped to the right directories? Would a new contributor's AI coding assistant behave consistently with existing contributors' assistants from the first session?
Key Insight¶
Context at team scale is architecture, not authoring. The layered hierarchy — project root for shared conventions, subdirectories for domain specialization, path-scoped rules for conditional context, local overrides for personal preferences — ensures every contributor's AI coding assistant starts from the same foundation while having the domain-specific knowledge it needs. The knowledge-to-code ratio quantifies what practitioners already know: context is load-bearing infrastructure. Underinvest in it, and every contributor's output degrades independently in ways that compound at integration time.