Agent Context Architecture Field Guide
A practitioner's field guide to Agent Context Architecture: the tactical method for designing what an agent reads, skips, may write, and must prove — traced through one real task from inventory to evidence.
Eleven sections that treat the repository as the control plane for agent work. It starts from one costly, recurring task and follows it through the five context layers, the routes that load them, the budget that bounds them, the controls that secure them, and the evidence that closes them. Written for staff and senior engineers, platform and developer-productivity teams, repository architects, and technical engineering leaders — with four reading paths so you can design, diagnose, secure parallel work, or drive adoption without reading front to back.
Every component is a decision, not a diagram: trees answer where context belongs, matrices answer when it loads, contracts answer what a stage must produce, diagnostics answer why a run drifted, and scorecards answer where to invest next. A fictional Northstar Platform carries the same task, paths, and owners across all eleven sections. The guide deliberately publishes no universal token threshold and no measured efficiency claims — where a benefit is expected it names the mechanism and the evidence to collect locally, and every external claim is dated and cited.
What's inside
- Sections 1–2 · The repository as a control plane, the five context layers with their loading rules, boundary tests, and a layer placement decision table
- Sections 3–4 · A six-step inventory procedure with worksheet and contradiction register, plus inheritance rules, good/bad root files, and an oversized-root diagnostic
- Section 5 · Progressive disclosure — the task-plus-path routing matrix, a routing table starter, route records, and a route verification checklist
- Sections 6–7 · A mechanism decision matrix for contracts, maps, skills, and connectors, local vs. remote trust boundaries, a context budget worksheet, and a freshness and ownership registry starter
- Sections 8–9 · Conflict resolution and drift diagnostic tables, a three-layer validation pipeline, security classification, and multi-agent lane isolation with handoff contracts
- Section 10 · Four reference architectures — small application, product monorepo, multi-service platform, and enterprise repository portfolio — with a pattern selection guide
- Section 11 · An eleven-dimension context architecture scorecard out of 44, remediation priority ranking, and a four-week rollout sequence with weekly exit evidence
- Six tear-out reference cards for layer placement, routing, budget, drift, security review, and completion evidence
- 16 original diagrams, the Northstar Platform worked example carried across every section, and a claim-level ledger of 10 cited primary sources
Questions teams ask
What is Agent Context Architecture?
Agent Context Architecture is the practice of designing what an agent reads, ignores, produces, and proves so AI-assisted development becomes inspectable and repeatable. This guide treats the repository as the control plane and gives you the layers, routes, budgets, controls, and evidence gates that make it operable.
Does the guide give me a safe context-window fill percentage?
No, deliberately. No universal token threshold exists across tasks, models, toolchains, and repositories. The guide gives you a context budget worksheet and a ranking method so you calibrate your own envelope from controlled runs, and it publishes no measured efficiency claims — where a benefit is expected, it names the mechanism and the evidence to collect locally.
What can I actually apply on the first day?
Score your current system with the eleven-dimension scorecard, then run the four-week rollout against one recurring task: inventory it, route it, validate it, and measure it. The worksheets, registers, matrices, and six reference cards are built to be lifted straight into your own documents.
What is the difference between prompt engineering and AI Systems Engineering?
Prompt engineering tunes individual model requests. AI Systems Engineering designs the context, workflow gates, review loops, and operating memory that make AI-assisted work repeatable across a team.