How to Implement Context Engineering for AI Coding Agents

The third time the agent rewrote the same database migration incorrectly, Mara stopped blaming the model. Her team at a mid-size fintech had adopted Claude Code three months earlier. Throughput was up. But one pattern kept failing: anything touching the payments schema. The agent didn't know that a 2023 incident had locked two columns behind a manual approval gate. It wasn't in the code. It was in a post-mortem buried in Confluence and a Slack thread from eighteen months ago.

Mara didn't need a better prompt. She needed a context engineering implementation that would surface the right institutional knowledge before the agent started writing code. What she built over six weeks is roughly what this guide walks through: five steps from failure audit to measured iteration.

We've seen this scenario repeated across dozens of engineering teams. The agent produces code that compiles, passes linting, and still fails review because it violates an unwritten rule that lives outside the codebase.

For foundational concepts, start with our context engineering guide.

---

What does a context engineering implementation actually involve?#

Implementing context engineering for AI agents means building systems that deliver the right institutional knowledge before the agents act. JetBrains' 2025 Developer Ecosystem Survey found that 76% of developers using AI assistants still manually verify output before committing it (JetBrains, 2025). That verification tax is what a proper implementation eliminates.

Implementing context engineering connects an AI coding agent to institutional knowledge, including code history, design decisions, incident records, and team conventions, so the agent produces reviewable output on the first run. JetBrains' 2025 survey found 76% of developers still manually verify AI output before committing (JetBrains, 2025).

The work breaks into five layers. First, you identify where agents fail today. Most failures cluster around three to five recurring patterns, not hundreds. Second, you map the knowledge sources that contain the missing context. Third, you build retrieval that ranks and shapes those sources for the agent's task. Fourth, you add conflict resolution and access controls. Fifth, you measure whether the implementation actually reduced rework.

This isn't a weekend project, but it's not a six-month infrastructure bet either. Teams we've talked to typically start with a single failure mode and expand from there.

For definitions and deeper context, see what is context engineering.

---

Step 1: Audit where your agents fail today#

McKinsey's 2025 research on AI in software development found that developers using AI coding tools reported productivity gains of 20-45%, but those gains eroded significantly when agents lacked project-specific context (McKinsey, 2025). The audit step identifies exactly where that erosion happens on your team.

McKinsey's 2025 research found AI coding productivity gains of 20-45% erode significantly when agents lack project-specific context (McKinsey, 2025). Auditing agent failures reveals the specific knowledge gaps causing rework.

Don't start by cataloging all your knowledge. Start by cataloging all your failures. Pull the last 30 days of PRs where an AI agent contributed code that required significant rework during review. Tag each failure with a root cause category.

What failure categories should you track?#

The categories that matter most are ones where the agent was missing institutional knowledge, not where the model itself was confused. Common categories include:

• Convention violations: The agent wrote valid code that broke an internal style or pattern rule
• Stale context: The agent used a deprecated API, function, or workflow
• Missing history: The agent didn't know about a prior incident, migration, or architectural decision
• Permission gaps: The agent accessed or modified something it shouldn't have
• Cross-repo blindness: The agent changed code in one service without understanding downstream effects

In conversations with engineering teams running AI agents at scale, we've found that 60-80% of agent failures fall into just two or three of these categories. One team discovered that "missing incident history" alone accounted for 40% of their rework. That's where they started.

How do you prioritize which failures to fix first?#

Rank failures by rework cost, not frequency. A failure that happens twice a month but triggers a full day of rework outranks a daily failure that takes five minutes to fix. Multiply frequency by average rework hours to get a simple priority score.

For more on agent failure patterns, see stop babysitting your agents.

---

Step 2: Map your institutional knowledge sources#

Google's 2025 DORA report found that AI adoption correlates with declining software delivery stability when organizations lack structured knowledge practices (Google DORA, 2025). Knowledge mapping is how you structure what your agents need to know.

