Context for coding agents: what to document and how to test it
Meta's internal map reduced exploration in a small test, while a broader study found higher cost without more successful fixes. The contrast shows how to design auditable context.
On April 6, 2026, Meta explained how it turned some of its engineers' tacit knowledge into a map for coding agents. The case matters beyond Meta because it poses a question any team can test: when an assistant receives repository instructions, is it getting a useful compass or a load of text that makes it more expensive and less accurate? The answer cannot be inferred from the number of documents. Teams must identify which context is missing, constrain where it applies and compare outcomes with and without it.
The system described in Meta Engineering's primary account covered an internal pipeline spread across four repositories, three languages and more than 4,100 files. Onboarding a data field could affect configuration registries, routing, graph composition, validation and code generation. An agent could find functions and produce changes that compiled, yet miss relationships that maintainers took for granted. That was the precise problem the map addressed: not teaching syntax, but exposing operational information that code alone did not express.
Start by identifying the knowledge that is actually missing
Meta did not ask one model to write a repository encyclopedia. It split the analysis into more than 50 specialized tasks — exploration, module analysis, writing, criticism, fixing and prompt testing — and produced 59 context files. Each file was kept to roughly 25–35 lines, or about 1,000 tokens, containing quick commands, key files, non-obvious patterns and references to other parts of the system. Meta also built a cross-repository dependency index and scheduled periodic refreshes.
The useful unit is therefore not a general summary but a decision an agent could not safely infer. It might be a serialization constraint that prevents removal of a deprecated value, two names for the same operation or a temporary field that changes identity later in a pipeline. Meta says it recovered more than 50 such patterns. These are examples of negative knowledge: they explain which plausible route must not be taken and why.
A maintainable context entry can record six elements for every rule: scope, rationale, affected files, an executable check, an owner and the date or version of its last verification. “Do not delete this value” is a fragile prohibition. “Do not delete it because stored messages still serialize it; run this compatibility test; these two modules are affected” supplies evidence and a verifiable exit. If a constraint can be expressed as a test, type or validator, that deterministic protection should accompany the explanation. Text provides direction; it does not replace enforcement.
A compass must select, not flood
Brevity is not merely stylistic. Every instruction competes for attention with the problem, the code and tool results. A global guide should contain only truly cross-cutting conventions; specific instructions should sit near the module they govern and load only when a task enters that scope. Separating navigation, stable rules and temporary state also makes staleness easier to detect. An entry path may change tomorrow, while an architectural rationale may last for years.
A separate Meta account of AI-assisted asset classification states the same principle in another setting: more context is not automatically better. It recommends a compact evidence brief containing both supporting and contradicting signals, with provenance attached. It also keeps human-reviewed labels separate from generated recommendations. Applied to code, this means an instruction should not erase uncertainty. It should show where it came from, which contradictions remain and which decision still requires human approval.
That design guards against two failures. The first is accidental authority: a generated sentence becomes project policy. The second is staleness: a file that was accurate when created continues to load months after its paths or invariants have changed. Checking that referenced files exist catches broken internal links, but it does not prove the rule remains true. That requires owners, versions, drift signals and review when dependencies change.
Measuring efficiency is not measuring correctness
Meta reports a preliminary six-task test in which context reduced tool calls and tokens per task by roughly 40%. It also says it tested more than 55 prompts, achieved a 100% pass rate on a core set and raised an internal critic score from 3.65 to 4.20 out of five. These are the maker's measurements on its own system. They are not an external benchmark, and six tasks cannot show that the method improves every repository. Most importantly, lower token use demonstrates efficiency; it does not by itself establish that the final change is correct.
The counterpoint is the primary study of AGENTS.md files, updated on June 23, 2026. Its authors tested four model-agent configurations on 300 SWE-bench Lite tasks and CTXBENCH, a set of 138 tasks from twelve recent or less familiar Python repositories. Model-generated files produced no statistically significant improvement in task resolution: average performance shifted by about -0.5% and -2% across the two benchmarks, while cost increased by roughly 20% and 23%. Developer-written files performed better than generated ones, but their average advantage over no file was not statistically conclusive either, and they also raised cost.
The paper found that agents did follow the instructions: they explored and tested more. The problem was that general overviews did not necessarily help them locate relevant files sooner. Its limitations matter too. It evaluates Python repositories, whose familiarity during pretraining may reduce the value of extra context; it measures task resolution rather than security or code efficiency; and it leaves improved context generation for future work. The study therefore does not refute Meta's case, just as Meta's case does not invalidate the study.
Reconciling results that appear to conflict
The sources test different propositions. Meta examines proprietary, dispersed knowledge unavailable during public model training and mainly measures exploration across six tasks. The paper examines public Python repositories, adds general context files and measures whether hundreds of issues are resolved. It is possible to reduce calls in the first environment and increase steps without improving success in the second. The honest conclusion is neither “context works” nor “context gets in the way.” Its value depends on whether it contributes information that cannot otherwise be inferred and whether the task activates that precise information.
A useful evaluation freezes the model, agent, budget and tools, then assigns representative tasks to a no-file condition and a context condition. The test set should not be the one used to draft or tune the instructions. Teams should measure final correctness, regressions, steps, tokens, latency and human intervention separately. Tasks should also be stratified: routine navigation, cross-repository changes, compatibility, security or migrations. An average can conceal a map that greatly helps one class while harming the rest.
The independent-evaluation practice in Meta's classification case supplies another transferable rule: do not optimize against the same set that determines whether a system is good. Use frozen references, human-reviewed labels and regression gates. Coverage is not correctness either. Having 59 files reach every module does not show their claims are true, just as exhaustive documentation does not guarantee the agent will select the right instruction.
A protocol that leaves an audit trail
A team can begin with ten or twenty real tasks that previously required asking a maintainer. For each, record the tacit decision, its evidence and a check. Write the minimum context needed to direct an agent to that evidence. Then run tasks in the same environment, review each change without knowing which condition produced it and preserve failures as well as successes. If correctness improves or cost falls without regressions, expand the experiment. If the file merely triggers more exploration, trim or remove it.
Maintenance is part of the product. Paths can be checked automatically; rules need owners and expiry dates; relevant changes should trigger review; and generated recommendations must remain distinct from approved policy. When an instruction is stable and testable, it should become a deterministic test or rule. The agent needs to know where to look, but the repository should make its invariants hard to violate.
This is how to read the next claim about agent “memory” or “context” without simply accepting the headline. Ask what new knowledge it contributes, when it is retrieved, who verified it, which tasks it was compared against and which metric improved. A code map earns its value when it converts private intuition into traceable evidence and a reproducible decision. If it cannot pass that test, it may not be a compass at all. It may simply be more text.
Sources for this piece
This piece draws on 3 primary source(s), gathered during reporting.
This article was produced with artificial intelligence under human editorial oversight.
