What Is AI Context Engineering? Giving Coding Agents the Right Context

When a coding agent breaks a rule your team agreed on, the usual instinct is to give it more instructions, but more material can make the agent worse. Chroma tested 18 models and found performance dropped as input length grew, even when the task stayed the same.

The alternative is AI context engineering: deciding what a coding agent knows at each step, from architecture and conventions to past decisions. Because several engineers and agents now share the same files, keeping that context accurate needs an owner.

In this article, we'll cover why more context isn't enough, which kinds of context an agent needs, what happens when it goes stale, and what your team should own versus what tooling should handle.

What does context engineering actually mean for AI coding agents?

Context engineering means deciding what information an agent sees before its next action, and maintaining that information with the same discipline a team applies to the code itself.

Andrej Karpathy popularized the term over prompt engineering in mid-2025, posting that he preferred "context engineering" over "prompt engineering" because people associate prompts with short task descriptions you'd give an LLM in day-to-day use.

Instead, he described context engineering as "the delicate art and science of filling the context window with just the right information for the next step."

For a coding agent, context is never just the prompt typed into a chat window. It is the assembled set of files, instructions, standards, history, and check results the agent is handed for that specific step.

Some of that material gets built automatically for a single task: the open diff, the ticket, the files touched last.

Other material persists across tasks and across engineers, and nobody assembles it automatically.

Inside our loop, graph, and harness framing:

• The graph decides order and routing.
• The harness decides what the agent can touch and what checks its output.
• The loop decides when to retry or stop.
• Context engineering is the fourth layer, deciding what the agent knows at each step, and it lives inside the harness.
  
  

Why just giving the agent more context isn't enough anymore?

Chroma's report also shows what works. Every model scored significantly higher on a focused input of about 300 tokens than on the same facts buried in about 113,000 tokens of chat history. Distractors did the most damage: related but wrong content lowered accuracy, and the effect grew with input length.

A stale convention sitting next to a current one confuses the agent: it has no reliable way to tell which one wins, and the stale rule competes for attention with the guidance that matters.

For teams running agents against a shared codebase, the real work is choosing which material earns a place in the window for this step and discarding the rest.

What kinds of context does an AI engineering agent need?

An AI engineering agent needs several distinct kinds of context to produce a usable first attempt, and each comes from a different source inside the repository and the team's history.

Here's what each one covers:

• Architecture: how the system is structured and why certain boundaries exist. This comes from architecture notes and design decisions written into the repository, so the agent doesn't have to guess structure from file names.
• Conventions: naming, patterns, and house style. This lives in coding standards and instruction files, and it is the layer most teams already maintain, even if only informally.
• Constraints: security rules, dependency policies, and performance limits that must hold regardless of what the agent proposes. These start as written policy, but they only matter in practice once an enforced check backs them.
• Past decisions: what the team tried, what broke, and what it decided to do differently. Instruction files capture this poorly unless someone writes the lesson down the day it happens, often as a rule dated to the incident that caused it.
• Feedback signals: the results that tell the agent when it got something wrong. These come out of the harness as check output and only become useful once fed back into the next attempt.

Most of this is team-level: shared, persistent, and valuable only if someone keeps it current.

Constraints and feedback signals hold up better as check results than as prose in a Markdown file, because a deterministic check gives the same answer every run. For example, the Codacy MCP Server and Codacy Analysis CLI let an agent run Codacy's analysis locally and read each finding's exact file and line.

What happens when context goes stale, contradicts itself, or diverges across repos?

A harness delivers context to an agent faithfully, whether or not that context is still correct, and a stale rule reaches the agent with exactly the same authority as a current one. It has no way to know the instruction file it is loading describes a decision the team reversed months earlier, so it passes the outdated rule along with full confidence.

The failure compounds when the agent checks its own output. It evaluates the change against the same instruction file that shaped it, so it passes its own review, just as a developer can't catch a misread requirement by rereading the ticket that caused the misreading.

The problem grows across repositories. When one team updates its instruction file after an incident, and another never does, the same change can pass in one repository and get flagged in another, depending on which file sits in that directory.

