Writing

Writing

AI Coding Agents Don't Always Need More Context. Sometimes They Need a Crib.

A practical argument for giving coding agents the right repository precedent, not just more context.

8 min readwritingenAICoding AgentsRepository ContextSoftware Engineering

I noticed something while working with AI coding agents on existing codebases.

The more specific I am about where the agent should look for precedent, the better its solution tends to fit the codebase.

There is a big difference between asking:

“Implement this behaviour on the Orders screen.”

and saying:

“We implemented something similar on the Payments screen. Have a look at that implementation and follow the same approach where it makes sense.”

In both cases, the agent understands the requirement.

But the second prompt usually gets me to a useful result much faster.

Without that reference, an agent may create a perfectly reasonable solution that simply doesn’t belong in that particular codebase. It might introduce a new service when we already have an abstraction for it, put logic in the wrong layer, invent another helper, or solve a problem that the application has already solved elsewhere.

The code can be valid.

The architecture can still be wrong.

That distinction has become more important as I use coding agents for larger tasks.

The agent knows how to code. It doesn’t automatically know how we code.

When a developer joins an established team, we rarely explain every design decision from first principles.

We say things like:

“Have a look at how we did this in Customer Details.”

“That service works like the Payments integration.”

“Use the same pattern as the existing background jobs.”

These are incredibly information-dense instructions.

An experienced developer doesn’t just copy the referenced code. They use it to infer things that haven’t been explicitly stated: where the logic belongs, which abstractions are intentional, how dependencies are wired, how errors are handled, what should be tested and, perhaps most importantly, what not to invent.

Coding agents need much of the same information.

There is research behind this problem too. Repository-level code generation performs better when the model has access to relevant information from elsewhere in the repository rather than only the file immediately being edited. The interesting question, then, is not simply how much context we can give an agent.

It is which context is worth giving it.

Because more context is not necessarily better context.

A huge instruction file can consume tokens and bury the useful information among hundreds of unrelated rules. OpenAI described running into exactly this problem while building an agent-first codebase: instead of turning AGENTS.md into a giant manual, they eventually used it more like a map pointing agents towards deeper sources of truth in the repository.

That made me think about a much older search problem.

Enigma, the Bombe, and the crib

Most of us know the broad story of Enigma and Alan Turing, even if our introduction to it came through films such as The Imitation Game.

But the part I find particularly interesting in the context of coding agents is not Enigma itself.

It is the relationship between the crib, the menu, and the Bombe.

The Bombe wasn’t simply given an encrypted message and told:

“Figure it out.”

Codebreakers tried to identify a likely piece of plaintext inside the encrypted message - a crib.

Certain messages contained predictable language. Weather reports, for example, naturally contained recurring words and phrases. Once a plausible crib had been identified, the relationship between the guessed plaintext and ciphertext could be used to construct a menu for the Bombe.

That crib did not contain the Enigma settings.

It wasn’t the answer.

It constrained where the answer could be.

The Bombe could then work through possible machine settings and identify candidates consistent with those constraints. Even a Bombe “stop” wasn’t automatically accepted as the answer; candidates still had to be checked.

That is the part that reminded me of coding agents.

When I tell an agent:

“We solved a structurally similar problem here.”

I’m not giving it the implementation for the new requirement.

I’m giving it a crib.

Instead of exploring every technically plausible way of solving the problem, it can start from a much narrower question:

How does this codebase already solve problems like this one?

That changes the search dramatically.

A reference implementation is more than an example

It is tempting to describe this simply as few-shot prompting: give the model an example and it produces something similar.

I think that misses part of what is happening in a codebase.

A good reference implementation carries architectural information.

It tells the agent something about the decisions made by the engineers who built the system before it arrived.

Suppose I ask an agent to add permission handling.

Without further context, several solutions might be sensible: a route guard, middleware, a component wrapper, a hook, a service, an API-level check, or some new abstraction.

Now I add one sentence:

“This screen uses the same permission model as Payments. Look at the Payments implementation first.”

Suddenly most of that search space becomes irrelevant.

The reference doesn’t tell the agent exactly what to write.

It tells it where in the solution space the right answer is likely to live.

There is an interesting connection here with research on analogical reasoning in language models. Models can use relevant previous examples to reason about a new problem rather than treating every problem as completely new. That has been demonstrated in several reasoning domains, including code generation.

For software engineering, however, we have an additional advantage:

the examples we need are often already sitting in the repository.

The harder problem is finding them.

So what can we do today?

We could wait for coding agents to become better at repository understanding. They undoubtedly will.

But there are some fairly simple things we can do with today’s tools.

The first is to improve the repository itself.

AGENTS.md, CLAUDE.md, Copilot instructions and similar files are useful places to document not only coding rules, but also architectural landmarks.

Instead of filling them only with instructions such as:

“Use dependency injection.”

or:

“Write unit tests for services.”

we can include pointers such as:

“For permission-based UI, see the Payments implementation.”

“For external API clients, use CustomerClient as the reference implementation.”

“Before introducing a new abstraction, search for a structurally similar implementation already in the repository.”

GitHub now supports repository-wide, path-specific and agent instruction files, while Anthropic similarly recommends keeping CLAUDE.md concise and using it to point Claude towards important files, commands and conventions.

But we can’t predict every future requirement when writing those files.

So the second part happens at prompt time.

If I already know that the feature I’m requesting resembles something elsewhere in the system, including that information is usually one of the highest-value sentences I can add to the prompt.

It saves the agent from discovering something I already know.

And it saves tokens that might otherwise be spent exploring irrelevant parts of the codebase.

There is also a third step, and I think this is the more interesting one:

agents should become good at finding their own cribs.

Before creating a new pattern, an agent should be able to search the repository for structurally similar implementations, compare them, identify the strongest precedent, and use that as part of its plan.

Something like:

Requirement -> find similar implementations -> identify architectural precedent -> plan -> implement -> verify.

At that point, repository search stops being just “find code containing these words.”

It becomes part of the reasoning process.

What I’ve been experimenting with

A lot of my recent experiments with AI-assisted development have gradually been moving in this direction, although I didn’t initially think of them in terms of “cribs.”

I’ve experimented with indexing repositories so local models can retrieve codebase context, with agent workflows where different agents take different roles in the software delivery process, and with repository-level instructions designed to give coding agents more persistent knowledge about the systems they are working in.

The more I’ve used these approaches, the more convinced I’ve become that retrieval alone isn’t quite enough.

Finding code that is related to a task is useful.

Finding the code that represents the precedent for that task is much more valuable.

That is a slightly different retrieval problem.

And perhaps a more interesting one.

If we can make architectural decisions easier for agents to discover - through documentation, better repository structure, explicit references and smarter search - we spend less time correcting perfectly valid code that simply doesn’t belong where the agent put it.

The model is only part of the system

Coding models will get better.

Context windows will get larger. Repository search will improve. Agents will become better at navigating large systems without help.

But I don’t think that removes the engineering problem.

A large codebase contains thousands of possible clues. Most of them are irrelevant to the task in front of us.

The job is not simply to give an agent more information.

It is to help it find the information that changes its search.

That was one of the clever ideas behind the crib: a relatively small amount of well-chosen information could turn an otherwise enormous search problem into a much more constrained one.

The machines are very different today, and so are the problems.

But the principle feels surprisingly familiar.

Sometimes the breakthrough isn’t searching faster. It’s finding the right crib first.

Sources and further reading