Capability 02 of 04 · Development
Context Engineering
What information agents receive about your codebase, architecture, and conventions.
5
maturity levels
15
practices
15
guides
L1 · Stage 01Ad-hoc
Practices - what it looks like3 guides
- Agent works from the currently open fileWhy AI agents at L1 are flying blind - they see only the open file, with no awareness of your project's architecture, conventions, or dependencies.guide→
- Project knowledge lives with people, not docsAt L1, the rules governing your codebase live in developers' memories - invisible to AI agents, fragile under turnover, and impossible to scale.guide→
- Onboarding leans on the existing README and peopleStale documentation is more than a developer experience problem - it actively prevents AI agents from using docs as context and signals that the team hasn't invested in machine-readable knowledge.guide→
Criteria - what to measure
- 01The agent can read the file(s) the developer is working on
- 02Developers can supply the agent with project context when needed
- 03README.md exists (may be incomplete)
- 04Developers manually paste context into AI chat when needed
L2 · Stage 02Guided
Practices - what it looks like3 guides
- CLAUDE.md with basic project infoAdding a CLAUDE.md to your repository root is the single highest-leverage context engineering investment - it gives every AI agent the minimum viable information about what your project is and how it works.guide→
- Written coding conventionsDocumenting your team's semantic coding decisions - not just style rules - gives AI agents the judgment framework they need to suggest code that fits your architecture, not just code that compiles.guide→
- Agent instruction files + Skills as the unit of reuse (SKILL.md alongside CLAUDE.md, AGENTS.md, llms.txt; official skill-packs from Apple/NVIDIA/Cloudflare)Agent instruction files - CLAUDE.md, .cursorrules, copilot-instructions.md - have become a standard software project artifact, with 60,000+ repositories on GitHub already containing them.guide→
Criteria - what to measure
- 01CLAUDE.md or equivalent exists with project description, tech stack, and top conventions
- 02Written coding conventions document exists and is referenced from agent instruction files
- 03Agent instruction files are committed to the repository (not local-only)
- 04CLAUDE.md includes explicit prohibitions (banned libraries, anti-patterns)
- 05Agent instruction files are reviewed as part of the standard PR process
L3 · Stage 03Systematic
Practices - what it looks like3 guides
- MCP servers: architecture, ownership, SLA (universal standard)Model Context Protocol servers are the infrastructure layer of context engineering at L3 - dedicated services that give AI agents structured, real-time access to your organization's knowledge.guide→
- Memory beyond RAG: agentic grep/tool-search + repo-explorer subagent (FastContext) over vector DBs (Anthropic dropped embeddings in Claude Code)A structured framework for the five types of context an AI agent needs to make good decisions - and a diagnostic tool for understanding why your agents keep getting things wrong.guide→
- Context budgeting + automatic compaction (handoff.md, .claudeignore, Rewind summarize, Amp auto-compact at 90%); prune unused skills/MCP (recovers 24%+ context)AI models have finite context windows - context budgeting is the practice of deliberately allocating that budget across context types to maximize agent effectiveness per token spent.guide→
Criteria - what to measure
- 01MCP servers provide structured context (architecture, ownership, SLAs) to agents
- 02Context is organized across at least 3 of the 5 levels: System, Code, Org, Historical, Operational
- 03Token budget management is implemented (agents receive context within defined token limits)
- 04Context sources are versioned and tested for correctness
- 05Context budgeting policy defines priority order when token limits are reached
L4 · Stage 04OptimizedMost teams aim here
Practices - what it looks like3 guides
- BYOC: org PUSHES context to the agentAt L4, organizations flip the context model - instead of agents pulling context on demand, the org pre-assembles and pushes a rich context package to agents at task start, eliminating discovery latency and ensuring consistency.guide→
- Knowledge graph (Graph Buddy / CodeTale / pitlane-mcp)Semantic knowledge graphs of codebases - built by tools like Graph Buddy and CodeTale - give AI agents structural understanding of your codebase without requiring them to read every file.guide→
- Spec-Driven Development: AGENTS.md as shared spec interface (Andrew Ng + JetBrains, Thoughtworks)At L4, AI agents transform Jira or Linear tickets into structured specifications and failing acceptance tests before a developer touches the implementation - creating a context artifact that guides the entire downstream workflow.guide→
Criteria - what to measure
- 01Organization pushes context to agents automatically (BYOC - Bring Your Own Context)
- 02Knowledge graph (Graph Buddy, CodeTale, or equivalent) is integrated with agent context pipeline
- 03Ticket-to-spec automation generates acceptance tests from requirements without manual writing
- 04Context push triggers on repository events (commit, PR, deploy) without manual refresh
- 05Knowledge graph covers 80%+ of active repositories
L5 · Stage 05Autonomous
Practices - what it looks like3 guides
- Persistent agent identity + memory (Beads/Git, Dreaming / Kairos 4-stage consolidation)At L5, agents maintain persistent identity and memory across sessions using structured memory files committed to git - accumulating codebase-specific institutional knowledge that makes them progressively more effective over time.guide→
- Production telemetry → context auto-updateAt L5, agent context updates automatically based on production signals - when a service degrades, agents working on related code receive updated operational context without manual intervention.guide→
- Self-healing context: agent detects stale docs, updatesAt L5, agents monitor context quality continuously - detecting when CLAUDE.md entries, README sections, or architecture diagrams no longer match the codebase, and automatically proposing or applying updates.guide→
Criteria - what to measure
- 01Agents maintain persistent identity and memory across sessions (Beads/Git-backed)
- 02Production telemetry feeds back into agent context automatically (deploy, error, performance data)
- 03Agents detect stale documentation and update it without human initiation
- 04Agent memory persists architectural decisions and their rationale across sessions
- 05Self-healing context updates are validated by automated tests before commit
From the Field
Recent releases, projects and discussions the AI Radar classified into this capability.
release
article
Anthropic Removed MagicDocs from Claude Code
discovered
Model-agnostic code memory MCP server. Budget-aware graph retrieval for AI agents. Sub-millisecond queries, token budgeting, deterministic results. Built o
discovered
Practical OpenClaw tips for memory, reliability, cost, automation, and multi-agent workflows.
discovered
Comprehensive guide to AI agent engineering: how 30+ frameworks actually work under the hood. Context rot, compaction, system prompt assembly, SOUL.md, age
discovered
A fast codebase indexer and MCP server for AI coding agents.
discovered
SUPERCHARGE AI-assisted development by using Git. Cross-model review gates, evidence-linked closure, verification profiles, model-tier routing, artifact envelopes, an
discovered
Agent skill for color science expertise. Many references covering color spaces, accessibility (APCA, WCAG), palette generation, pigment mixing, and historica
Which level is your team at in Context Engineering?
The criteria above are what we check in a facilitated assessment. Run it yourself to place this capability, see which gates you have passed, and compare it against the other 3 in Development.
Start the assessment →