Rules or machinery

I once opened a small repo, a dozen files of client-side code, that came with a full governance framework for the AI writing it: change requests, specs, mandatory session files, a table of agent roles, lists of what was forbidden and what was required. One of the rules said every change needs a test. There was no test runner.

That is the mistake in its purest form, and it is an easy one to make. The short version of what I took from it:

• If something has to hold every time, whoever is typing, put it in machinery.
• If it needs judgement and context the code already shows, leave it to Claude, and spend the effort on making that context good.

Why rules are not enough

A model forgets everything between sessions. Each new session knows the code, the git log, CLAUDE.md and whatever memory it is given, and nothing else. A rule I intend it to follow can be missed, or a fresh session never hears of it. That is not sloppiness, it is how the thing works.

It is the same reason you do not trust a team to remember to run the tests: you put them in CI. The only difference is that the forgetting is total, so you reach the point where something must be automated sooner.

So on a bigger project the answer is rarely more rules for Claude. It is more guardrails that do not depend on Claude.

Three buckets

What it does anyway. Following the patterns already there, respecting boundaries it can see, planning before a big change. Writing "preserve modular boundaries" in a rules file restates what it does when it reads the code. It feels safe and enforces nothing. Don't write it down.

What it cannot work out. The only prose worth writing:

• invariants that matter and are not obvious, like "all drawing goes through one function; go around it and the preview stops matching the export". That one line is worth more than a governance framework.
• decisions and why, so it does not helpfully undo one.
• conventions that no single file shows: where things live, what they are called.
• what is half done and what is blocked.

The more you write, the less each line weighs. A 200-line CLAUDE.md drowns the three lines that matter.

What must be true every time. Tests pass, lint is clean, no secrets in a commit. Prose cannot promise any of that. A pre-commit hook, a CI check that blocks the merge, or a Claude Code hook that runs before a tool call can. They run whether or not anyone remembers the rule, which is the point.

Which one is it

When I am about to add a rule, I ask two questions:

In words:

1. Must it hold every time? If it can be checked automatically, it is a hook or a CI check. If it can't, a person owns it, as an explicit review step.
2. If it is a judgement call: is it obvious from the code? Then don't write it down. If not, it gets one line in CLAUDE.md.

As it grows

Claude keeps the judgement work. What changes is how much machinery sits around it.

Alone on a prototype, a tight CLAUDE.md and readable code are enough. With a team, add pre-commit hooks and a branch per task. With several agents working at once, add required checks that block a merge, and a worktree per agent. What was a good intention for one developer has to be a merge blocker when five agents work in parallel, because none of them remembers what the others did.

Rules that point at nothing

Two things to watch for. Rules that point at something that isn't there ("never bypass the validation scripts", in an empty folder). And required rules that cannot be followed, like the test rule with no test runner. The second is the worst: once one rule is broken in plain sight with no consequence, the whole framework teaches that rules are optional. That is a bad habit to carry into a project that actually needs them.

Match the weight of the process to the risk, and let the machine enforce what a machine can enforce.