The Repository Is the Prompt: Preparing a Codebase for Coding Agents
A coding agent did not fail to read the documentation. The repository stopped producing documentation years ago. Apparently, intelligence was expected to compensate for archaeology.
🗓️ Last updated: August 2026
A coding agent opens a repository, reads three files, changes a fourth, runs the wrong test command, and announces success. The team blames the model. The repository contains four build scripts, two abandoned architecture documents, and a README last updated when the application still had one database.
The model may indeed be imperfect. It has also been asked to infer a development system that the humans stopped documenting years ago. Apparently intelligence was expected to compensate for archaeology.
Coding agents do not work from source code alone. They work from the repository as an operating environment. File layout, naming, build commands, tests, local instructions, and dependency boundaries all become part of the context from which the agent decides what to inspect and what to change. The repository is therefore not merely where the prompt lands. The repository is most of the prompt.
What this article is not
This is not a guide to writing one enormous instruction file. A repository cannot be made legible by placing a small novel beside an illegible codebase. Instructions help most when they reveal stable facts that the code and tooling cannot express clearly.
Start with the executable truth
An agent needs one reliable path to restore, build, test, lint, and run the project. Those commands should work from a clean checkout. Put them in the repository and run them in continuous integration. If the documented command differs from the CI command, the documentation is decorative.
Keep the default path unsurprising. A command that requires three private environment variables, a manually created database, and knowledge passed down through oral tradition is not a build command. It is an initiation ceremony.
The repository should answer these questions without guesswork:
What command establishes a working environment?
What is the fastest relevant verification command?
Which generated files must not be edited?
Where do architectural boundaries live?
Which changes require broader tests or human approval?
These answers benefit humans immediately. Agent readiness is often ordinary engineering hygiene with a more impatient customer.
Write instructions for decisions, not syntax
Repository instruction files — AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, and equivalents depending on the tool — can describe project wide commands, conventions, and architectural rules. Folder specific instructions can narrow the guidance for a monorepo or a subsystem. Current Visual Studio Code documentation, for example, supports repository instructions and scoped instruction files (currently experimental) for coding agents.
Useful instructions state facts with operational consequences:
Run dotnet test tests/Orders.UnitTests for changes under src/Orders.
Do not edit files under Generated.
Database migrations require an integration test and schema review.
The Domain project must not reference Infrastructure.
Weak instructions ask for virtues:
Write clean, scalable, production ready code.
Follow best practices.
Be careful.
The second group sounds respectable and constrains almost nothing. A model can produce a confident interpretation of "best practices" just as easily as a committee can.
Keep instructions short enough to remain visible. Remove rules that tools already enforce. Formatting belongs in a formatter. Dependency boundaries belong in architecture tests. Secret scanning belongs in a scanner. Prose is appropriate where judgment is required, but prose should not impersonate enforcement.
Design the repository map
Large repositories need progressive disclosure. The root should explain the system shape and point toward deeper documentation. Each major area should identify its purpose, public boundaries, verification commands, and local hazards. The agent can then load the smallest useful context instead of pouring the entire repository into one conversation and hoping relevance emerges from volume.
A concise architecture map should name the deployable units, shared libraries, data stores, external contracts, and ownership boundaries. Link to source files and executable tests where possible. Avoid copying implementation details into documents that will drift independently.
Context engineering research from Anthropic emphasizes curating relevant information and controlling context growth during long running work. The same principle applies at repository scale. More context is not automatically better context. A hundred thousand tokens of stale detail is still stale detail, now with a larger invoice.
Make boundaries machine visible
If a layer must not reference another layer, test that rule. If an API contract must remain compatible, validate it. If a package can only be used in one module, encode the restriction in project structure or analysis. An agent is much more reliable when the repository rejects invalid changes than when a paragraph merely discourages them.
This is the key shift. The repository should be a constrained environment in which the easiest successful change is also an architecturally valid change.
Failure modes
The first failure is the repository constitution: hundreds of instructions that compete with the actual task and with one another. Stable, specific rules beat comprehensive prose.
The second is undocumented setup state. The agent succeeds in an environment that contains cached packages, old build outputs, or developer credentials, then fails from a clean runner.
The third is context by proximity. A file sits nearby, so the agent assumes it belongs to the same architectural boundary. Good naming and explicit maps reduce that ambiguity.
The fourth is instruction drift. If the command in AGENTS.md no longer works, remove or repair it immediately. Incorrect context is worse than absent context because it arrives wearing authority.
The architect's checklist
Make restore, build, and test commands work from a clean checkout.
Keep one documented default path aligned with continuous integration.
Use repository instructions for stable decisions and local constraints.
Provide a concise map of deployables, modules, contracts, and owners.
Encode architecture rules in tests and tooling wherever possible.
Test the repository setup in the same isolated environment used by agents.
A coding agent reveals the quality of the environment around the code. If it cannot discover how the system works, the uncomfortable possibility is that the repository has been relying on human memory as infrastructure.
