Context Engineering for Coding Agents: The Multi-Tier Architecture

An AI coding agent's context window represents its entire working memory. In modern software engineering with frontier reasoning models (Gemini 3 Pro, Claude 3.5 Sonnet / 3.7 Sonnet, GPT-5 / o3), the context window is both finite and perishable: as token count scales, attention degrades exponentially across long horizons — an empirical reality known as context rot.

Context engineering has superseded conversational prompt engineering as the definitive discipline of agentic software development. The central engineering challenge is no longer "how do I phrase this prompt?", but rather: "How do I supply the exact, minimum-entropy set of ground-truth tokens required for the current execution step while keeping irrelevant context externalized?"

flowchart TD
    subgraph Tier_1["Tier 1: Standing Invariants (500–1,500 tokens)"]
        RULES["Root Instruction Files<br/>(AGENTS.md / CLAUDE.md)"]
        CONTRACTS["Core Normative Rules & Architectural Boundaries"]
        RULES --- CONTRACTS
    end

    subgraph Tier_2["Tier 2: Progressive Procedural Skills (Deferred)"]
        SKILLS_DEF["Skill Registry / Headers<br/>(name + 60-token description)"]
        SKILL_BODY["Loaded Skill Body<br/>(.agents/skills/<name>/SKILL.md)"]
        SKILLS_DEF -->|Triggered on demand| SKILL_BODY
    end

    subgraph Tier_3["Tier 3: Ephemeral Session Memory (Active Working Window)"]
        HIST["Conversation Trajectory & Tool Call I/O"]
        DIFF["Working Tree Diffs & Scratch Scripts"]
        HIST --- DIFF
    end

    subgraph Tier_4["Tier 4: Sovereign Semantic Knowledge Base (Externalized)"]
        WIKI[("Wikantik Semantic Knowledge Base<br/>(Living specs, ADRs, RDF Knowledge Graph)")]
        MCP["Knowledge MCP Server<br/>(/knowledge-mcp, 21 read tools)"]
        WIKI --- MCP
    end

    Tier_1 --> AGENT{"Coding Agent Runtime<br/>(Antigravity agy / Claude Code)"}
    Tier_2 --> AGENT
    Tier_3 <--> AGENT
    AGENT <-->|Dynamic Retrieval: assemble_bundle / get_page_for_agent| Tier_4

1. The Four-Tier Context Hierarchy

A robust context architecture partitions project knowledge across four distinct operational tiers:

2. Tier 1: Standing Instruction Files (AGENTS.md and CLAUDE.md)

Standing instruction files represent the project's permanent voice. Every mature coding agent framework loads these files automatically upon session boot (AGENTS.md in Antigravity and Codex; CLAUDE.md in Claude Code).

The Four Essential Elements

1. Non-Derivable Rules: Constraints that cannot be deduced from static code inspection (e.g., "NEVER modify core platform code in jspwiki; propose architectural handoffs as wiki RFCs").
2. Deterministic Command Truth: Exact, copy-pasteable build, test, lint, and verification commands with mandatory flags (e.g., ./bin/wikantik lint <slug> rather than generic linter assumptions).
3. Load-Bearing Operational Gotchas: High-cost pitfalls documented from past regressions (e.g., "KaTeX interprets unescaped currency dollar signs as inline math delimiters; always escape with \$").
4. Architectural Pointers, Not the Territory: A concise ecosystem map linking directly to external semantic wiki slugs rather than embedding large architecture specifications inline.

The Standardized Agent Header Pattern

In the Simple Agility ecosystem, every repository installs a standardized Agent Header pointing to the central architectural hub on Wikantik:

<!-- SIMPLE-AGILITY-AGENT-HEADER-START -->
## Simple Agility Architectural Context
This repository is part of the **Simple Agility** small-business ecosystem:
- **Role in Stack:** Content strategy, SEO telemetry analysis, and architectural coordination engine.
- **Architecture Hub:** Refer to `SimpleAgilityStackHub` on Wikantik (`https://wiki.wikantik.com/SimpleAgilityStackHub`).
- **Active Initiatives & Coordination:** Check `SimpleAgilityAgentCoordination` for in-flight tasks and cross-repo dependencies.
- **Architectural Decisions:** Consult `SimpleAgilityDecisionLog` before changing cross-repo APIs, logging, or telemetry conventions.
<!-- SIMPLE-AGILITY-AGENT-HEADER-END -->

