5-level context: System, Code, Org, Historical, Operational

When an AI agent makes a bad suggestion, the cause is almost always a context gap: the agent was missing information it needed to reason correctly. But "the agent needs more context" is not an actionable diagnosis. The 5-level context framework provides a structured vocabulary for describing exactly what kind of context is missing - and therefore what specific investment would fix it.

The five levels are:

1. System-level context - The architecture and infrastructure of the system: how services are deployed, what infrastructure they run on, how they communicate, what the scalability and reliability constraints are. An agent working on a microservice without system-level context doesn't know whether it's a standalone service or one of two hundred in a mesh. It doesn't know if horizontal scaling is available or if there's a single-region constraint.

2. Code-level context - The codebase itself: module structure, dependency graph, existing abstractions, test patterns, build conventions. Code-level context is what IDE tools naturally provide - file contents, imports, definitions. The agent can read the files, but it can only read what fits in its context window.

3. Org-level context - Team structure, ownership maps, who to contact for what, what teams' current priorities are, what's in-progress vs. completed. An agent that doesn't know that the authentication team owns the auth-service might modify that service in a way that's technically correct but violates a team boundary.

4. Historical context - Why decisions were made: Architecture Decision Records (ADRs), git commit history with meaningful messages, design documents, post-mortems. An agent that doesn't know a particular pattern was explicitly rejected three years ago after a production incident will confidently re-suggest the rejected pattern.

5. Operational context - The current state of the running system: deployment status, error rates, latency metrics, recent incidents, on-call alerts. An agent working on code related to a currently-degraded service needs to know the service is degraded - and why - to make safe suggestions.

At L3 (Systematic), organizations have identified which of these context types they're providing and which they're not, and are systematically building the infrastructure to provide all five.

The framework is diagnostic. When an agent makes a bad suggestion, you can classify the failure by context level:

• Agent suggested a pattern we explicitly rejected in 2022 → Historical context gap → fix: ADRs in context
• Agent modified a service owned by another team without coordination → Org-level context gap → fix: ownership data via MCP
• Agent didn't account for the fact that this runs on single-region infrastructure → System-level context gap → fix: infrastructure documentation in CLAUDE.md
• Agent created a utility function that already exists in a shared library → Code-level context gap → fix: better codebase indexing, RAG over the repo
• Agent suggested adding caching to a service that's currently in a degraded state due to a memory leak → Operational context gap → fix: production telemetry in context

Without this framework, context gaps get described as "the AI is bad" - which leads to no actionable fix. With the framework, they become specific infrastructure investments.

The five levels also map naturally to the maturity progression: L2 provides basic Code-level context (CLAUDE.md with project info). L3 systematically addresses all five levels. L4 automates context assembly. L5 makes context self-maintaining.

A June 2026 shift changed how Code-level context is best retrieved: memory beyond RAG. Anthropic dropped vector search in Claude Code in favour of agentic grep and tool-search, and Microsoft's FastContext (June 15) uses a repo-explorer subagent that returns compact file-line citations and cuts coding-agent tokens by up to 60%. The lesson: assembling more context is not free, and an overstuffed window degrades reasoning. Treat context as a budget - pruning unused skills and MCP servers recovers 24%+ of the window - and prefer on-demand retrieval (grep, scoped subagents) over pre-loading everything for the levels that change fast.

1. Audit your current context coverage - For each of the five levels, ask: does the agent have reliable access to this type of context? Rate each level: none, partial, or systematic.
2. Identify your biggest gap - The level with "none" coverage is your starting point. Don't try to address all five levels at once.
3. Build Code-level context first - If you haven't done L2 work, start there. CLAUDE.md with architecture overview and conventions is the foundation. Everything else builds on it.
4. Add Historical context via ADRs - Start writing Architecture Decision Records for new decisions. Retroactively write ADRs for the three most consequential historical decisions. Store them in the repository where agents can find them.
5. Connect Org-level and Operational context via MCP - These change too fast to maintain in static files. Build MCP servers that expose service ownership and deployment status from your existing operational tools.
6. Validate each level with a probe question - Test each context level by asking the agent a question that requires it. "Who owns the auth service?" tests Org-level. "What's the current deployment status of the payments service?" tests Operational. "Why don't we use Redis for session storage?" tests Historical. Gaps become visible immediately.

Treating Code-level context as the only kind that matters. Teams that have done good L2 work often stop there - they've improved autocomplete and basic agent suggestions, and declare success. But for agents tackling larger tasks, the other four context levels are equally important. Code-level context alone doesn't prevent the agent from violating team ownership, ignoring historical decisions, or making unsafe changes to degraded services.

Confusing context level with information priority. Operational context is not more important than Historical context - they're different dimensions of the same picture. An agent that has excellent operational context but no Historical context will make safe suggestions about the current system state while confidently repeating patterns that were explicitly rejected years ago.

Trying to provide all five levels through static files. System-level and Code-level context can live in CLAUDE.md. Org-level, Historical, and Operational context changes faster than static files can keep up with. Organizations that try to maintain these as static documents spend significant effort on a losing battle. MCP servers are the right infrastructure for dynamic context.

Not measuring context quality by level. If you track agent suggestion quality as a single number, you can't tell which context level is causing failures. Separate your quality metrics: how often does the agent make architectural errors (System), violation-of-conventions errors (Code), team boundary violations (Org), repeated historical mistakes (Historical), and operationally unsafe suggestions (Operational)?