AI coding agents have become remarkably good at finding code: they can search repositories, follow references, inspect files, and identify likely locations for a bug. Yet finding the right file does not guarantee a correct fix.
The problem is that software engineering is a reasoning task involving dependencies, behavior, tests, architectural decisions, and the history behind existing code - not just a search task.
The next step for AI coding agents is a context graph that helps them understand how a software system fits together.
Search finds code. Context explains it.
Modern coding agents increasingly use iterative search instead of relying entirely on prebuilt vector indexes, searching for relevant terms, inspecting results, following references, and refining their investigation as they learn more.
This approach has advantages: it is flexible, works directly with the latest source code, and avoids some of the complexity of maintaining separate retrieval indexes.
But search results are still largely independent pieces of information and even when an agent finds the correct files, it must reconstruct how those files relate to one another.
Consider a seemingly simple bug: requests without a tenant header unexpectedly fall back to a default account.
An agent might find the request middleware, tenant resolver, and a few tests through keyword search. But solving the issue requires understanding how the header is parsed, how the tenant is resolved, where the fallback occurs, which authorisation rules depend on it, and which tests verify the intended behavior. The relationships between these variables carries more weight than the search terms.
A context graph makes them explicit by connecting code, tests, configuration, issues, changes, and engineering decisions.
Why better search eventually reaches its limits
There are three reasons why improving retrieval alone cannot solve the problem.
1. Relevance is about relationships, not just similarity.
Two pieces of code can be closely related even when they share few words. An interface implementation, an indirect caller, or a configuration flag may be essential to a fix without resembling the original issue description.
Conversely, search can return highly similar code from another service or execution path that has nothing to do with the problem.
2. Finding evidence is not the same as using it.
A recent study for Context Retrieval in Coding agents evaluated coding agents across 1,136 issue resolution tasks in 66 repositories. It found substantial gaps between the context agents explored and the context they ultimately used, with sophisticated agent scaffolding producing only marginal improvements in retrieval quality.
This exposes a crucial weakness. An agent can inspect the right code and still fail to carry the important evidence into its implementation decisions.
3. More context does not automatically mean better reasoning.
Giving an agent more files or a larger context window may seem like a straightforward solution. However, additional information can introduce irrelevant details, increase costs, and make critical evidence harder to retain.
The goal should not be to provide as much context as possible. It should be to provide the right context, with the relationships needed to interpret it.
What a context graph changes
A context graph represents a software system as connected entities rather than a collection of searchable documents.
| Search centric approach | Context graph approach |
|---|---|
| Finds files matching an issue | Connects the issue to relevant code and behaviour |
| Returns independently ranked results | Preserves relationships between results |
| Relies on the agent to reconstruct dependencies | Exposes callers, implementations, tests, and configuration links |
| Retrieves context for the current query | Can incorporate changes, decisions, and previous findings |
| Measures relevance at the result level | Can evaluate whether the collected evidence explains the task |
The graph does not need to contain every possible fact about a repository. It needs enough reliable structure to help the agent move from an initial clue to a coherent understanding of the problem.
For example, a useful graph might connect a failing test to an API endpoint, then to a service, a database mapping, and the configuration controlling that behavior. It could also connect those elements to the pull request that introduced the behavior and the review that explained why it was designed that way.
This last connection is particularly important because the source code tells an agent what the system does, while engineering history can help explain why it does it.
The role of search in a graph-based architecture
A context graph should not replace search - it should make search more useful.
A practical architecture combines three capabilities:
Lexical and semantic search identify likely starting points using issue descriptions, error messages, symbols, and stack traces.
Graph traversal expands those starting points through meaningful relationships. Depending on the task, this could include callers, implementations, affected tests, configuration dependencies, recent changes, or architectural decisions.
The agent receives a compact evidence package containing the relevant source code, the relationships between components, and the provenance of important facts.
As the agent edits code and runs tests, the context should evolve. Failed hypotheses can be discarded, newly discovered dependencies can be added, and previous findings can be retained rather than rediscovered.
Research supports this direction, demonstrating improvements when repository structure was integrated into existing coding systems. More recent work evaluates repository exploration directly rather than treating final task success as the only measure of an agent's capabilities.
These results support the value of structured context, although they do not establish that every graph implementation will outperform every search based system.
What this means for engineering teams
The practical opportunity is to build context incrementally rather than attempt to model an entire organisation upfront.
Start with relationships that are relatively easy to extract and maintain, such as definitions, imports, function calls, and tests. Then connect these to issues, pull requests, configuration, and architectural decisions where reliable data is available.
The graph must also remain current. Stale relationships, incorrect inferences, and indiscriminate expansion can be just as damaging as poor search results. Every important relationship should have traceable evidence, and the agent should be able to distinguish verified facts from assumptions.
Evaluation matters too. Teams should measure not only whether an agent completes a task, but also whether it finds the relevant code, retains the necessary evidence, makes appropriate changes, and solves the task at an acceptable cost.
Conclusion
AI coding agents are moving beyond code completion toward software engineering tasks that require understanding entire repositories.
Better search helps them find the right places to look. A context graph helps them understand what those places mean, how they connect, and which constraints must be preserved when making changes.
Reliable engineering depends on understanding the system well enough to change one part without breaking another.










