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 (6)
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.
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 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.
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.
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.