Google's 2025 DORA report found AI tool adoption without structured knowledge practices correlates with declining delivery stability (Google DORA, 2025). Mapping institutional knowledge sources is the prerequisite for any context engineering implementation.

Once you know which failure modes to target, trace each one back to its knowledge source. Where does the information live that would have prevented the failure? This is rarely a single system.

Which knowledge sources matter most?#

For most engineering teams, institutional knowledge scatters across five to eight systems:

• Code repositories: Not just the code itself, but commit history, PR discussions, and review comments
• Documentation platforms: Confluence, Notion, internal wikis, ADRs (architecture decision records)
• Communication tools: Slack threads, Teams messages, email chains where decisions were made
• Issue trackers: Jira, Linear, GitHub Issues, including closed tickets with resolution context
• Incident management: Post-mortems, runbooks, on-call notes, status page history

The Anthropic context engineering guide emphasizes that agents need "the right information, in the right shape, at the right time" (Anthropic, 2025). Shape matters as much as availability. A raw Confluence page dumped into a prompt is available but not shaped for the task.

How do you assess source quality?#

Not all knowledge sources are equally reliable. Rate each source on three dimensions:

1. Freshness: When was it last updated? Documentation older than six months is suspect.
2. Authority: Who wrote it? A post-mortem authored by the on-call engineer carries more weight than a wiki page with an unknown author.
3. Accessibility: Can a retrieval system programmatically access it, or is it locked in someone's head?

What about the knowledge that isn't written down anywhere? Every organization has tribal knowledge, the kind of context that lives in senior engineers' heads. That knowledge needs to be captured, even partially, before it can be retrieved.

Read more about what qualifies as decision-grade context.

---

Step 3: Build the retrieval and ranking layer#

Stanford HAI's 2025 AI Index reported that AI systems still struggle with complex, multi-step reasoning and factual grounding despite benchmark gains (Stanford HAI AI Index, 2025). A retrieval and ranking layer compensates for this by pre-filtering context so the agent receives only what's relevant and trustworthy.

Stanford HAI's 2025 AI Index found AI systems still struggle with multi-step reasoning and factual grounding despite benchmark gains (Stanford HAI AI Index, 2025). A retrieval and ranking layer pre-filters context so agents receive only relevant, trustworthy information for their specific task.

This is where the implementation diverges from basic RAG. Retrieval-augmented generation asks: "What documents are semantically similar to this query?" Context engineering asks: "What does this agent need to know to complete this specific task correctly?"

What's the difference between retrieval and ranking?#

Retrieval is finding relevant documents. Ranking is ordering them by authority, freshness, and task relevance. Both matter, but ranking is where most implementations fall short.

A naive retrieval system might surface five Confluence pages about your payments schema. A ranking layer would prioritize the post-mortem from 2023 over a planning document from 2021, because the post-mortem contains the constraint the agent needs to respect. It would also deprioritize a draft RFC that was never approved.

Most teams we've talked with treat retrieval and ranking as a single step. They shouldn't. Retrieval can be solved with off-the-shelf embedding models and vector search. Ranking requires domain-specific logic: recency weights, source-authority tiers, and task-type matching. Separating these two concerns makes the system easier to debug and iterate on.

How should you handle context window limits?#

Even with large context windows (200K+ tokens in current models), stuffing everything in degrades performance. The Stack Overflow 2025 Developer Survey found that 84% of developers use or plan to use AI tools, but only 33% trust the accuracy of those tools (Stack Overflow Developer Survey, 2025). Indiscriminate context is part of why trust is low.

Parsimony matters. Include only what's relevant to the current task. A good ranking layer acts as a filter, not a firehose. If your agent is modifying a database migration, it needs the schema history, the relevant post-mortems, and the team's migration conventions. It doesn't need your onboarding docs or your Q3 product roadmap.

For a deeper comparison of retrieval approaches, see our post on what a context engine actually is.