By enforcing this header, any agent initialized in any repository immediately acquires orientation and the exact wiki slugs required for deeper retrieval.

3. Tier 2: Progressive Disclosure and Modular Skills

Attempting to place every operational runbook into AGENTS.md triggers immediate context exhaustion. The proven defense is progressive disclosure:

sequenceDiagram
    autonumber
    actor User as Engineer
    participant Agent as Coding Agent Runtime
    participant Skills as Local Skill Registry (.agents/skills)
    participant Execution as Product Repository

    User->>Agent: "Execute structured page curation on VectorIndexingInternals"
    Note over Agent: Agent matches intent against 60-token description in skill registry
    Agent->>Skills: Loads SKILL.md for project_structured_page_curation
    Skills-->>Agent: Injects full procedural runbook (1,800 tokens)
    Agent->>Execution: Executes step-by-step curation commands
    Agent-->>User: Reports verified outcome

The 98% Token Deferral Rule

A procedural skill packaged in .agents/skills/<name>/SKILL.md contains two functional blocks:

• Frontmatter Descriptor: Name and human-readable trigger description (~60 tokens).
• Skill Body: Exhaustive step-by-step instructions, edge cases, and command sequences (~2,000–3,500 tokens).

By loading only the descriptor into the root context, the harness defers 98% of the token cost until the agent actively determines that the skill's capabilities are required.

4. Tier 4: Wikantik as the Sovereign External Context Engine

While instruction files and skills scale within a single repository, they break down across multi-repository architectures. If an engineer manages five microservices or distinct components (stockroom, roller, jakemon, wealthview, wiki-content-agent), copy-pasting documentation across repos guarantees desynchronization and stale drift.

The Level 5 maturity pattern (AgenticCodingMaturityModel) replaces local file hoarding with an authoritative external knowledge plane:

flowchart LR
    subgraph Repositories["Decoupled Product Repositories"]
        R1["roller (docker2)<br/>Customer Weblog"]
        R2["stockroom (docker1)<br/>Inventory WMS"]
        R3["jakemon (inference)<br/>Observability Plane"]
    end

    subgraph Knowledge_Plane["Sovereign Knowledge Backbone (Wikantik)"]
        WIKI_CORE[("Wikantik Core Engine<br/>Markdown + Frontmatter")]
        KG[("RDF Knowledge Graph<br/>Entities & SPARQL")]
        MCP_K["Knowledge MCP Server<br/>(/knowledge-mcp)"]
        WIKI_CORE --- KG
        KG --- MCP_K
    end

    R1 <-->|assemble_bundle / get_briefing| MCP_K
    R2 <-->|read_pages / get_page_for_agent| MCP_K
    R3 <-->|sparql_query / retrieve_context| MCP_K

Knowledge MCP Retrieval Tool Surface

