Rules I added to my AI coding agent's contract after it wasted my time or lied to me. Nine revisions in four months; the rules that came out of a specific incident still carry their dates.
The file is CLAUDE.md.
- Claude Code: copy it to
~/.claude/CLAUDE.md(all your projects) or a repo root (that repo only). On Windows that's%USERPROFILE%\.claude\. The agent definitions go to~/.claude/agents/(user-level) or.claude/agents/(project-level) — keep their YAML frontmatter, it is what registers them. Start a new session after installing; the files are read at session start. - Codex: most of the contract works as an
AGENTS.md— copy it to~/.codex/AGENTS.md. Other tools: copy it to wherever your tool reads its instruction file (check your tool's docs; I haven't verified paths beyond these two). Sections 10–11 and the two agent files assume Claude Code's subagents and compaction; skip or adapt them elsewhere.
Then delete every rule that doesn't match a failure you've actually seen. Don't rewrite it from scratch and don't adopt it whole — a rule you never got burned by is a rule you won't enforce. If you don't know where to start, keep sections 1–3 and 6; they carry the most weight.
Two agent definitions come with it: agents/verifier.md
(the acceptance checker, wired into contract section 10) and
agents/scout.md (read-only research, optional — the
contract works without it).
I had a contract full of verification rules. Verify before answering, cite file:line, label unverified claims. All of it written after real incidents, and all of it pointing one direction: check more.
Then a review harness I built ran twenty-one rounds on one slice of work. The last five rounds found nothing that changed behavior. One round changed nothing at all. I had also written the review packets in a way that asked reviewers to produce findings, which reliably produces them.
The old rules were fine. None of them said when to stop, so the harness kept going. That incident produced the one rule most agent guidelines are missing:
A decision earns scrutiny when at least one is true: it introduces or modifies branching logic; it crosses a module or service boundary; it asserts a property the compiler cannot check; its correctness depends on context a future reader cannot see; its blast radius is irreversible.
It does not, for: renames, formatting, file moves; following a clear instruction; reading code that is already open; one-line changes obvious on sight; running tests or listing files; anywhere the user asked for speed (which lifts extra self-review only — never the honesty rules, and never checks on money, deployments, or data changes).
A review loop needs its stopping condition fixed before the first round. One clean round closes it. A second clean round establishes nothing the first did not. And a review request may not ask the reviewer to assume a defect exists — that reliably produces findings whether or not any are there.
The rest of the contract points the other way: check more. An honesty floor, a four-step test before consequential claims, a repair protocol for when the agent gets caught, task sizing, compaction instructions. They're in the file.
Agents mark their own work done. So acceptance runs through a check the author doesn't control: either a separate verifier agent, or an explicit switch into a reviewer role that re-reads everything from disk.
The shipped verifier agent gets three things — the acceptance conditions, the file paths, and the commands to run — and not the author's summary. It reads the files back from disk, runs the commands itself, and judges each condition PASS / FAIL / UNVERIFIABLE with output quoted. One FAIL fails the unit; UNVERIFIABLE is not PASS, and a unit with any unverifiable condition comes back BLOCKED, not passed.
To dispatch it in Claude Code, ask for the verifier agent by name and paste
three blocks:
Use the verifier agent to check this unit.
Conditions: 1) pytest -q tests/test_x.py exits 0 2) no file outside src/x.py changed
Files: src/x.py, tests/test_x.py
Commands: pytest -q tests/test_x.py; git diff --stat
No subagents in your tool? Open a fresh session, paste the same three blocks, and tell it to act as the reviewer — the point is that the checker didn't write the code and doesn't get the author's story.
One honest caveat: its tool list has no Edit and no Write, and its rules forbid modifying anything through Bash — but Bash could. This is enforced policy plus missing tools, not a physical lock. If your platform can sandbox commands read-only, add that.
This is one person's contract, shaped by one stack and one set of failures. No benchmark backs it. The evidence is that the specific failures behind each rule stopped recurring, which is weaker than a measurement and stronger than nothing.
It is also long, and every line costs context tokens each session. That's why the advice is to delete rules, not collect them.
The verification-ceiling trigger and exclusion lists are adapted from
addyosmani/agent-skills (MIT),
skill doubt-driven-development. The source-pinning rule comes from the same
repo's source-driven-development. Task sizing comes from
MrLesk/Backlog.md (MIT). The
maker/verifier split comes from
DennisWei9898/fable-commander (MIT).