Enforce invariants with a failing test, not a warning

You have written the same correction into CLAUDE.md three times — don't change the signature of renderRow, don't touch the migrations folder, always keep the version pill in the footer — and Claude still walks past it every few sessions. The instruction is not being ignored out of malice. It is advisory text competing with everything else in a long context, and by turn forty it has lost.

The move is to stop writing the rule as prose and start writing it as something that returns a non-zero exit code.

Why the prose version keeps losing

The docs are unusually blunt about this. memory says Claude "treats them as context, not enforced configuration" and points you at a PreToolUse hook to block an action regardless of what Claude decides. best-practices says the same thing from the other side: "Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens."

So the reframe is not "write a better instruction." It is: an instruction you have had to repeat is a missing test.

The sharp version: "don't change this function signature" should not be a warning you hope lands. It should be an end-to-end test that fails when the signature changes. Claude sees the failure, reads it, and fixes it without you in the loop. Prose costs tokens on every turn and can be forgotten; a script costs milliseconds and cannot.

Where to put the gate

The community framing of this tip reaches for a git pre-commit hook. That works, but it is the weakest of the available layers, and the docs describe stronger ones. Pick by how early you want the failure.

hooks-guide has a worked PreToolUse example — a script that matches the target path against a protected-pattern list and exit 2s to block the edit, with the stderr message fed back to Claude. That is the shape to copy for "do not touch this file." For "do not break this behavior," a Stop hook running the test is the closer fit: best-practices calls it "a deterministic gate" that "blocks the turn from ending until it passes."

The invariant test, concretely

An invariant test is narrower than a normal test. It asserts one thing you have decided will not change, and its failure message says why, because the agent reading it has no other source for that.

# tests/invariants.sh — run by the Stop hook and by CI
set -euo pipefail

# The version pill is load-bearing: without it a stale service-worker
# cache is indistinguishable from a successful deploy.
grep -q '__BUILD_SHA__' src/components/Footer.tsx \
  || { echo "INVARIANT: Footer.tsx must render __BUILD_SHA__ (stale-cache detection)" >&2; exit 1; }

Two properties matter more than the grep itself. The message names the consequence, not just the rule — an agent that knows why will find a correct fix instead of a fix that satisfies the grep. And it is fast, because it runs on every turn.

A detail that supports the pre-commit version

If you do use a git hook, there is a real reason it is harder to defeat than it looks. permission-modes lists .pre-commit-config.yaml, lefthook.yml and friends as protected files, and .husky as a protected directory. Writes to those are "never auto-approved, except in bypassPermissions mode and in planning sessions with bypass permissions available" — default and acceptEdits prompt, dontAsk denies outright, and auto routes the write to the classifier rather than to you. So the agent cannot quietly rewrite the gate while fixing the thing the gate caught, though in auto mode "quietly" is doing more work than in the modes that prompt.

What is unverified here

Say it plainly, because it is the part that decides how far to trust this:

• Corroborated by the docs: hooks are deterministic and CLAUDE.md is advisory; PreToolUse exit 2 blocks an edit; a Stop hook gates the end of a turn; pre-commit config files are permission-protected.
• Not in the docs at all: the practice of converting a repeated prose correction into a test, the word invariant (it appears nowhere across the 77 pages), and any suggestion that a git pre-commit hook is the right enforcement layer. The docs consistently point at Claude Code's own hook system instead.
• Untested claim, and the important one: that an agent stopped by a git pre-commit hook fixes the underlying problem rather than reaching for git commit --no-verify. The docs say nothing either way. Nobody has run this.

To settle that last point, wire the check above into .git/hooks/pre-commit in a throwaway repo, give Claude a task that trips it, and then look at whether git log is empty and whether the transcript contains --no-verify. That single observation is what would move this entry from docs-corroborated to reproduced.