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.
Top comments (12)
Really useful framing — the verification command and the honesty clause stood out to me, especially the point that a narrow passing test shouldn't become a claim about the whole system. My #11 would be a where-to-run line: the environments and data the agent may touch, and a clear ban on production data and credentials unless a human says otherwise. That feels like the missing boundary before the other ten lines can do their work safely.
My #11 would be an explicit escalation boundary for verification: what evidence is sufficient for this change, and what must stay unverified if a required environment or check is unavailable? A narrow test is a good first signal, but its green result should not silently become a claim about integration or production behavior. I’d have the agent name the checks it ran, the important ones it could not run, and the decision those checks can support.
That is the reporting contract with its missing half added. My version says report the diff and the test result; yours adds what the report owes when the proof is out of reach: the checks that ran, the important ones that could not, and the decision those checks can support. A green result that silently narrows its own scope is the failure I keep calling confidently incomplete: done-shaped, honest by its own lights, and quietly about a smaller world than the one being shipped to. Naming the unrun checks out loud turns that into a report a tired human can actually weigh.
Really practical advice, especially the “stop-and-ask” and honesty clauses. I think a useful #11 would be an explicit rollback rule — if an agent makes a change that causes an unexpected failure, it should know when to revert the change instead of trying to fix the problem by making more changes. Giving coding agents clear boundaries around failure recovery could make them much safer to use in real repositories.
A rollback line is a strong candidate for #11, and it belongs right after the honesty clause. The spiral you are describing is real: an agent that breaks something and then fixes the break it caused is two changes deep with zero human eyes on either one. The version I would write: if a change you made fails unexpectedly, stop and report. Reverting is a decision, not a reflex, and it belongs to the human, partly because a revert also destroys the evidence of what actually broke. The worst entries in my own breach log are this exact shape, a helpful fix applied on top of an unexpected failure without anyone asking whether the first move should have been back.
My #11 would be a freshness line: name the one place where the current state of the repo lives, like the open ticket or the latest decision note, and tell the agent to check it before starting. The verification command and the do-not-touch list are my favorites from your ten, because they turn vague caution into something checkable. The context budget also rings true. A short file gets reread, so every extra line really does cost attention.
The freshness line is a good #11 and the failure it prevents is easy to underestimate: without it, the agent reads a stale plan and executes it confidently, because everything in its context says the plan is current. The version I run is close to yours: name the one place the current state lives, and make reading it the first step of every task. In longer runs I go one step further and have the agent maintain a state file as it works, so the freshest facts get re-fed each step instead of aging inside the transcript. Same idea, different half-life.
My #11 would be a prove-it-ran line. #8 names the suite that lies — tests passing while the subsystem never actually ran — but nothing in the ten forces the agent to show the check really executed. I've had an agent report green on a suite that silently skipped the module it changed. One line: the verification report must include how many tests actually ran. If that number is zero, the run failed, whatever the exit code says.
Restricting workspace boundaries and setting strict diff inspection rules upfront saves hours of messy rollbacks. Giving agents clear guardrails is genuinely the difference between a productive pair programmer and a chaotic refactoring spree.
The do-not-touch list gets easier to audit if the final report names every changed path; a stray lockfile or generated file jumps out immediately. Do you use a lightweight diff check to catch those boundary slips?
I'd add a dependency freeze line: never bump versions, never regenerate lockfiles, never add a package unless the ticket explicitly asks for it. I've had an agent "fix" a type error by upgrading a library and quietly rewriting the lockfile. The do-not-touch list helps, but spelling out that installs are out of scope unless asked has saved me more than once.
The dependency freeze line is going straight into my file, because your type-error story is a perfect specimen of what my log calls judgment substitution. Upgrading a library to fix a type error looks like diligence from inside the run, and meanwhile it rewrote a lockfile nobody asked about. My version: never install, upgrade, or regenerate a dependency unless the ticket names it. A type error is a code problem by default, not a version problem. It pairs with the do-not-touch list rather than duplicating it: that list says which files are off limits, this one says which kinds of changes are out of scope entirely.