Design Patterns
WorkflowIntermediate

Context-First Architecture

How to structure a Context Index, assemble Context Packets, and establish context engineering practices for agentic teams.

Overview

Context-First Architecture is a structural pattern that treats context as the primary engineering artifact in an agentic workflow. Instead of relying on ad-hoc prompts and scattered documentation, teams build a Context Index — a structured, versioned collection of specifications, standards, examples, and historical records that agents consume before generating any code.

The core insight behind this pattern is that agent output quality is bounded by context quality. A capable model with poor context produces poor results. A less capable model with well-structured context consistently outperforms it. Context Engineering is the discipline of designing, maintaining, and delivering context to maximize agent effectiveness.

Problem

Teams adopting AI agents encounter a predictable degradation pattern:

  • Inconsistent output quality. The same task assigned to the same agent produces different results on different days because context is supplied differently each time — different files mentioned, different phrasing, different assumptions left implicit.
  • Scattered documentation. Project knowledge lives across READMEs, wiki pages, Slack threads, code comments, and engineers' heads. No single source aggregates what an agent needs to do its work correctly.
  • Hallucination from context gaps. When agents lack information about architecture constraints, naming conventions, or API contracts, they fill the gap with plausible but incorrect assumptions. These subtle errors pass initial review and surface as bugs later.
  • Session amnesia. Agent sessions are ephemeral. Knowledge provided in one session does not carry to the next. Engineers waste time re-supplying the same context repeatedly.
  • Scaling failure. What works for one developer chatting with one agent breaks when a team runs multiple agents in parallel. Without a shared context source, agents produce conflicting implementations.

Solution

Build a Context Index as the single source of truth that all agents draw from. The Context Index is a directory structure within the repository that organizes context into well-defined categories. For each unit of work, assemble a Context Packet — a curated subset of the Context Index scoped to a specific task — that the agent receives alongside its Live Spec.

The Context Architect role owns the Context Index. This person (or combined role) is responsible for auditing, structuring, maintaining, and evolving the context over time. Context is treated like code: it is versioned, reviewed in pull requests, tested for staleness, and measured for effectiveness.

The five components of a Context Index are:

  1. Live Spec collection — Behavioral contracts, acceptance criteria, and task maps for current and planned work
  2. System Constitution — Project-wide rules that apply to every task: coding standards, framework constraints, security policies, naming conventions
  3. Codebase Context — Type definitions, API contracts, architecture decision records, dependency maps
  4. Historical Context — Past decisions, deprecated approaches, known pitfalls, migration records
  5. Golden Samples — Exemplary implementations that demonstrate expected quality, structure, and style

Implementation

1

2

3

4

5

Considerations

Benefits
  • • **Higher Spec-to-Code Ratio.** When agents receive well-structured context, a larger proportion of their output directly implements the specification rather than improvising around context gaps.
  • • **Fewer Rescue Missions.** Teams with a maintained Context Index report fewer cases where agent output requires significant human intervention to salvage. The [[rescue-mission]] rate drops because agents start from a better foundation.
  • • **Compound improvement.** Unlike prompts (which are ephemeral), the Context Index accumulates value over time. Each spec authored, each golden sample added, and each constitution rule documented improves every future agent run.
  • • **Onboarding acceleration.** New team members and new agents both benefit from the same Context Index. The ramp-up period shortens because project knowledge is explicit and structured rather than tribal.
  • • **Measurable quality.** The [[spec-to-code-ratio]] and [[eval-harness]] pass rates provide objective data on context effectiveness. Teams can identify and fix specific context gaps rather than guessing at prompt improvements.
Challenges
  • • **Initial setup effort.** Building the Context Index from scratch requires significant upfront work — auditing existing sources, writing documentation, selecting golden samples. Teams should start with one domain and expand incrementally.
  • • **Maintenance burden.** Context must stay current with the codebase. Without the monthly Context Hygiene cycle, the Context Index becomes a liability instead of an asset. The [[context-architect]] role must have dedicated time for this work.
  • • **Context window limits.** Even well-curated context competes for space in the model's [[token-budget]]. Teams must make deliberate decisions about what to include and what to leave out for each task. This requires judgment and iteration.
  • • **Cultural adoption.** Engineers accustomed to direct coding may view context authoring as overhead rather than engineering. Teams must reframe context as a first-class artifact — as important as code and tests.
  • • **Tooling gaps.** The ecosystem for context management is still maturing. Teams may need to build custom tooling for context assembly, token budgeting, and staleness detection until standard tools emerge.