The Wikantik Knowledge MCP server (https://wiki.wikantik.com/knowledge-mcp) provides 21 read-only tools designed specifically for high-efficiency agent grounding:

1. assemble_bundle(query): The primary retrieval tool. Runs hybrid BM25 + dense vector semantic search, extracts relevant section chunks, de-duplicates overlapping text, and computes a mathematical coverage.confidence score (strong, adequate, weak).
2. get_page_for_agent(canonicalId, tokenBudget): Returns a token-budgeted projection of a page. Rather than dumping an entire 3,000-word markdown file into context, it emits:
   • Verification status (verified_at, verified_by)
   • Frontmatter metadata and cluster membership
   • Section heading outline
   • Extracted key facts and constraints
   • Diagnostic tool hints and stale citation alerts
3. retrieve_context(query): Returns ranked page and section candidates without full bodies, allowing the agent to evaluate relevance before committing context budget.
4. read_pages(slugs): Fetches raw markdown for up to 20 verified slugs in a single batched network round-trip.
5. sparql_query(query): Executes read-only SPARQL queries over the RDF Knowledge Graph to resolve architectural relationships, component dependencies, and ontology hierarchies deterministically.

Connecting the Agent Harness via Streamable HTTP

To wire coding agents directly to Wikantik, configure Streamable HTTP in the project's .mcp.json:

{
  "mcpServers": {
    "wikantik-knowledge": {
      "type": "http",
      "url": "https://wiki.wikantik.com/knowledge-mcp",
      "headers": {
        "Authorization": "Bearer ${WIKANTIK_KNOWLEDGE_API_KEY}"
      }
    }
  }
}

5. Mathematical Modeling of Context Decay and Budgeting

Context is not an unlimited commodity; attention efficiency decays mathematically as the working context expands.

The Attention Retention Decay Model

Empirical attention retention across long token sequences can be formalized by an exponential decay function:

Where:

• A_0: Baseline attention fidelity on isolated, short-context tasks (A_0 ≈ 1.0).
• N_active: The cumulative token count currently residing in the active context window.
• W_max: The model's nominal context ceiling (e.g., 200,000 tokens).
• lambda: Empirical distraction decay constant (lambda ≈ 1.5 to 2.8).

When active tokens exceed 50% of nominal capacity without externalized notes, the probability of instruction omission or hallucinated API parameters scales rapidly.

The Bounded Context Budget Equation

To maintain optimal reasoning fidelity (retention ≥ 0.85), the orchestrator enforces a strict budget allocation:

Target Budget Distribution for 200k Frontier Models

• C_invariants (Root Rules): ≤ 1,500 tokens (0.75%)
• C_skills (Active Procedural Body): ≤ 3,000 tokens (1.5%)
• C_wiki_brief (Wikantik Retrieval Bundle): ≤ 4,000 tokens (2.0%)
• C_session (Active Working Code & Diff History): ≤ 25,000 tokens (12.5%)
• Delta_generation (Reserve for Reasoning & Code Emission): ≥ 15,000 tokens (7.5%)
• Externalized Knowledge Plane (Wikantik): Unbounded external storage; zero window cost until queried.

6. Long-Horizon Strategies: Compaction, Scratchpads, and Subagents

When complex refactoring spans hours or days, context engineering relies on three complementary architectural mechanisms:

1. High-Fidelity Compaction

When context utilization crosses a threshold (~75%), mature harnesses trigger compaction. The craft of compaction is asymmetric retention:

• Preserve: Explicit decisions made, architectural trade-offs accepted, active file paths, failed experiment rationales, and outstanding task checklists.
• Evict: Raw compiler error traces, full file listings already persisted to disk, intermediate tool call payloads, and resolved debugging conversations.

2. Externalized Scratchpads and Plan Files

The agent must write durable state outside the context window. Storing execution progress in on-disk plan files or scratch scripts (scratch/plan.md) ensures that if a session crashes, compacts, or transfers to a secondary agent, the plan is re-read cold with zero fidelity loss (SpecDrivenDevelopment).

3. Subagent Context Isolation

Tasks requiring extensive file scanning or broad log exploration should be delegated to ephemeral subagents. A subagent consumes its own isolated 60,000-token window exploring 40 source files, returning only a 300-token distilled summary to the primary coordinator.

7. Context Anti-Patterns to Eliminate

1. The Kitchen-Sink CLAUDE.md: Dumping complete API documentation, database schemas, and style guides into the standing instruction file. This burns 15,000 tokens on every prompt and causes the model to ignore foundational safety rules.
2. Context Hoarding: Pasting entire source files or stack traces into chat "just in case" instead of letting the agent query specific line ranges with view_file.
3. Compaction Roulette: Allowing an agent to drift past context limits without externalized notes or specs on disk, forcing the model to guess previous constraints after lossy summarization.
4. Conflicting Authority Layers: When an in-repo CLAUDE.md, a skill prompt, and an external wiki page state contradictory rules, the agent resolves the conflict non-deterministically. Maintain one authoritative source of truth per domain (SimpleAgilityDecisionLog).

See Also

• AgenticCodingHub — Master hub for agentic software engineering practices.
• SpecDrivenDevelopment — Specifications as immutable context anchors.
• SkillsVsMcp — Procedural runbooks versus living data plane connectivity.
• FindingTheRightMcpTool — Decision tree for selecting Wikantik MCP tools without token waste.
• ConnectingClaudeCodeToWikantikMcp — Setup runbook for configuring Claude Code and Antigravity with Wikantik.
• SimpleAgilityStackHub — Enterprise architecture and cross-repo context coordination.