Coding Agents Need Better Repositories, Not Just Better Prompts
A better prompt can rescue one coding-agent task. A better repository gives every agent durable authority, context, boundaries, validation, continuity, and evidence.
The most common way teams try to improve coding agents is with better prompts.
More detail. More examples. More rules copied into the chat. A larger context window to hold all of it.
Sometimes this rescues the task. It does not repair the environment — the next session starts with the same missing map, the same hidden commands, and the same reasons to guess.
Here is the real problem: coding agents fail most when the repository does not expose the contracts required to change it safely.
A prompt describes the task. The repository describes the world.
A useful task prompt answers a narrow set of questions:
- What outcome is required?
- What is in scope?
- What must remain unchanged?
- What evidence will count as done?
Those answers change from task to task. They belong in the prompt or task envelope.
Repository truth changes on a different clock. Package ownership, generated-source rules, validation commands, architectural boundaries, release procedures, and settled decisions should survive the session that discovered them.
When those facts live only in chat, every new session must reconstruct them. The agent searches. It infers. It asks the developer to repeat the same context — or it moves ahead without asking.
The prompt is temporary authority. The repository is durable operating context.
Both matter. They solve different problems.
For a practical placement model, see Context Engineering for Coding Agents. The short version is simple: task-specific intent belongs in the task; reusable repository truth belongs close to the source it governs.
The expensive failures happen before code is written
A bad coding-agent session often looks like a code-generation problem. The diff is wrong, so the team blames the model that wrote it.
The first wrong decision usually happened earlier.
The agent chose the wrong source. It edited a generated client instead of the schema or generator that owns it. The local diff looked reasonable. The next generation step erased the work.
The agent crossed an invisible boundary. It changed a shared package while solving a feature inside one service. Unit tests passed. A downstream contract broke somewhere the agent did not know to check.
The agent proved the wrong thing. It ran a fast test command and reported success, but the change required integration tests, generated-output checks, or a migration rehearsal.
The agent reopened a settled decision. It replaced a pattern that looked awkward without finding the decision record that explained the operational constraint behind it.
The agent handed back a claim instead of evidence. “Tests pass” arrived without the exact command, candidate identity, output, or known omissions needed for another developer to verify the statement.
These are repository-interface failures. A stronger model can sometimes infer its way around them. That is not a reliable operating system.
The goal is not to eliminate judgment. The goal is to make the first important decisions inspectable before the agent mutates the codebase.
Six contracts make a repository legible to an agent
A repository does not become agent-ready because it has more documentation. It becomes agent-ready when the documents, scripts, and workflows form explicit contracts.
1. Authority contract
The agent must know which instruction controls the current path and which source owns the current behavior.
A root AGENTS.md can establish the repository-wide defaults. A nested instruction file can narrow them for a package. A CLAUDE.md or tool adapter can point into the shared contract without becoming a second, drifting copy.
Authority also applies to code. If an API client is generated, the schema or generator is authoritative. If configuration is produced from a manifest, the manifest is authoritative. The repository should say this before an agent edits the derivative.
2. Context contract
The agent needs a compact map of the system it is entering.
That map should identify the important packages, runtime entry points, ownership boundaries, public contracts, and documents worth reading before a change. It should not narrate every directory.
A useful map reduces discovery cost. It does not replace discovery.
3. Boundary contract
The agent must know what it may change, what requires approval, and what must remain untouched.
Boundaries include scope boundaries, secret-handling rules, generated files, migrations, release automation, external side effects, and destructive commands. “Be careful” is not a boundary. “Do not edit generated/; change schema/openapi.yaml and run make generate” is one.
4. Validation contract
Every important claim needs an executable proof path.
A documentation change may require link and formatting checks. A package change may require unit tests and type checks. A schema change may require regeneration, a clean diff, integration tests, and compatibility proof.
“Run tests” forces the agent to guess which tests matter. A change-type-to-command map makes the proof surface explicit.
5. Continuity contract
Long tasks and multiple agents need durable state.
A checkpoint should record the intended outcome, exact candidate identity, files changed, decisions made, commands run, evidence produced, known omissions, residual risks, and the next verifiable action. Chat history is not a checkpoint. It disappears when the session ends or the task moves to another tool.
The coding-agent handoff template shows a repository-native shape for this contract.
6. Evidence contract
The reviewer needs to distinguish what was attempted from what was proved.
A useful handoff names the exact commands and their results. It identifies the commit or worktree state that those results apply to. It reports skipped checks and unresolved risks without hiding them behind “done.”
This is where a coding agent becomes reviewable. The agent is allowed to be incomplete. It is not allowed to make completion unverifiable.
These six contracts are the working model behind the agent-ready repository guide. The guide turns them into a maturity ladder and migration sequence.
AGENTS.md is a router, not a knowledge dump
Teams often discover repository context and put all of it into one instruction file.
The file grows. Rules from unrelated packages collide. Examples become stale. Agents spend context on details that do not apply to the current path.
A root instruction file works better as a router. It should tell the agent:
- what the repository is;
- which instructions control the current directory;
- where the authoritative source and architecture map live;
- which safety boundaries apply everywhere;
- which commands provide the default proof surface;
- what evidence a completed handoff must include.
Narrow rules should live nearer to the code they govern. Detailed architecture belongs in maintained documentation. Repeated command sequences belong in scripts or task runners. Decisions belong in short records with dates and reasons.
The instruction file points. The repository proves.
If you need a starting structure, use the AGENTS.md template and the current guide to writing AGENTS.md. Keep one shared repository contract, then add thin adapters for tools that use their own native entry points.
The prompt-first trap has a predictable shape
The same loop appears across teams:
- The agent makes a bad change.
- The team adds a warning to the next prompt.
- The agent makes a different bad change.
- The team copies more repository facts into the chat.
- The prompt becomes a temporary operations manual.
- A new session starts without that manual.
- The team declares the agent unreliable.
Step 7 skips the system diagnosis.
If a correction should apply to future tasks, the correction needs a durable home. If a check proves correctness, it needs a repeatable command. If an exception protects production behavior, it needs an authority trail.
Do not keep paying prompt tax for repository facts.
The deeper failure mechanisms are covered in Why Coding-Agent Prompts Fail and the coding-agent failure-mode taxonomy. Both start from the same question: where did the first wrong decision become possible?
Better repository context does not mean more context
More context can make an agent slower and less precise.
The repository needs the smallest complete set of facts that changes the next decision. This is different from copying every architecture document, issue, and convention into the session.
Good context has four properties:
It has authority. The agent can tell whether the source is canonical or merely descriptive.
It has scope. The rule says where it applies and where it does not.
It has a lifecycle. The team knows what event should update or remove it.
It has a proof path. The agent can test whether it followed the rule correctly.
A stale instruction file is worse than a missing one because it creates false confidence. Every repository contract needs an owner, a trigger for review, or an executable check that exposes drift.
This is why scripts beat prose for repeatable operations. It is why nested instructions beat one global wall of text. It is why a decision record needs a reason, not only a conclusion.
Test the repository in a clean session
A repository contract is not complete because the author understands it.
Open a clean coding-agent session. Do not provide the hidden explanation from the previous chat. Give the agent a representative change and ask it to answer six questions before editing:
- Which instructions control this path?
- Which file is the authoritative source for the behavior?
- Which files are in scope and out of scope?
- Which exact commands will prove the change?
- Which decisions or compatibility constraints apply?
- Which evidence will be returned at handoff?
Score each answer as found, inferred, or missing.
Found means the repository exposed an authoritative answer. Inferred means the agent guessed from code shape or convention. Missing means the agent could not proceed safely.
Repair the first inferred or missing answer. Run the test again.
That loop is more useful than adding another page of general advice because it measures whether a new session can make the right first decisions without access to the maintainer’s memory.
For a broader scoring system, use the 100-point agent-readiness audit.
A minimum repository contract you can add this week
You do not need to redesign the codebase. You need five small surfaces that agree with each other.
1. A root router. Add a compact AGENTS.md that names the repository purpose, instruction precedence, global boundaries, authoritative maps, default validation entry point, and handoff requirements.
2. A source-of-truth map. For each important generated or derived surface, name the source that owns it and the command that reproduces it.
3. A validation map. Map common change types to exact commands. Include the expensive checks that are conditional, not just the fast default.
4. A decision record. Write down one recurring architectural exception with its reason, scope, and review trigger. Start with the decision agents keep trying to reverse.
5. A clean-session gate. Test a representative task with no hidden chat context. Record the first wrong guess and repair the repository surface that allowed it.
Do not add all possible documentation. Add the contract that removes the next expensive guess.
The open-source repository-harness project packages these ideas into templates, installation flows, validation surfaces, and safe maintenance commands for existing repositories.
FAQ
Are better prompts still useful for coding agents?
Yes. A prompt should describe the current outcome, scope, constraints, and acceptance criteria. Durable architecture, validation commands, safety boundaries, and decision history belong in the repository.
What makes a repository good for coding agents?
A good repository makes six contracts explicit: authority, context, boundaries, validation, continuity, and evidence. The agent can find the right source, stay inside scope, run the right checks, resume from durable state, and prove its claims.
Is an AGENTS.md file enough?
No. AGENTS.md is a routing layer. It should point to canonical documentation, exact validation commands, scoped instructions, decision records, and generated-source rules that the repository maintains.
Should one root instruction file contain every rule?
Usually not. Keep the root file compact. Put narrow rules close to the code they govern, and keep tool-specific adapters thin so shared truth does not drift across several files.
How do you test whether repository context works?
Use a clean session. Ask the agent to locate the code, identify controlling instructions, state the scope, name the validation commands, and describe the evidence it will return. Every guess is a repository-interface defect worth inspecting.
Does this only matter for autonomous coding agents?
No. Human-guided agents use the same context and proof surfaces. Better contracts improve planning, review, handoff, and recovery even when a developer approves every change.
Where should a team start?
Start with one root router, one source-of-truth map, one validation map, one decision record, and one clean-session test. Repair the first wrong guess before adding more documentation.
What to do Monday
Pick one task that recently required repeated correction.
Run it again in a clean session. Watch the first wrong decision. Put the missing authority, boundary, command, or decision into the repository surface that should have answered it.
Then run the same task once more.
A better prompt can rescue today’s session. A better repository changes every session that follows.