---

Step 4: Add conflict resolution and permission enforcement#

GitHub's 2025 Octoverse report found that over 1.4 million developers used Copilot regularly, but organizations with strict compliance requirements reported the slowest adoption rates (GitHub Octoverse, 2025). Permission enforcement is the implementation step that unlocks adoption in regulated environments.

GitHub's 2025 Octoverse report found organizations with strict compliance requirements had the slowest Copilot adoption rates (GitHub Octoverse, 2025). Adding permission enforcement unlocks AI agent adoption in regulated environments where context engineering for AI agents otherwise stalls.

This is the step most DIY implementations skip, and it's the one that blocks enterprise adoption. Two problems need solving here: what happens when knowledge sources contradict each other, and who is allowed to see what.

How do you handle conflicting information?#

Sources conflict constantly. A Confluence page says one thing. A Slack thread from last week says another. A code comment says a third. Your implementation needs explicit rules for resolving these conflicts.

Build a source hierarchy. In most organizations, it looks something like this:

1. Production code (current state of truth)
2. Post-mortems and incident records (learned constraints)
3. Approved ADRs (architectural decisions)
4. Team documentation (conventions, standards)
5. Slack and email threads (contextual, but unofficial)

When sources conflict, the higher-ranked source wins. This isn't perfect, but it's far better than letting the agent pick whichever source happened to score highest on semantic similarity.

Why does permission enforcement matter for context engineering?#

An agent that surfaces private HR data in a code suggestion has created a compliance incident, not a productivity gain. Permission enforcement means the retrieval layer respects the same access controls that apply to human users. If an engineer can't see a specific Jira ticket, the agent operating on their behalf shouldn't see it either.

We've found that permission enforcement is the single biggest differentiator between a proof-of-concept and a production deployment. Teams that skip it get impressive demos. Teams that build it get organizational buy-in.

Arthur Rodolfo, a Software Engineer at Clio, described how he handles this in practice: "I built a step called 'enrich' that runs before any code gets written. The agent asks Unblocked for everything, the ticket, the Slack context, what's been done in related repos, and then it starts implementing. It's especially powerful for cross-repository work where you'd otherwise have to do all that archaeology yourself."

For more on the architecture, see what is a context engine.

---

Step 5: Measure and iterate#

Gartner's 2025 research on AI engineering predicted that by 2027, 60% of organizations will have abandoned AI projects that lacked systematic feedback mechanisms (Gartner, 2025). Measurement isn't optional. It's what separates implementations that survive from implementations that get shelved.

Gartner predicted that by 2027, 60% of organizations will abandon AI projects lacking systematic feedback mechanisms (Gartner, 2025). Measuring outcomes through first-run acceptance rates and rework reduction determines whether the system survives past its pilot.

What metrics should you track?#

Four metrics tell you whether the implementation is working:

1. First-run acceptance rate: What percentage of agent-generated PRs pass review without major rework? This is your primary metric.
2. Rework hours per PR: How much time do reviewers spend correcting agent output? Track this before and after implementation.
3. Context hit rate: When the agent needed institutional knowledge, did the retrieval layer provide it? Measure by sampling failed PRs and checking whether the relevant knowledge was available.
4. Time to first reviewable PR: How long from task assignment to a PR that's ready for human review?

How often should you iterate?#

Weekly, at minimum. Review the PRs that still required rework. For each one, ask: did the retrieval layer provide the right context? If yes, the ranking or conflict resolution failed. If no, there's a knowledge source gap to fill.

Teams that run weekly context audits typically see first-run acceptance rates improve from 30-40% to 65-75% within the first two months of implementation. The gains aren't linear. They come in jumps as you close the two or three knowledge gaps that account for most failures.

---

What does this look like in practice?#

The Pragmatic Institute's 2025 AI product management survey found that cross-functional alignment on AI metrics was the strongest predictor of sustained adoption (Pragmatic Institute, 2025). Context engineering setup works the same way. The teams that succeed treat it as a cross-functional system, not a backend project.

