CLAUDE.md contracts and Stop hooks tame Claude Code's "done" problem
Developer JDiz00 shares a practical Claude Code setup built around a strict CLAUDE.md contract and a "Stop" hook that blocks the agent from claiming a task is done unless it has actually run a verification step.
Score breakdown
The Stop hook mechanically prevents Claude Code from handing back a false "green checkmark" — closing the gap between the agent claiming completion and actually verifying it — without requiring any prompt engineering.
- 01The CLAUDE.md is written as a binding contract with rules like 'answer first, explain only if asked' and 'never say a task is complete without verifying it.'
- 02A 'Stop' hook blocks the agent from ending its turn if it modified code and claimed completion but ran no test or build command that session.
- 03The hook demands the agent run the feature, test it, or explicitly state what it could not verify.
JDiz00 opens by diagnosing a common Claude Code frustration: the model forgets prior context, edits the wrong files, and declares broken builds complete. Their conclusion is that the model itself is not the problem — the missing piece is a disciplined harness around it. The solution starts with a CLAUDE.md file written as a non-negotiable contract rather than a loose style guide. Key rules include answering before explaining, halting at genuine decision forks to present options rather than guessing, and never marking a task done without running it, testing it, or explicitly stating what could not be verified.
The enforcement layer is a Claude Code "Stop" hook — a script that runs when the agent attempts to end its turn.
The enforcement layer is a Claude Code "Stop" hook — a script that runs when the agent attempts to end its turn. The hook checks whether the agent changed code and claimed completion without running any verification command that session; if so, it blocks the stop and forces the agent to actually verify. JDiz00 describes the logic as a few dozen lines that eliminated nearly all false "it worked" reports. Beyond verification, the setup routes subagent tasks by cost tier: cheap fast models handle recall, inventory, and summarization, while stronger models are reserved for implementation, tests, and deep diagnosis — with a pre-spawn hook that auto-assigns the tier. A file-based memory system (one fact per file, with a one-line index loaded each session) and a knowledge graph over notes let the agent surface prior work before re-researching or rebuilding it.
JDiz00 packaged the two highest-leverage pieces — the CLAUDE.md contract and the verify-before-done guardrail — into a free starter kit available on Gumroad on a pay-what-you-want basis with a $0 option and no email wall.
Key facts
- 01The CLAUDE.md is written as a binding contract with rules like 'answer first, explain only if asked' and 'never say a task is complete without verifying it.'
- 02A 'Stop' hook blocks the agent from ending its turn if it modified code and claimed completion but ran no test or build command that session.
- 03The hook demands the agent run the feature, test it, or explicitly state what it could not verify.
- 04Subagents are routed by task tier: cheap fast models for recall/summarization, mid models for implementation/tests, strong models for deep review.
- 05A pre-spawn hook auto-assigns the model tier so the routing happens without manual intervention.
- 06A file-based memory system stores one fact per file with a one-line index loaded each session to prevent re-researching prior work.
- 07The CLAUDE.md contract and verify-before-done hook are packaged as a free, pay-what-you-want starter kit on Gumroad with a $0 option.
Topics
Summary and scoring are generated automatically from the original article. We always link back to the publisher and never republish images or paywalled content. Last processed Jun 20, 2026 · 08:55 UTC. How this works →