The Map

"Who else uses this?"

The agent answered before the meeting did.

The open question#

In April I wrote a piece called The Nuclear Reactor in Your Codebase. An agent writes code from whatever fits in its context, and that is all it sees. It does not know where the change lands. It does not know what it breaks on the way. It has the repository, and the repository does not say any of this. I ended that piece without a clean answer. All I had was an instruction: write down what only the senior engineers know, before they leave.

I meant it. I also had no idea what writing it down would look like.

Then I spent the summer inside a very large monolith where somebody had, partly, done it.

The agents#

The codebase was old enough and big enough that nobody claimed to understand all of it. Ownership was drawn with CODEOWNERS files, so at least every path had a name next to it. That alone put it ahead of most places I've worked.

The answer there was to build more agents. Of course it was; this is the AI era.

What made them worth writing about is not the models. It is what they were pointed at. One of them you aimed at a change, and it came back with who lives downstream of it. Does this migration touch a table another team reads directly? Does the default value you just added change what a consumer of this endpoint gets back? Is the field you renamed sitting inside an event that two other services listen to? The answer was not a list of files that import a module. It was teams, owners, the endpoints they call and the events they consume. In a monolith where a grep for a function name returns four hundred hits, that is not a small thing.

Three more sat next to it. One went after the root cause of a bug instead of the symptom, walking back from the stack trace through the recent changes and the services around them. A knowledge base had indexed the wiki, the repositories and the chat history, and could answer almost anything about the company in seconds, with the link. On top of it sat a chat assistant, which people asked the things they used to ask whoever had been there longest.

The first one is the one I keep thinking about. Someone in a meeting asks who else uses this. Normally that question costs a day: you grep, you read, you ask two people, you come back on Thursday and you are still not sure. Here the answer arrived while the question was still in the air, with team names on it, and the meeting carried on.

The model underneath was the same model everyone else has. The intelligence was not the difference. The difference was that somebody had given the agent somewhere to look.

What was underneath#

Those agents were fast because they were not reading the codebase. They were asking things that already knew it.

Ownership came from the CODEOWNERS files, which are plain text and parse in a second. Callers came from a call graph that had been built in advance, so "who calls this" was a lookup, not a search. Event consumers came from the event schemas. What talks to what in production came from tracing, which knows what the code cannot: the code has no idea what it runs next to. Criticality, who is on call, where the runbook lives, all came from a service catalogue.

None of those sources is exotic. Most mid-sized engineering organizations have all of them, scattered, in five tools nobody has connected. What made the difference was that they had been connected and exposed to the agents as tools: something like who owns this path, who calls this service, who consumes this event, what tier is this. The agent did not load the monolith into its context and think hard. It asked six small questions of six systems that each held one true thing, and assembled the answer.

That is also how the knowledge base worked, as far as I could tell from the outside. Connectors into the wiki, the repositories and the chat; an index over all of it; a search that combined plain keyword matching with meaning; and permissions carried through, so it would not tell you what you could not already read. Ask it a question and it retrieved the eight paragraphs that mattered out of ten years of writing and answered from those. The trick was never the answering. The trick was retrieving the right eight paragraphs.

None of this is intelligence. It is plumbing. An agent is only as good as what has been written down in a form it can query, and that part is engineering work like any other.

And once the plumbing exists, the agents built on it should not stay in one team's repository. That is the usual pattern: one team writes a good agent, everyone else keeps doing the work by hand, and the same tool gets written three more times. A company needs an internal marketplace for them, the way it has a package registry. Agents and the tools they call are published there, with what they do and what they are allowed to reach, and any team can install one on its first day instead of building it in its second year. That is the difference between a few engineers who use AI well and a company that builds software with it.

Not in the code#

Here is roughly what a change looks like in any system old enough to matter.

CopyController
    ↓
Service
    ↓
Model
    ↓
Event
   ↙      ↘
Queue      Listener
 ↓             ↓
Service B   Service C
                ↓
            Search index

An agent with the repository can trace most of this: controller to service, service to model, model to event, event to listener. Then it runs out of code, and the questions do not stop. Is this event consumed by something outside this repository? Is that branch business-critical, or a leftover nobody has dared remove? Who owns Service C, and did they agree to this contract or inherit it? Is there production behavior here that no test covers?

Every one of those has an answer. None of the answers is in the code.

