10 Lines to Give Your Coding Agent Before It Touches Your Repo
Every coding agent reads your repository before it changes it. The only place you get to set defaults for that reading is the instruction file: AGENTS.md, CLAUDE.md, whatever your tool calls it.
The ones I run with are long, and most of that length is context. But ten lines do most of the work. If you are writing yours for the first time, start here, in this order, and skip everything else until one of these lines proves insufficient.
1. The Scope Sentence
One line saying what this repo is. Every prompt the agent assembles gets anchored by it, and without it, the agent guesses your project's shape from the file names.
This repo is a Python CLI for log reconciliation. Python 3.12. No web framework. 2. The Verification Command
The exact command that proves the work. "Run the tests" is not a command, it's a wish. Give the one unambiguous line, and make it fast enough to run constantly.
Verify with: pytest tests/test_parser.py -k "failing_case" (that test only) 3. The Smallest-Command Rule
Run only what the current step requires. No full suites between steps, no re-runs of checks that already passed, nothing run "to be safe." Curiosity is for humans.
4. The Do-Not-Touch List
Name the paths that must never be regenerated or edited: generated directories, secrets, lockfiles, release notes you don't own. The agent cannot respect a boundary it was never told about.
Never edit: docs/generated/, .env*, pnpm-lock.yaml, CHANGELOG.md 5. The Ticket Workflow
Test first: write the test, watch it fail, write the code, watch it pass. One ticket at a time. This single line converts an agent from a generator into something shaped like a TDD machine, and even badly executed, the shape holds.
6. The Reporting Contract
Report the diff and the test result. Nothing else. No narration between steps. You are going to read the log either way, so make it the log.
7. The Honesty Clause
Never present blocked or partial work as done. If the step cannot complete, say exactly what is missing and stop. This line is the difference between an agent you trust and an agent you audit.
8. The Known Traps
The three ways this repo bites: the command that hangs, the suite that lies (tests passing while the subsystem under test never actually ran), the file that must never be regenerated. You know them from the scars. The agent knows nothing until you write them down. 💡
9. The Stop-and-Ask Line
Ambiguity, destructive operations, anything touching a file another human or agent owns: stop and ask. One line, and it prevents most of the disasters.
10. The Context Budget
Keep the whole file under a page. It is re-read constantly, and every line spends attention. If a line hasn't changed agent behavior in a month, it is decoration. Delete it.
The file is a contract, not documentation. The agent holds up its side with suspicious consistency. The human side is the one that rots, so re-read yours before the next agent run, not after the next incident.
Comments usually end up better than the article on this topic, so: what's your #11?
References
- The agent-instruction conventions this builds on (AGENTS.md et al.) are documented across the major coding agents; the structure above is distilled from the instruction files I actually run with, including the working rules in this repository.
