Sometimes, an AI coding agent has access to a powerful model, a detailed prompt, and an entire repository, yet still makes the wrong change.
It might rewrite a function that already has a shared implementation. It might introduce a new dependency when the project already has a solution. Or it might fix a bug in one file while breaking a feature somewhere else.
The problem is not always the model's ability to write code. Sometimes, the agent simply does not have the right information at the right time.
This is where context engineering comes in. As AI coding agents become more capable, knowing how to manage their context is becoming an important part of building reliable software.
1. what is context engineering?
Every coding decision depends on information. Developers understand a project through its files, documentation, architecture, conventions, and previous decisions. AI agents need access to the same kinds of information to make useful changes.
Context engineering is the practice of selecting, organizing, retrieving, and updating the information an AI model uses while working on a task. It goes beyond writing a good prompt. It includes deciding which files the agent should inspect, what instructions it should follow, which tools it can use, and what feedback it should receive.
Anthropic describes context as a finite resource that must be carefully curated as agents work across multiple steps. The challenge is not simply providing more information, but choosing the information most likely to help the model make the right decision. <Cite refs={["turn853089search2"]}/>
Imagine asking an agent to add password reset functionality to an existing application. The request alone does not explain how authentication works, which email service the application uses, or how errors are handled.
If the agent receives those details before implementing the feature, it can work within the existing system instead of inventing a new one.
2. context engineering vs. prompt engineering
A prompt tells an AI what you want. Context engineering determines what the AI knows while trying to accomplish it.
These practices are related, but they solve different parts of the problem.
| Prompt engineering | Context engineering |
|---|---|
| Focuses on instructions and wording | Focuses on the information available to the model |
| Defines the immediate task | Supplies project knowledge and relevant constraints |
| Clarifies the desired output | Helps the agent make decisions throughout the workflow |
| Often begins with a user message | Can include files, tools, memory, search results, and test output |
| Improves how a task is communicated | Improves what the agent can use to complete the task |
Consider two requests.
The first says, "Add authentication to this application. Follow best practices."
The second says, "Add password reset using the existing authentication service. Follow the error-handling conventions in src/auth, reuse the existing email provider, and add tests for expired and invalid reset tokens."
The second request is better because it includes more useful direction. Context engineering takes this further by helping the agent discover the relevant files, inspect existing implementations, retrieve documentation, and use test results as the work progresses.
A better prompt can improve one response. A well-designed context system can improve an entire development workflow. <Cite refs={["turn853089search2","turn853089search1"]}/>
3. what information does an AI coding agent need?
Not every coding task requires the same information. Fixing a typo in a button does not require reading the entire architecture document. Changing authentication logic probably does.
A useful context setup gives the agent access to several categories of information.
Project instructions. These explain coding conventions, commands, architectural boundaries, and rules the agent should follow. Files such as AGENTS.md or tool-specific instruction files can provide persistent guidance, depending on the agent being used.
Codebase context. Existing implementations, related files, interfaces, dependency relationships, and configuration help the agent understand how the application actually works.
Documentation and decisions. API documentation, design specifications, database schemas, and architectural decision records explain why the project is structured in a particular way.
Task requirements. Acceptance criteria, constraints, expected behavior, and explicit non-goals define what a successful change looks like.
Tool outputs and feedback. Test failures, compiler errors, terminal output, and logs show the agent what happened after it took an action.
Relevant history and memory. Previous decisions, known pitfalls, and summaries of ongoing work can help preserve important information between steps or sessions.
Microsoft's VS Code documentation describes agent context as including instructions, workspace files, conversation history, and tool outputs. It also explains how agents can gather additional context by searching files and running commands as they work. <Cite refs={["turn853089search1","turn853089search4"]}/>
The goal is not to provide everything at once. It is to make the right information available when the task needs it.
4. why more context does not always mean better results
It seems reasonable to assume that giving an AI agent the entire repository, every design document, and a long history of previous conversations should make it more accurate.
In practice, excessive context can create new problems.
A large codebase may contain outdated documentation, duplicate implementations, abandoned features, and instructions that no longer apply. If the agent receives too much irrelevant information, the details that matter can become harder to identify.
Models also have context-window limits. Instructions, code, conversation history, retrieved documents, and tool outputs all compete for space. Even when a model supports a large context window, more information does not guarantee better reasoning or recall. <Cite refs={["turn853089search8","turn853089search0"]}/>
Imagine asking an agent to fix a payment bug and supplying 200 files without explaining where the payment flow begins. The agent may spend time inspecting unrelated modules or follow an outdated pattern it discovers elsewhere.
A better approach is to start with the relevant entry point, trace the dependencies, and retrieve additional files as needed.
This is sometimes called progressive context building. The agent begins with a focused set of information and expands it as the task becomes clearer.
Good context engineering is not about making the context bigger. It is about making every important piece of context earn its place.
5. how to implement context engineering in a real codebase
You do not need a complicated multi-agent system to start improving context. Most teams can make meaningful progress with a few practical changes.
establish project-wide instructions
Create a concise instruction file that explains how the repository is organized, which coding conventions matter, and how to run the application and its tests.
For example:
# project instructions
- use typescript and follow existing patterns.
- reuse existing utilities before adding dependencies.
- do not change public APIs without approval.
- run relevant tests after modifying code.
- never expose secrets in source code.
The exact filename and format depend on your coding agent. Keep the instructions specific, accurate, and easy to maintain.
document important architectural decisions
Explain the parts of the system that are difficult to infer from code alone. These might include why a particular database was chosen, how authentication works, or which service owns a given responsibility.
Documentation should help an agent make decisions, not merely describe every directory.
ask the agent to investigate before editing
For complex tasks, separate exploration from implementation.
Ask the agent to identify the relevant files, explain the current behavior, list constraints, and propose a plan before making changes. This gives you an opportunity to catch incorrect assumptions early.
retrieve context as the task evolves
The first files an agent inspects may not reveal the entire problem. It may need to follow function calls, inspect schemas, read API documentation, or examine test failures.
Allow the agent to discover that information through repository search and appropriate tools rather than guessing or loading everything indiscriminately.
validate and update
After implementation, run the relevant checks. If the agent repeatedly misunderstands a convention, consider whether that convention needs clearer documentation or a more accessible example.
Microsoft's context engineering workflow for VS Code covers project instructions, implementation planning, incremental development, and maintaining useful context as a codebase evolves. <Cite refs={["turn853089search4"]}/>
6. how context engineering works with agent skills, MCP, and tools
Context engineering is not a replacement for other agent infrastructure. It helps determine how that infrastructure should be used.
Agent skills provide reusable procedures and domain-specific guidance for particular tasks. For example, a testing skill might explain how to run a test suite, interpret failures, and verify a fix.
Model Context Protocol (MCP) provides a standardized way for AI applications to connect with external tools and data sources. An agent might use an MCP server to access issue-tracking information or retrieve relevant documentation, depending on the integrations available.
Repository instructions explain project-specific rules. Search tools help discover relevant code. Tests provide evidence about whether a change works.
Context engineering connects these pieces by deciding what information should reach the agent, when it should be retrieved, and how the resulting information should influence the next step.
Consider a bug reported in an issue tracker. The agent retrieves the issue, searches for the affected function, reads the relevant project instructions, examines related tests, and proposes a fix. After running the tests, it uses the results to decide whether more work is needed.
Each step contributes new information to the agent's working context.
The important distinction is that having access to a tool does not mean an agent will use it correctly. The surrounding workflow must make the right actions available and provide enough information to guide their use.
7. how to know whether your context engineering is working
Context engineering should improve observable engineering outcomes, not simply create more documentation.
Start by looking at the mistakes your agents make repeatedly. Do they use the wrong database pattern? Ignore existing utilities? Break public interfaces? Repeat questions that were already answered? These patterns can reveal missing, outdated, or poorly organized context.
Then measure whether changes to your context setup improve the workflow.
Useful indicators include:
- Fewer corrections: How often do developers need to redirect the agent?
- Better first-pass results: How frequently does the proposed implementation satisfy the acceptance criteria?
- Test outcomes: Do changes pass the relevant tests without introducing regressions?
- Less unnecessary exploration: Does the agent spend less time inspecting unrelated files?
- Lower task cost: Can the agent complete comparable work with less repeated context and fewer unnecessary tool calls?
- Better consistency: Does generated code follow the project's architecture and conventions across different tasks?
These measurements need context of their own. A lower token count is not automatically an improvement if the agent starts missing important requirements. Likewise, fewer tool calls do not matter if the resulting code is less reliable.
A practical method is to select a handful of recurring tasks, record their current results, change one part of the context setup, and compare the outcomes.
Over time, this turns context engineering from guesswork into an iterative engineering practice.
conclusion: better agents need better information
AI coding agents are becoming more capable, but capability alone does not guarantee that they understand the system they are changing. They need relevant project knowledge, clear constraints, useful tools, and feedback that helps them distinguish a successful change from a plausible-looking mistake.
Context engineering gives developers a way to design that environment deliberately. It reduces the need to repeat instructions, helps agents work within existing architecture, and makes complex tasks easier to break into manageable steps.
The most effective setup is rarely the one with the most files or the longest prompt. It is the one that makes important information easy to find, keeps outdated guidance out of the way, and verifies results as work progresses.
As AI-native engineering matures, developers will spend more time designing the conditions under which agents work well, not just asking them to write code.
"An AI agent can only make good decisions with the information it can find, understand, and trust."