Your repository is the context, and it is a mess

An agent opens a ticket that says “add caching to the customer lookup”. It then goes looking for how this codebase caches things. It finds four answers: a Redis wrapper written in 2022, a decorator someone added last year that wraps the same Redis wrapper differently, an in-memory LRU in the reporting service, and a half-finished branch’s worth of code in utils/cache.py that nothing imports.

All four exist. All four are in the repository. Nothing in the repository says which one is current, which one is deprecated, and which one was a mistake everyone agreed to stop repeating but nobody deleted.

The agent picks one. It picks reasonably. It will be wrong about a third of the time, and the reason has nothing to do with the model.

My position: the repository is the largest and least managed context input in your organisation, and for most teams it is the cheapest place to make agent output better. Retrieval tuning and prompt libraries are being funded while the corpus itself is left untouched, which is backwards.

A repository is a set of worked examples

We are used to thinking of a codebase as an artefact: the thing that runs. That was accurate when the only people reading it were the people maintaining it, and they read it in small, targeted slices with a colleague available to explain the confusing parts.

The moment agents entered the loop, the codebase acquired a second job. It became the training set for how work is done here. Not in the model-weights sense. In the much more direct sense that every generation run reads a sample of your code and infers conventions from it.

That inference has no way to distinguish between “this is how we do it”, “this is how we used to do it”, and “this is a thing one person did on a Friday in 2023 and nobody ever came back to”. Everything present is present with equal authority. Absence of a warning reads as endorsement.

What you think the agent reads

• The ticket
• The files it will change
• Your prompt or rules file
• The style guide, if you have one

What actually shapes the output

• Whichever similar code it found first
• Three competing implementations of the same concern
• A README that describes the 2023 architecture
• Dead code that nothing imports and nobody deleted
• The most-repeated pattern, correct or not

Context blindness has a treatable half

The failure mode everyone is naming now is context blindness: output that is internally coherent and incompatible with the repository it was written for. References to APIs that do not exist, or violations of local convention that no linter catches.

Half of that is genuinely hard. An agent cannot know that the payments team agreed in a meeting to stop adding retries at the call site. That knowledge was never written down anywhere, and no amount of repository hygiene surfaces it.

The other half is not hard at all. It is that the repository contains contradictory evidence and the agent resolved the contradiction differently than you would have. That is a corpus problem with a corpus fix, and it is remarkably unglamorous: delete things, mark things, and make the correct pattern the most common one.

Nobody wants to fund that. It has no demo. It does not appear in a roadmap. And it is very likely the highest-return week of work available to a platform team this quarter.

The four things a repository does not say

Walk through what an experienced engineer knows about your codebase that is nowhere in it.

Which of two similar modules is the one to extend. Which directory is a graveyard. Which test file is load-bearing and which one has been failing intermittently for a year with everyone quietly re-running the job. Which of the three config mechanisms will actually be read in production.

None of that is secret. It is all knowledge held in three or four heads and transmitted in review comments. It has never needed to be written down, because a human always stood behind the repository to interpret it. That is the same structure as an underspecified ticket, at a much larger scale, and it fails in the same way for the same reason.

Dead code nothing importsReads as an available utility. Gets extended, and now something does import it.

Two implementations of one concernReads as a genuine choice. The agent picks by proximity, not by policy.

A stale READMEReads as authoritative architecture. It is the one file explicitly written to be believed.

An abandoned experiment directoryReads as a sanctioned pattern, especially if it is well written. Quality is not recency.

Commented-out codeReads as an alternative under consideration. Sometimes it comes back.

What to actually do

Start with deletion, because it is the only intervention that removes a wrong signal rather than adding a competing one.

Dead code, abandoned branches merged in and never used, experiment directories, the old client that two files still reference. Every one of those you delete removes a vote for the wrong pattern. Deletion is also the only cleanup that cannot rot, which is not true of anything you write.

Then mark what you cannot delete. If the legacy path has to stay because six services still call it, say so in the file, in plain language, at the top, in the form of a statement about what new code should do instead. Not a ticket. Not a wiki page. In the file, because that is what gets read.

Then make the correct pattern the most frequent one. If you are migrating and you are thirty percent through, the corpus still says the old way wins. Either finish the migration or accept that every agent run is going to reproduce the old pattern and your review load absorbs the difference. That is a real choice with a real cost, and it should be made on purpose rather than by drift.

Then treat the README and the architecture docs as production surface. They are the highest-weight files in the repository for exactly the reason they are the lowest-priority ones for humans: nobody reads them, so nobody notices they are wrong, and the machine reads them first and believes them.

Where this breaks down

Deletion is not free, and it is not reversible in practice. Code that nothing imports today gets imported next quarter by someone who knew it was there. I have watched cleanup sprints delete a utility that turned out to be called by a cron job in another repository. Anyone recommending mass deletion owes you the caveat that the search for callers is harder than it looks.

The strongest objection is that this is a retrieval problem, not a corpus problem. If the tooling ranked recency, ownership and deprecation correctly, the mess would not matter. That argument is genuinely good, retrieval is improving quickly, and there is a real chance that in eighteen months the corpus hygiene I am recommending is largely obsolete work. I would still do it, because the same hygiene makes onboarding faster and reduces human error, so it survives being wrong. But I am not certain.

Consistency has a cost you may not want to pay. “Make the correct pattern the most frequent one” is a polite way of saying finish your migrations. Migrations are expensive, risky and unfashionable, and there are good reasons a team might rationally choose to live with two patterns for years. I am asking for a real budget here and should say so.

I have not shown that repository quality moves output quality by a measurable amount. I believe it does. What I have is a mechanism that is easy to state and hard to falsify, which is exactly the sort of claim that deserves scepticism. If you try this, measure the rework rate on generated changes before and after, and be prepared for the difference to be smaller than the argument implies.

And some of the mess is load-bearing history. Commented-out code sometimes encodes a decision. The weird retry loop is often correct and the comment explaining it was never written. A cleanup pass run without the people who remember why will remove real information and you will find out during an incident.

The takeaway

Your repository stopped being only an artefact and became a corpus. Every file in it is an example of how work is done here, weighted by frequency, with no way to distinguish current practice from historical accident. Prompts and retrieval get the attention because they are new. The corpus is where the leverage is, because it is large, it is unmanaged, and it is entirely within your control.

If you take one thing into next week: pick the concern your team argues about most often in review, grep for how many distinct implementations of it exist in your repository, and count them. That number is what your agents are choosing between, and nobody has ever looked at it.