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.

7 min readwritingenAICoding AgentsRepository ContextSoftware Engineering
Also available in Turkish

I was looking into whether I could have several coding agents working on the same repository at the same time.

Git worktrees solved one part of that problem. Each agent could have its own working tree, so they were less likely to step on each other’s files. But that left a harder question: even if the agents were isolated, how would they know where a change belonged in a large codebase?

I had already noticed a smaller version of the same problem when using coding agents manually.

If I said:

“Implement this behaviour on the Orders screen.”

the agent could usually produce something that compiled.

If I said:

“We implemented something similar on the Payments screen. Look at that first, then follow the same approach where it fits.”

the first result was usually much closer to the codebase.

The difference was not that the second prompt explained the requirement better. It gave the agent a starting point inside the repository.

Without that reference, the solution was not necessarily wrong. That was the frustrating part. It could compile, follow a reasonable pattern in isolation, and still ignore an implementation three folders away that already solved almost the same problem.

A new service instead of an existing abstraction. Logic in the wrong layer. Another helper for something the project had already named and shaped.

Valid code, wrong home.

Existing Teams Work This Way

When a developer joins an established team, we rarely explain every convention 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.”

Those sentences carry a lot of information. They point to naming, dependency wiring, error handling, test style, layering, and the parts of the system that the team considers stable.

An experienced developer does not just copy the referenced code. They use it to infer what the team has already decided.

Coding agents need much of the same help.

Repository-level code generation research points in this direction too: models do better when they can use relevant code from elsewhere in the repository, not only the file being edited. The practical question is which repository context is worth pulling into the task.

A huge instruction file can make that worse. It consumes tokens and hides the useful pointer among general rules. OpenAI described a similar issue while building an agent-first codebase: AGENTS.md worked better as a map toward deeper sources of truth than as a giant manual.

That is what reminded me of a crib.

The Crib Analogy

The Enigma story has a useful concept here, without needing the whole history lesson.

Enigma created a huge search space. The Bombe did not blindly treat every possible setting as equally likely. Codebreakers looked for a probable fragment of plaintext in an encrypted message. That fragment was called a crib.

The crib was not the answer. It did not contain the machine settings.

It narrowed the search.

A likely weather phrase, for example, could be related to the ciphertext and turned into a menu for the Bombe. The machine could then test candidates that matched those constraints. Even a Bombe stop still needed checking.

That maps surprisingly well to the repository problem.

When I tell an agent, “we solved a structurally similar problem here,” I am not giving it the new implementation. I am giving it a crib.

A crib does not solve the problem. It tells you where to start looking.

A Reference Is More Than An Example

It is tempting to call this few-shot prompting: provide an example, get something similar back.

That misses the architectural part.

Suppose I ask an agent to add permission handling. Without a repository pointer, several options may look sensible: a route guard, middleware, component wrapper, hook, service, API-level check, or a new abstraction.

Then I add one sentence:

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

Most of the search space disappears.

The reference implementation tells the agent where this codebase expects the answer to live. It also tells the agent what not to invent.

There is a connection here with analogical reasoning in language models: relevant previous examples can help a model reason about a new problem instead of treating it as completely new. In software, the useful examples are often already in the repository. The harder part is finding the right one.

What I Do With This Today

The simplest version is prompt-level discipline.

If I know a task resembles something else in the product, I say so. One sentence can save a long repository wander:

“This follows the same validation flow as Customer Import.”

“Use the existing background job pattern from Invoice Sync.”

“Before adding a new abstraction, check whether the same shape already exists under Payments.”

The next version is repository guidance.

AGENTS.md, CLAUDE.md, Copilot instructions and similar files are good places for architectural landmarks, not just coding rules. I do not want them to become encyclopedias. I want them to point agents toward files, commands and conventions that matter.

For example:

For permission-based UI, start with the Payments implementation.
For external API clients, use CustomerClient as the reference.
For a new background job, inspect the existing Invoice Sync job before planning.

Those are not generic rules. They are cribs the repository can keep close to the code.

The more interesting step is having agents find their own cribs:

Requirement
  -> find similar implementations
  -> identify the strongest precedent
  -> plan
  -> implement
  -> verify

At that point, repository search is no longer just “find code containing these words.” It becomes part of the engineering reasoning.

Where My Experiments Are Going

My recent AI-assisted development experiments keep coming back to this problem.

I have tried local repository indexing, MCP-based tool access, role-based agent workflows, and repository instructions that give agents more persistent knowledge about the systems they work in.

Retrieval helps, but retrieving related code is not enough. The useful thing is finding the code that acts as precedent for the task.

That is a different search problem.

It also changes how I think about agent workflows. A Worker agent should not rush straight from requirement to implementation. It should first ask: where has this repository already made this kind of decision?

A Reviewer agent should ask the same question from the other side: did the implementation follow the right precedent, or did it create a new local pattern by accident?

This is why I care about repository instructions, run history, reviewer roles and human approval. They are not decoration around the model. They are the engineering system that decides whether generated code belongs in the product.

The Model Is Only Part Of The System

Coding models will keep improving. Context windows will get larger. Repository search will get better.

That does not remove the engineering problem.

A large codebase contains thousands of possible clues. Most of them are irrelevant to the task in front of the agent. The useful work is often narrowing the search before generation starts.

That was the clever part of the crib: a small piece of well-chosen information could turn an enormous search problem into a constrained one.

The machines are different now. The habit still feels familiar.

Sometimes the useful context is not more context. It is a good starting point inside the repository.

At Bletchley Park, a good crib helped turn Enigma traffic into life-saving intelligence. In our smaller engineering world, a good crib saves tokens.

Sources and further reading