The research says the same thing from a different direction. A 2026 case study had a coding agent migrate an old VB6 system to C# and then measured how much behavior survived: around 92% for the simple features, around 47% for the complex ones.¹ The agent had every file. What it missed was behavior hidden in optional parameters and configuration, and the batch jobs and notifications that lived next to a feature without being named in it. The files were all provided. The system was not.

Scale AI's benchmark of long engineering tasks put a number on it. Take away the human-written requirements and interface descriptions, leave the agent with only the repository and the issue, and the best model drops from roughly 23% to roughly 8%.² The code had not changed. What had been written about the code had.

A developer in a 2025 study, working in their own large repository, said it more simply: the model doesn't know that we need to take care of this weird case of backwards compatibility.³ Nobody wrote that case down. So the model, which can only read, could not read it.

Too much context#

The instinct at this point is to give the agent more. More files, more tokens, a bigger window, the whole wiki, the entire commit history.

It does not work. A study of thirteen models advertising windows of 128,000 tokens or more found that eleven of them dropped below half of their short-context performance by the time the input reached 32,000.⁴

Even the people who build the models now say so. Anthropic's engineering guidance talks about "context rot" and an "attention budget", and describes the goal as the smallest set of high-signal tokens, not the largest.⁵

There is a sharper finding. Researchers at ETH Zürich tested the repository-level context files that every vendor now recommends, the AGENTS.md and CLAUDE.md files that describe the codebase to the agent. The auto-generated ones made things slightly worse. The developer-written ones helped by about two points, which may be noise, and both made every task about twenty percent more expensive. Repository overviews, they concluded, are not helpful. What did help was explicit instruction: say which tool to use and the agent uses it.⁶

I read that as good news. It separates two things that get called by the same name. Describing the repository to the agent in prose is not the map. The map is the part the ETH study did not test: who owns this, what breaks if it changes, what must stay true, who has to be in the room. Not more context. A different kind.

The First Button was about the boundary of a piece of work: what it is, when it is done. This is about the boundary of the system that piece of work lands in. The first one you can write in an afternoon. The second one is what took that company years.

The catalogue#

What sat next to the code, in the place I described, was roughly this set of layers: architecture, ownership, dependencies, invariants, business flows, operational constraints. None of them lived in one file, and I am not proposing a file. But one part of this map already has a standard form. Backstage is an open-source service catalogue, first built at Spotify. In Backstage, every service has a small file next to its code. This is the example from its documentation:⁷

yamlCopyapiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: artist-web
  description: The place to be, for great artists
spec:
  type: website
  lifecycle: production
  owner: artist-relations-team
  system: artist-engagement-portal
  dependsOn:
    - resource:default/artists-db
  dependencyOf:
    - component:default/artist-web-lookup
  providesApis:
    - artist-api

Many companies already have files like this. The file tells you who owns the service, what it depends on and who depends on it. That is useful. But it does not tell you what must never break. It does not tell you why the service works the way it does, or what went wrong the last time someone changed it. That part is still in people's heads. It is the part the agents in the next section were writing down.

The point of both halves is what they let the agent reason about. Instead of "here are the files", the agent gets to think: this change touches A, B and C; B crosses a service boundary; that boundary is owned by another team; the change would violate an invariant that team relies on; it therefore needs a migration, and afterwards this one path has to be validated end to end. That is a different job from generating code. It is closer to what a good tech lead does in the first ten minutes of a design review, and it is exactly what that agent did in the meeting.

I should be honest about the evidence. Nobody has published a controlled study showing that a machine-readable map of ownership and invariants improves what agents produce. The closest things are the benchmark above, where writing down what must be true tripled the success rate, and Thoughtworks' work on legacy systems, where they turned code into a graph database first and let the model answer questions against the graph, because, in their words, the mental models existed only in people's heads.⁸ What I have is one summer of watching it work, and one recent project where I built a version of it myself. That is an observation, not a result.

Written as you go#

The obvious objection is that maps rot. Somebody writes the ownership file, the rules, the decision log, and six months later it describes a system that no longer exists. That is true of every map kept by hand.

I tried a different way on a recent project. I wrote four agents and ran them on every pull request, before pushing. None of them wrote feature code. Each one had one job: keep one part of the map up to date.

The first traced the blast radius. It followed every caller, async consumer, cache and schema the diff could reach, then ran the full test suite to prove they still worked. The second attacked the design against the rules that must hold, the ones the domain cannot break and the load the system has to survive. For each rule it asked where it was enforced, in the database or in application code that can race. The third wrote the decisions down. Every design choice that landed got an entry in the decision log, with what it gave up and why that was acceptable, in the same pull request that made it.

