Repository intelligence isn't a context graph

A few weeks ago I asked Claude to tidy up a date helper in mycaminoguide.com. Small job. It gave me back a cleaner function than the one I wrote, properly typed, with the edge case I'd been ignoring for a year. I merged it, felt good about myself, and two days later the daily stage emails went out with the wrong dates for anyone in a timezone behind UTC.

The code was better. The code was also wrong, because it didn't know that the stage scheduler treats every date as Madrid local time on purpose, and that the reason is buried in a commit message from 2024 that says "don't normalize to UTC here, pilgrims read this in Spain."

That gap has a name now. GitHub's chief product officer Mario Rodriguez called repository intelligence the defining edge for developers in 2026, and every tools vendor has been racing to claim the term since. Most of them are describing a context graph and putting a different label on it. Those aren't the same thing, and the difference is exactly the thing that broke my emails.

What a context graph actually is

A context graph is a machine-derived map of your repository. Parse the code into an AST, walk the imports, resolve the call sites, and you get nodes and edges: functions, classes, modules, interfaces, tests, packages. Calls, imports, inherits, implements, covers.

Once it exists you can ask questions that flat retrieval can't answer. What's the blast radius if I change this interface? Who are all the callers of this deprecated function across six services? Which modules have no test coverage and no owner? Harness makes this argument well in Your repo is a knowledge graph, you just don't query it yet, and their framing is right: a 300,000-line codebase doesn't fit in any context window, so you stop shipping text at the model and start shipping structure.

You can run one today. CodeGraphContext indexes a local repo into a graph database and exposes it over MCP, so the agent queries relationships instead of grepping. There's an open standard forming around it in Code Context Graph, and an academic version, the Repository Intelligence Graph, which builds a deterministic build-and-test centered map rather than a probabilistic embedding one. That determinism matters. An embedding says "these two files feel related." A graph edge says "this function calls that function on line 41."

All of this is good. I run a graph over getbitwit.com and it has saved me from at least three refactors that would have quietly orphaned a screen. But notice what every one of those queries has in common: the answer was already sitting in the source, and the graph just made it cheap to find.

Repository intelligence is the part that isn't in the source

Nothing in my repo says "Madrid local time is deliberate." The AST doesn't know it. The call graph doesn't know it. A blast radius query would have flagged the callers of that function and told me all six of them still compiled, which they did, all the way to production.

Repository intelligence is the whole picture: relationships, history, conventions, and intent. The graph gives you the first one for free. The other three are things a human decided, usually in a hurry, usually in an argument, and then wrote down badly or not at all.

Think about what your best senior engineer knows that a parser can't extract. They know the payments module looks over-abstracted because you tried the simple version in 2023 and it fell over during a sale. They know two services have near-identical retry logic and one of them is the good one. They know which tests are load-bearing and which are theater. They know the API returns a string for that field because a client shipped against it and you can't change it now.

Every one of those is a fact about the codebase. None of them are facts in the codebase.

That's why I don't love how the term is getting used. A vendor sells you repository intelligence and delivers a graph, which is real engineering and genuinely useful, and then you're surprised when the agent still writes something that's technically correct and organizationally insane. You bought the map. Nobody sold you the local knowledge.

The graph is derived, the intent is authored

Here's the split I use when I'm deciding where to put effort.

Anything a compiler could figure out belongs in the graph, and you should not be hand-writing it. Dependency lists, call hierarchies, coverage, module boundaries. If you're maintaining a hand-written architecture doc that lists which files import which, delete it. It's already wrong and a tool can regenerate it perfectly on every commit.

Anything that required a human decision has to be authored, because there is no other source. That's your CLAUDE.md or AGENTS.md, your skills, your ADRs, and honestly your commit messages. The reason my date bug happened isn't that Claude was careless. It's that the only place the intent lived was a commit message the agent had no reason to read.

Concretely, the four things worth writing down, in order of how often they've saved me:

1. Decisions with a reason attached. Not "we use Madrid time" but "we use Madrid time because pilgrims read the email in Spain, and normalizing to UTC shifted every stage a day for US subscribers."
2. Dead ends. The approach you tried and abandoned, and what broke. Agents love re-proposing the thing you already rejected, because on paper it's the obvious solution.
3. Which patterns are canonical. When two implementations of the same idea exist, say which one is the reference and which one is legacy. A graph will show the agent both and have no opinion.
4. Constraints that come from outside the repo. Contracts, clients you can't break, compliance rules, that one enterprise customer.

None of that is glamorous, and it's the same argument I made about structure over prose in API docs. Machines can't infer intent from vibes. If it matters and it isn't in the code, write it in a form something can read.

Where I'm still unsure

I don't think the authored layer scales the way people are assuming it will. On my own projects I'm the only decision maker, so the intent file is honest. On a team of forty, half the decisions were made by people who left, and the doc rots into fiction faster than anyone updates it. Stale intent is worse than none, because the agent trusts it completely.

I also suspect a chunk of this gets automated within a year. There's enough signal in commit messages, PR review threads, and incident write-ups that a model could draft the intent layer from history and let you correct it, rather than making you write it from scratch. That's the version I actually want, and it's not quite here.

Until then, the practical move is boring. Run a graph so your agent stops guessing at structure, and write down the reasons so it stops guessing at intent. The first one is a tooling problem someone else already solved. The second one is on you, and it's the part that's actually the skill.

If this was useful, subscribe here and come find me on YouTube at @seeqcode, where I build a lot of this stuff on camera.