Context Engineering for AI Agents: Building Context-Rich Environments

Every engineering leader has experienced this moment: you invest in AI coding tools, distribute licenses to your team, and wait for the promised productivity gains. A few weeks later, the results are underwhelming. Some developers love the tools; others abandon them entirely. The difference, it turns out, has nothing to do with the developers and everything to do with the context-rich AI environment those tools are operating in.

The principle is deceptively simple: garbage in, garbage out. An AI agent working with a poorly documented, inconsistently structured codebase will produce suggestions that are generic at best and dangerous at worst. The same agent working with a context-rich environment—where intent is explicit, patterns are documented, and constraints are clear—becomes something far more valuable: a genuine force multiplier for your engineering team.

This is not theoretical. Research published in late 2025 from Stanford and UC Berkeley demonstrated that AI model accuracy begins degrading significantly when context exceeds 32,000 tokens, and models particularly struggle to utilize information buried in the middle of large contexts—the “lost in the middle” problem. Even with Anthropic’s 1M token Claude models now generally available, the optimization target has shifted from “stuff more context” to maximize cache hit rate and signal density. You cannot simply throw more documentation at an AI and expect better results. You must design agent environments that communicate effectively with these systems.

The Context Engineering Framework: Five Layers

Before diving into tactics, engineering leaders need a mental model. Context engineering for AI agents is not a single artifact (AGENTS.md) or a single technique (RAG). It is a stack of five layers that each shape what the agent sees, remembers, and can do.

graph TD
    A[Agent Environment] --> B[1. System Prompt and Persona]
    A --> C[2. Repository Context]
    A --> D[3. Tool Surface MCP]
    A --> E[4. Memory and Sessions]
    A --> F[5. Observability and Eval]
    B --> B1[Role, constraints, output format]
    C --> C1[AGENTS.md, types, tests, ADRs]
    D --> D1[MCP servers, tool search, code execution]
    E --> E1[Compaction, sub-agents, persistent memory]
    F --> F1[Traces, token cost, cache hit rate]

The teams that win with agents in 2026 are not the ones with the longest prompts—they are the ones who treat each of these layers as a deliberate engineering surface. This is exactly what metacto’s Enterprise Context Engineering practice is built around.

Why Context Is the Critical Variable for AI Success

AI coding assistants do not understand your code the way a human developer does. They process text, recognize patterns, and generate statistically probable completions. When a human joins your team, they absorb tribal knowledge through conversations, code reviews, and the gradual accumulation of context. An AI agent starts every session with near-zero institutional memory. It only knows what you explicitly tell it or what it can infer from the files it can access.

This is why two teams using identical AI tools can have radically different experiences. One team operates in a context-poor environment where the AI must constantly guess at conventions, reinvent patterns, and generate code that technically compiles but violates architectural principles. The other team has invested in context-rich AI infrastructure that gives the agent everything it needs to make informed suggestions.

The business case is straightforward. According to industry data, development and coding activities have the highest AI adoption rates precisely because the impact is measurable. But that measurable impact only materializes when context is properly engineered. Without it, you are paying for AI licenses that deliver a fraction of their potential value. This is why implementing AI tools strategically requires attention to the environment, not just the tool itself.

Layer 1 and 2: The Anatomy of a Context-Rich Codebase

A context-rich codebase is not one with more documentation—it is one where the right information is discoverable, structured for machine consumption, and placed where AI tools can find it when needed.

Agent Memory Files: AGENTS.md as the 2026 Standard

The emergence of standardized agent memory files represents a fundamental shift. In December 2025, AGENTS.md was donated to the Agentic AI Foundation under the Linux Foundation. By early 2026 it is read natively by Claude Code, OpenAI Codex CLI, Cursor, Aider, Devin, GitHub Copilot, Gemini CLI, Windsurf, and Amazon Q—making it a universal agent instruction format.

But—and this is the 2026 update most teams miss—more AGENTS.md is not better. Research by Gloaguen et al. (2026) evaluated 138 real-world repositories and found that LLM-generated context files actually reduced agent task success rates while increasing inference cost by over 20%. Developer-written context files, by contrast, provided a +4% lift—but only when minimal and precise.

A well-crafted AGENTS.md should include:

The key insight from practitioners is that these files should contain only information the AI cannot infer from the code itself. Generic instructions like “write clean code” waste precious context tokens. Specific instructions like “this project uses the Result pattern for error handling—see src/utils/result.ts for the implementation” provide actionable guidance.

File-Scoped Documentation and Sub-Agent Routing

The most sophisticated teams are moving toward file-scoped documentation—.instructions.md files with YAML frontmatter specifying which files or directories they apply to. Combined with Anthropic Sub-agents (specialized agents that handle a slice of work with their own focused context), this lets you route different parts of your codebase to different reasoning contexts.

For example, your payment processing module might use a payments-reviewer sub-agent loaded with PCI constraints, while UI components route to a frontend sub-agent loaded with design-system rules. The parent agent delegates; sub-agents return concise findings. The result: each layer of the stack sees only the context for LLMs that is actually relevant to its task.

Type Systems and Inline Comments as Context