The fourth kept the test cases for the user journeys, and it was not allowed to read the implementation. It worked from the user stories, the same kind The First Button was about. A test case written from the code cannot fail, because it asserts what was built. A test case written from the story can, and that is its whole value.

Four is not a rule. It is what that project needed. Another codebase will want different ones: one that watches data contracts between services, one that checks security rules, one that keeps the runbooks honest. The set will grow as a team learns what it keeps forgetting. The idea stays the same.

This is context engineering in the literal sense. Not a longer prompt. A repository that explains itself a little more after every merge, so the next agent that opens it, or the next person, finds the answers already written. And nobody has to remember to write them.

One detail surprised me. An agent has no memory between runs, so each of mine kept a small notebook per branch: what it reviewed last time and what it left open. Without that, a reviewer on its fifth pass either reads the whole branch again or forgets what it asked for.

Sideways#

AI capability is improving vertically. Better reasoning, better code, longer context, better use of tools. Every quarter the same task gets done better.

I don't think that line keeps going up. At some point, at least with the technology we have now, it will flatten. We have already seen one sign of it: a bigger context window did not make the models read better.

The next model will write a better function.

It will not know more about your company.

The real gain is horizontal. To change one thing safely, the agent has to see past the repository: the services around it, the events on the bus, what really happens in production, which team owns which part, and the business process the whole thing exists for. Each step outward is a different source, with a different owner and a different format. The last step is not a source at all. It is people.

A better model does not take that step for you. The agents that impressed me were impressive because somebody had let them read sideways.

This is also why the same tools give different teams different results. DORA, a research program at Google, surveys thousands of software teams every year. In its 2025 report, more AI use went together with faster delivery, and also with less stable releases. The report calls AI an amplifier: it makes a strong team stronger, and a struggling team's problems bigger.⁹ A team that knows what its software means and who owns what gets a faster version of itself. A team that does not gets the same agent, and more of its own problems.

Abundant, scarce#

For most of my career a senior engineer's value was partly "I know how to write this". That part is being commoditized in front of us, and pretending otherwise helps nobody. Simon Willison put it bluntly this year: delivering new code has dropped in price to almost free, and delivering good code has not.¹⁰

The part that has not been commoditized is "I know what changing this means to the rest of the system". That knowledge was always the expensive part. It just used to be bundled with the typing, so nobody priced it separately. Now the typing is cheap and the knowledge is exposed, and it turns out most of it was never written anywhere a machine could find it.

Code is becoming abundant. Understanding is staying scarce.

The sixth sense#

The reactor piece ended with a line I still believe: trust your sixth sense rather than the perfect machine. The sixth sense was the map. It lived in people who had been there long enough to feel a bad change before they could explain it.

What changed is who is doing the changing. The agent has no sixth sense and cannot grow one; it has whatever we wrote down and nothing else. That sounds like a loss, and it is. It is also the first time the map has had a reader who will actually use all of it.

Maybe the next thing worth building for the agent is not a better tool. Maybe it is an honest description of what our software is.

Sources

1. 1.Legacy System Modernization with Coding Agents: A Case Study — arXiv preprint, 2026. One system, twelve features; functional equivalence 92% on low-complexity, 47% on high-complexity features.
2. 2.SWE-Bench Pro: Can AI Agents Solve Long-Horizon Software Engineering Tasks? — Scale AI, 2025. Removing the human-written requirements and interface specs dropped the best model from 22.7% to 8.2%.
3. 3.Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity — METR, 2025. Cited for the participant quote only; METR has since described the study's own evidence as weak.
4. 4.NoLiMa: Long-Context Evaluation Beyond Literal Matching — ICML 2025. Eleven of thirteen long-context models fell below half their short-context baseline at 32K tokens.
5. 5.Effective context engineering for AI agents — Anthropic Engineering, 2025.
6. 6.Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? — ETH Zürich / LogicStar, 2026. Generated context files: −0.5 to −2 points; developer-written: +2.4, not significant; cost +20–23%.
7. 7.Descriptor Format of Catalog Entities: Kind: Component — Backstage documentation. The example above is copied from this section as it is.
8. 8.Legacy Modernization meets GenAI — Thoughtworks on martinfowler.com, 2024.
9. 9.DORA Research: 2025 — DORA, Google Cloud. The 2025 research home; the findings quoted here are in its report, State of AI-assisted Software Development 2025. A survey, so these are correlations, not causes. The amplifier line is the report's own framing.
10. 10.Writing code is cheap now — Simon Willison, 2026.