Pragmatic Institute's 2025 research found cross-functional alignment on AI metrics was the strongest predictor of sustained adoption (Pragmatic Institute, 2025). Successful context engineering implementations involve engineering, documentation, and security teams working together.

Here's a condensed timeline from a real implementation pattern we've observed:

Week 1-2: Audit. The team reviewed 45 agent-generated PRs from the prior month. They tagged 31 that required significant rework. Of those, 22 failed because the agent lacked knowledge about migration constraints and deprecated internal APIs. Two failure modes, accounting for 71% of rework.

Week 3-4: Map and build. They identified four knowledge sources that contained the missing context: the incident management system, an internal Confluence space on database conventions, the PR review history for the payments service, and a Slack channel where the database team discussed schema changes. They connected these sources through a retrieval layer that indexed and ranked content by recency and author authority.

Week 5-6: Enforce and measure. They added conflict resolution rules (production code overrides documentation; post-mortems override planning docs) and permission enforcement that mirrored their existing Jira access controls. First-run acceptance rate went from 33% to 68% on the targeted failure modes.

That's not a finished system. It's a starting point. But it demonstrates the pattern: narrow focus, measurable outcomes, iterative expansion.

For more on the broader discipline, see what is context engineering.

---

FAQ#

How long does a context engineering implementation take?#

An initial implementation targeting one or two failure modes takes four to six weeks for most teams. JetBrains' 2025 survey data suggests the verification burden is widespread, with 76% of developers manually checking AI output (JetBrains, 2025). You don't need to solve all of it at once. Start with the failure mode that costs the most rework, build the retrieval for it, and expand from there.

Read the full context engineering walkthrough.

Can I implement context engineering with just CLAUDE.md or AGENTS.md files?#

Static instruction files are a starting point, not an implementation. They work for conventions that rarely change. They fail for anything dynamic: incident history, recent architectural decisions, cross-repo dependencies. Google's DORA 2025 research showed that delivery stability declines when AI tools operate without structured knowledge practices (Google DORA, 2025). Static files don't qualify as structured knowledge practices. They're Stage 1 in the context engineering maturity model.

What's the minimum team size needed for context engineering implementation?#

There's no minimum. A single senior engineer can implement the audit and knowledge mapping steps in a week. The retrieval and ranking layer typically requires familiarity with embedding models and vector search, or a context engine platform that handles it. Permission enforcement adds complexity proportional to your access control model. Teams of two to four typically handle the full implementation.

How does context engineering implementation differ from setting up RAG?#

RAG retrieves documents that are semantically similar to a query. A context engineering setup goes further: it ranks sources by authority, resolves conflicts between contradictory documents, enforces permissions, and shapes retrieved content for the specific task type. Stanford HAI's 2025 AI Index underscored that factual grounding remains a challenge for AI systems (Stanford HAI AI Index, 2025). RAG alone doesn't solve grounding. Context engineering addresses it through retrieval, ranking, conflict resolution, and measurement as an integrated system.

For a detailed comparison, see what is a context engine.

---

Start With One Failure Mode#

You don't need a platform team or a six-month roadmap to implement context engineering. What you need is specificity. Find the one failure pattern that costs your team the most rework. Trace it back to the missing knowledge. Build retrieval for that knowledge. Measure whether rework dropped.

The teams that succeed share one trait: they resist the urge to boil the ocean. They pick one failure mode, build the pipeline for it, prove the value, and expand. McKinsey's 2025 research confirms this pattern: AI productivity gains only hold when implementations target specific, measurable outcomes (McKinsey, 2025).

Mara's team didn't build a perfect system in six weeks. They built a system that stopped their agents from rewriting the same broken migration. That was enough to justify the next iteration. Yours will be too.

Start with the audit. Everything else follows.

Read the complete context engineering guide.