Verification has to come from somewhere independent of the context that shaped the work. That challenge is quite common: Codacy's scan of 34,266 repositories found gaps in AI agent configuration files in one in four organizations.

Context as a maintained artifact

Team-level context is an artifact with the same lifecycle needs as code: it needs an owner, versioning, and updates on a cadence, or it drifts the way any unmaintained module would.

Teams without a dedicated platform function tend to skip this by default, because instruction files feel like documentation rather than infrastructure, and documentation is usually the first thing cut when a sprint runs long.

Without an owner, every agent inherits whatever state the instruction files happen to be in.

One habit helps. In our own agent setup, each instruction-file rule carries the date something went wrong, so the same mistake doesn't resurface on the next run.

The habit works for one engineer. It breaks down as a team grows because it depends on someone remembering to write the rule, someone pruning the ones that are no longer true, and every repository getting the same update.

That's a lot to rely on memory when more than one in five code reviews on GitHub now involve an agent. Context that keeps up has to be captured as decisions are made and retired when it stops applying, without anyone maintaining it by hand.

Build vs. buy: what should teams own, and what should tooling handle?

Teams own the knowledge of what is true about their system. Tooling should keep that knowledge current and enforce what is allowed to merge. Confusing the two is how an optional check quietly becomes the only check a team has.

An instruction-file rule is a request the agent may or may not follow. A check that runs on every change is a guarantee, and an optional check tends to get skipped exactly when it matters.

In practice, the split looks like this:

• Own yourself: the decisions and the reasons behind them, such as architecture boundaries, conventions, and what the team learned from an incident. No outside tool can know why your system is shaped the way it is.
• Let tooling keep the record: capturing those decisions as they happen, keeping them consistent across repositories, and retiring the ones that stop applying, so nobody updates instruction files by hand.
• Let tooling enforce: the deterministic, independent checks that decide whether a change is allowed to merge, regardless of what any instruction file claims about the rule.
  
  

How does context quality affect agent output, review load, and risk?

Better team-level context improves an agent's first attempt, and the effect compounds across every agent drawing on the same files. Accurate architecture notes and current conventions mean fewer rounds of correction, which matters because AI time savings often shift to review without it.

Independent checks reduce review load from the other side: they catch what the context missed or got wrong before the change reaches a human, so the reviewer looks at work that has already cleared the mechanical issues.

Both effects push in the same direction, lowering what slips through to merge and lowering review time per change as a team grows.

This also shapes how much engineers actually trust what an agent produces. Stack Overflow's 2026 developer survey found that 48% of developers trust AI output when they can easily validate the answers, while only 16% extend that trust to tasks involving important work decisions.

Independent verification is what makes that validation cheap enough to run on every change rather than only the ones a reviewer happens to have time for.

Where Codacy fits: preserving knowledge and verifying the result

Verity, Codacy's second product, is a pair programmer for coding agents. It sits inside the agent's reasoning loop, checks every turn against the task, the team's standard, and the code itself, and hands the fix back to the agent before anything reaches Git.

Every decision lands in a knowledge base the next session builds on, so nobody maintains instruction files across repos by hand.

The check also stands apart from the agent that wrote the code. Verity combines AI analysis, SAST, intent checks, formal proofs, and runtime analysis, so the result doesn't depend on the agent grading its own work against its own context.

From there, the split is simple: fix in the agent loop, enforce at the PR. Verity works alongside the agent, and the Codacy platform determines what ships at the pull request level and across the organization.

Treat context as part of your system

Coding agents now work across sessions, repositories, and teams, so the context they draw on is part of your engineering system. Your team owns the decisions and the reasons behind them. Tooling should keep that record current and enforce what's allowed to merge.

The principle to keep in mind is to give agents the right context so their work holds to your standards across every agent and repository, with fewer rounds of correction, and keep an independent check on the result, because an agent can't verify its work against the same material that shaped it.

Before deciding what to build first, check where your team sits on the AI Coding Maturity Scale.

AI context engineering FAQs