Repository Instructions for Coding Agents
A coding agent works better when the repository explains how work should be done — not just what the code currently looks like.
What repository instructions are for
A human developer can learn a project's conventions over days or weeks. A coding agent often starts a task with none of that history. Repository instructions reduce that gap by making the project's operating rules explicit.
The useful question is not “How do I prompt the model to be smart?” It is “What facts would a competent new contributor need before changing this repository?”
Instructions should complement the code and documentation, not duplicate the entire repository. They are most valuable for facts that are easy to miss or expensive to discover by trial and error.
What to include
Good repository instructions usually cover five areas:
- Project map. Identify the important applications, packages, generated directories and ownership boundaries.
- Commands. Give the exact install, development, build, lint, type-check and test commands that are relevant to normal changes.
- Change constraints. State files that must not be edited manually, compatibility requirements, migration rules and security-sensitive areas.
- Conventions. Document project-specific patterns that cannot be reliably inferred from generic language or framework style.
- Verification. Explain the minimum evidence expected before a task can be called complete.
Prefer executable facts over adjectives. “Run npm test for application changes” is useful. “Write high-quality code” is not a project instruction because it does not tell the agent what evidence to produce.
A compact example
Project: static Eleventy site.
Install: npm install
Build: npm run build
Release check: npm run release-check
Source files live in src/. Never edit _site/ manually; it is generated.
Use existing layouts and CSS utilities before adding new patterns.
Do not add a page to the sitemap when it has noindex.
Before finishing a content or template change:
1. run npm run release-check;
2. inspect changed internal links;
3. report the files changed and any check that was not run.
This is intentionally short. The agent can inspect package files and source code for details. The instructions supply the project's non-obvious contract.
Large repositories may need broad root instructions plus narrower documentation near a package or subsystem. Keep the scope obvious so a local rule does not accidentally become a repository-wide rule.
What not to put in instructions
Avoid enormous style manuals, stale command lists, secrets, credentials and vague personality prompts. Do not encode a fragile description of every directory when the filesystem itself is the authoritative source.
Conflicting instructions are particularly costly. If one document says to run a full suite and another says never to run it locally, an agent must guess which rule has priority. Remove obsolete rules rather than stacking exceptions indefinitely.
Keep instructions testable
Treat repository instructions as code-adjacent documentation. When a command changes, update the instruction in the same change. When an instruction says a generated directory must remain untouched, a build check can often enforce that rule more reliably than prose alone.
The strongest instruction set therefore has two layers: clear written constraints for decision-making and automated checks for facts that a machine can verify.