AI Coding in Legacy Systems: First Build a Queryable Repository Knowledge Layer

The Problem: Context Gaps Beyond the Current File

A single interface change may touch only a few lines of code but must respect data ownership of another service, usage rules of platform components, and years of framework conventions. Coding agents that only read the current file often produce syntactically correct, locally testable code that cannot integrate into the system. Typical failures include cross-service direct database access, re-implementing existing capabilities, or bypassing private framework entry points. The root cause is not that the model cannot write code, but that it lacks the relational information that decides where to change, what to call, and what not to touch .

Figure 1: Context gap in cross-module changes, AI-generated

Why Expanding Context Windows Is Not Enough

Larger context windows mitigate omissions but cannot automatically judge relevance. Anthropic's context engineering guide treats context as a limited resource and stresses on-demand retrieval of high-signal information; Aider's repository map selects symbols by dependency relationships and token budget rather than feeding the entire repository text. This shows the key problem is how to organize and deliver knowledge .

Repository Knowledge Layer: Answering Relational Questions First

The proposed "repository knowledge layer" sits between code, documentation, and coding agents as a queryable knowledge base. It must answer three question types:

Code structure: who calls whom

Business: which module owns which rule

Engineering: which implementations are established patterns or forbidden zones

Only by connecting these three can retrieval support cross-module changes.

Figure 2: Layered design of repository knowledge layer, not yet built, AI-generated

1. Deterministic Relationships and Semantic Judgments Should Be Separated

Class, function, reference, and inheritance relationships should be extracted primarily from syntax trees and symbol indexes. tree-sitter provides syntactic structure; SCIP (Source Code Intelligence Protocol) enables cross-file symbol navigation. Business entity-to-module mappings often cannot be derived from syntax alone; they can be supplemented from documentation, database schemas, and expert review, but must retain provenance and confidence status. This separation avoids a danger: letting an LLM guess "call edges" from similar names and then treating those guesses as facts for downstream agents . Every edge in the graph must trace back to source files, commits, or document segments; unconfirmed relationships remain candidates and cannot replace deterministic dependencies.

2. Persistent Index Must Accommodate Current Code

Pre-built indexes reuse cross-file relationships; real-time search sees latest uncommitted changes. They should collaborate: stable architectural relationships come from the index; current workspace state is verified by in-task retrieval. When index version diverges from code commits, the agent must know results may be stale rather than treating an old graph as current fact. For AsiaInfo's multi-stack R&D scenarios, this means a unified model must allow language and private framework differences, not erase implicit dependencies for the sake of a tidy graph. Parser coverage, cross-language precision, and maintenance cost still need per-repository measurement .

Public Experiment Shows Gains and Costs

A 2026 preprint compared standard vector retrieval with graph-structured retrieval on a public Java migration task. Researchers reported: API hallucination rate dropped from 56.4% to 16.2%, dependency resolution quality rose from 34.8% to 65.9%; but complexity consistency fell from 71.6% to 46.7%. These numbers come from a single migration experiment with custom metrics and cannot be taken as general enterprise expectations, nor are they AsiaInfo's own measurements.

Figure 3: Gains and costs in public single-repo migration experiment, data from [4], AI-generated

The results reveal the real trade-off: structural context helps constrain non-existent interfaces and broken inheritance; feeding too much global information may induce defensive, overly complex code. Therefore, the knowledge layer should not stuff the entire graph into the prompt but retrieve the minimal task-relevant subgraph and keep code search as a supplement. Graphs are not the only solution: clear module boundaries and single-file changes may already be served by existing repository search and static specs; cross-module calls, private framework adaptation, and legacy migration justify graph investment. Whether to build a persistent knowledge layer should be decided by task difficulty, index maintenance cost, and validation results.

Validate Knowledge Quality Before Discussing Coding Efficiency

Adoption can start with a repository that has frequent cross-module changes and complete review records. First, record dependency misuse, rework, and defects without the knowledge layer. Then let a comparable task set use sourced structural queries. Keep model, tool permissions, and review standards identical to avoid attributing model upgrades to the knowledge layer.

Validation has two layers. First layer examines knowledge itself : sample-check key dependency edges for correctness, freshness, and permission leakage. Second layer examines delivery outcomes : compare dependency misuse, defect escape, review rounds, and total completion time. Model acceptance rate is only an auxiliary signal; accepted code does not prove it respects system boundaries. Thresholds should be set from pilot baselines; the article prescribes no target percentages.

Security boundaries cannot be omitted. Source code and design docs may have different visibility scopes; query results must inherit caller permissions, and output snippets must avoid leaking sensitive implementations. Dynamic calls, configuration-driven flows, and implicit relationships in private frameworks may exceed static indexing capability. For these gaps, the system should explicitly mark unknowns and retain human review entry points.

AI coding quality in legacy systems ultimately depends on whether model capability and engineering context are both in place . The repository knowledge layer is worth exploring because it turns repeatedly searched relations into traceable knowledge and delivers it per task; its effectiveness must be tested in real repositories, real reviews, and real defects.

Open Questions for Readers

In your repository, what do agents miss most often: structural dependencies, business rules, or team conventions?

If you introduce a knowledge layer, which attributable metric would you use first to judge its value?

References [1] Anthropic Applied AI Team. Effective Context Engineering for AI Agents. Anthropic Engineering, 2025. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents [2] Aider. Repository Map. Aider Documentation, accessed 2026-09-24. https://aider.chat/docs/repomap.html [3] Sourcegraph. The Future of SCIP. Sourcegraph Blog, 2026. https://sourcegraph.com/blog/the-future-of-scip [4] Jaiswal N., et al. Beyond Vector Similarity: Hierarchical Context-Aware Graph RAG vs Standard RAG in Enterprise Code Migration. arXiv:2609.12464v1, 2026. https://arxiv.org/abs/2609.12464