Key idea
An agent starts each session knowing only what it reads. An instruction file in your repository is read at the start of every session. Put in it what you'd tell a new colleague on day one: how to run and test the project, the rules that aren't obvious, and what it must never do without asking.
What an instruction file is
A plain Markdown file at the root of the repository that your agent loads on its own. The name depends on the tool. For example, AGENTS.md is a shared convention that several agents read, and Claude Code reads CLAUDE.md. Other tools use a rules file or folder of their own; your agent's documentation gives the name.
It's committed with the code, so everyone on the project, and every agent they use, starts from the same rules.
What to put in it
- Commands. How to install, start and test. The agent will run them to check its own work.
- A map. Where the main parts live, in a few lines.
- Conventions the code doesn't make obvious.
- Rules, with the reason. "No new dependencies without asking" is followed more reliably than a bare "no".
- Never without asking. Actions that need you: anything that deploys, deletes, or touches secrets.
- Done means. What must be true before it says finished.
One for the starter
# Agent instructions: vibe-starter
Node 20 + Express tasks app. In-memory data; resets on restart.
## Commands
- Install: `npm ci` Start: `npm start` (port 3000, or $PORT) Test: `npm test`
## Map
- server.js: routes. lib/dates.js: due-date rules. lib/tasks.js: store, validation.
- test/: node:test tests, one file per lib file.
## Rules
- No new dependencies without asking: we keep the app small and auditable.
- Every route that changes or deletes a task checks the caller owns it.
- Secrets come from environment variables only. Never read or print .env.
- Fix bugs test-first: show me the failing test before changing code.
## Never without asking
- Running csph, git push, or anything that deploys, deletes or changes secrets.
## Done means
- npm test passes, and you've listed the files you changed and why.
About twenty lines. That's the right size.
Keep it short and true
The file is read in every session and takes up room in the agent's context, so every line should earn its place. Link to longer documents instead of pasting them. Leave out anything the code already makes obvious, and anything secret: this file is committed.
When the agent makes the same mistake twice, add one line that would have prevented it. When a rule stops being true, delete it; a stale rule is worse than none.
Review changes to it like code
An instruction file changes what the agent does in every future session, so treat a change to it with the same care as a change to the code, especially one an agent proposes itself. And remember it isn't a fence. Other text the agent reads, such as a README in a dependency, an issue or a web page, can contain instructions too, and a model may follow them. What stops a harmful action is your approval before it runs, not a line in this file.
Check yourself