Here is a principle that often surprises engineering leaders: your type system is one of your most powerful AI context tools.

Strong typing provides machine-readable constraints that AI agents use to generate more accurate code. A function signature like processData(data: any): any tells an AI almost nothing. A signature like transformUserProfile(profile: UserProfile): APIResponse<TransformedProfile> communicates input expectations, output structure, and error handling patterns through the types alone.

The same principle applies to comments. AI systems analyze comments through semantic analysis, attempting to discern not just what code does but why it does it. The key is commenting for context, not for description.

graph TD
    A[Comments] --> B[Low Value: What]
    A --> C[Medium Value: How]
    A --> D[High Value: Why]
    B --> B1["// Add 1 to x"]
    C --> C1["// Use binary search for O log n"]
    D --> D1["// Retry 3x because payment API is flaky"]
    D1 --> E[AI generates retry logic correctly]
    B1 --> F[AI generates generic increments]

Test Suites: Your AI’s Behavioral Specification

Perhaps the most underutilized context for LLMs is your test suite. Tests are executable documentation—they specify exactly how your system should behave in concrete, verifiable terms. AI tools leverage existing tests to understand:

• Expected behavior patterns for similar functionality
• Mocking strategies your team prefers
• Edge cases that matter for your domain
• Integration boundaries between components

When an agent generates new code, a comprehensive test suite provides immediate feedback on whether the suggestion actually works. This creates a rapid iteration loop: generate, test, refine. Without tests, the loop breaks—generated code may look correct but fail in subtle ways that only surface in production.

Layer 3: The Tool Surface and MCP Context Engineering

In 2024, agents struggled because they could not act. In 2026, they struggle because they can act on too many tools. This is where the Model Context Protocol (MCP) changed the game—and where MCP context engineering became its own discipline.

What Changed in MCP in 2025–2026

• November 2025 spec release introduced asynchronous operations, statelessness, server identity, and official extensions.
• December 2025: Anthropic donated MCP to the Agentic AI Foundation (a Linux Foundation directed fund co-founded with Block and OpenAI). MCP is now a vendor-neutral standard.
• OpenAI announced full MCP support across the Agents SDK, Responses API, and ChatGPT desktop app.
• Streamable HTTP and OAuth 2.1 are now part of the spec, making MCP production-safe for enterprise.
• Anthropic shipped Tool Search and Programmatic Tool Calling in the API, allowing agents to discover tools dynamically across thousands of available MCP servers without loading every definition into context.
• Code execution with MCP lets agents load tools on demand, filter data before it reaches the model, and execute complex logic in a single step—dramatically reducing token cost on multi-step workflows.

Designing a Lean Tool Surface

The trap most teams fall into: connecting every MCP server in the directory, then watching token budgets explode. The 2026 best practice is the opposite—curate a small set of high-signal tools per agent, and use Tool Search to expose the long tail.

This is core to agent observability and context optimization: every tool in the surface is a tax on the context window. Treat it like a permission system.

Layer 4: Memory, Compaction, and Sub-Agents

The hardest problem in agent systems is what to remember. Anthropic’s 2026 shipping cadence reshaped the answer. For a vendor-neutral design reference, see our guide to AI agent memory architecture in production.

Memory for Managed Agents (April 2026)

Anthropic launched Memory for Managed Agents in public beta on April 23, 2026. It stores what agents learn across sessions as files, with per-write audit logs, programmatic access, and the ability for one agent to share findings with other agents in the same workspace. Rakuten reported a 97% error rate reduction in early benchmarks—not because the model got smarter, but because the agent stopped re-learning the same lessons every session.

A key architectural innovation: the session log lives outside Claude’s context window. The agent can interrogate it via getEvents()—picking up from where it stopped, rewinding, or re-reading context before a specific action. This avoids irreversible compaction decisions about what to keep.

Context Compaction

Compaction is the practice of taking a conversation nearing the context window limit, summarizing its contents, and reinitiating with that summary. Anthropic has formalized three techniques to manage context pollution:

1. Compaction — distill long conversations into high-fidelity summaries
2. Structured note-taking — agent writes intermediate findings to files, not to context
3. Multi-agent architectures — delegate to sub-agents with fresh, focused contexts

Since the 1M context window shipped, real Claude Code usage has shown a 15% decrease in compaction events. Agents now hold their full context and run for hours without forgetting what they read on page one. But this is a ceiling, not a free lunch—token cost still scales with context size, and context optimization remains the lever for ROI. We cover window budgeting and compaction strategies in depth in LLM context management in production.

Layer 5: Agent Observability and Evaluation

You cannot improve what you cannot see. The 2026 agent observability stack matured rapidly, with platforms like Opik (Comet), Langfuse, LangSmith, Arize Phoenix, Braintrust, Datadog LLM Observability, MLflow, and Galileo now offering end-to-end visibility into every step an agent takes in production—LLM calls, tool invocations, retrieval steps, and planning decisions.

The metrics that matter for context engineering:

• Cache hit rate — the new north star. Optimization target has shifted from “minimize context size” to “maximize cache hit rate” since most providers now support prompt caching.
• Token efficiency by context construction strategy — which AGENTS.md, which sub-agent, which tool set wins per task class
• Cost per run and latency by tool type — exposes expensive MCP tools and runaway loops
• Success rate by query domain — reveals where your context is failing
• Compaction events per session — a proxy for context-budget pressure

Without this telemetry, every context-engineering change is a guess. With it, you have a feedback loop.

Documentation That AI Agents Can Actually Use

Modern AI coding assistants increasingly use Retrieval-Augmented Generation (RAG) systems that search your documentation to find relevant context before generating responses. This means your documentation needs to be structured for searchability and chunking.

Effective documentation for AI retrieval:

• Uses clear, descriptive headings that match common query patterns
• Keeps sections self-contained so individual chunks provide complete context
• Avoids excessive cross-referencing that requires following multiple links to understand a concept
• Includes code examples inline rather than in separate files

Before and After: Context-Poor vs Context-Rich Agent Environments

Let me illustrate the practical difference with a concrete example. Imagine you are asking an AI agent to add a new API endpoint to your application.

Context-Poor Environment

The agent has access to:

• Source files with minimal comments
• No architecture documentation
• No AGENTS.md or CLAUDE.md
• Generic README with installation instructions only
• No type definitions (JavaScript with any types)
• Every MCP tool in the catalog, undifferentiated
• No persistent memory between sessions

The agent generates a technically valid endpoint, but it:

• Uses a different error handling pattern than existing endpoints
• Implements authentication differently than the rest of the application
• Returns responses in a format inconsistent with your API standards
• Places the file in a location that violates your project structure
• Includes no tests (because there are no existing patterns to follow)
• Burns through token budget on irrelevant tool calls

Context-Rich Environment

The agent has access to:

• A lean AGENTS.md specifying “all API endpoints must use the ApiResponse wrapper from src/utils/api-response.ts”
• Type definitions for request and response structures
• Existing endpoint files with consistent patterns
• Architecture documentation showing the controller → service → repository pattern
• Test files demonstrating the expected testing approach
• A curated MCP surface—database, internal API, logging—and nothing else
• Persistent memory carrying lessons from prior endpoint reviews
• A backend-reviewer sub-agent that checks the work before commit

The agent generates an endpoint that:

• Follows your established patterns automatically
• Uses correct error handling and response structures
• Includes appropriate types for all parameters
• Comes with test stubs matching your testing conventions
• Integrates seamlessly with existing code
• Costs a fraction of the tokens

The difference is not marginal—it is the difference between AI that creates technical debt and AI that eliminates it.

How metacto Builds AI-Optimized Agent Environments

At metacto, we have spent the last several years helping organizations move beyond ad-hoc AI adoption toward strategic enablement. Our experience building and integrating AI solutions across hundreds of projects has shown us that context engineering for AI agents is not optional—it is foundational to realizing AI’s value. This is the work of our Enterprise Context Engineering practice: making your systems legible to AI so agents can act with the same fidelity as your best engineers.

Our approach includes:

AI Maturity Assessment: Using our AI-Enabled Engineering Maturity Index, we evaluate your current state across all eight SDLC phases and identify specific gaps in your context infrastructure. Most organizations discover they are operating at a “reactive” level where AI tool usage is unstructured and results are inconsistent.

Codebase and Agent-Environment Audit: We analyze your existing documentation, type coverage, test suite, MCP tool surface, AGENTS.md hygiene, and memory strategy to identify high-impact improvements. Often, a small investment in agent memory files and targeted documentation yields outsized returns.

MCP and Sub-Agent Architecture: We design lean, scoped tool surfaces and sub-agent topologies that prevent context bloat and give each agent the focused context it needs to do one thing well.

Process Integration: Context engineering is not a one-time project—it requires integration into your development workflow. We help teams establish practices where context documentation, evals, and observability are maintained alongside code, not as an afterthought. Our AI development services include ongoing support to keep your context infrastructure current.

Measurement and Optimization: We implement agent observability—traces, cache hit rate, token cost per run, compaction events—so refinement is data-driven, not vibes-based. Suggestion acceptance rate, time to first meaningful contribution, and code review feedback provide objective measures of improvement.

The teams that excel with AI tools are not those with the most advanced models or the largest context windows—they are those that have invested in making their codebases legible to AI systems. Context engineering transforms AI from a novelty into a genuine competitive advantage. For organizations needing strategic guidance on this transformation, our Fractional CTO services provide the technical leadership to build context-rich environments that scale.

Sources:

• Effective context engineering for AI agents - Anthropic
• Donating the Model Context Protocol - Anthropic
• Code execution with MCP - Anthropic Engineering
• Context engineering: memory, compaction, and tool clearing - Claude Cookbook
• Anthropic Managed Agents Add Memory - OpenTools
• AGENTS.md Complete Guide for Engineering Teams (2026) - BuildBetter
• Context Engineering Best Practices for AI-Powered Dev Teams (2026) - Packmind
• AI Agent Observability: A Complete Guide for 2026 - Atlan
• Everything your team needs to know about MCP in 2026 - WorkOS
• Writing a Good CLAUDE.md - HumanLayer
• How AI Assistants Interpret Code Comments - Glean