Five rules Claude Code can't skip
We gave Claude Code real features on our own TypeScript invoicing API and caught it copying a validator instead of reusing it. This article lists five rules against codebase rot and, for each one, the Claude Code hook or setting that enforces it. Anthropic's documentation says a CLAUDE.md file is context, not enforced configuration, so a rule written there is a sentence the model weighs against the task. The enforcers below are files the harness runs: a duplication blocker that fires right after an edit, a turn that cannot end while tests are red, and configuration gates the agent cannot touch.
A rule you write, a check the harness runs
A Claude Code hook is a small script that Claude Code itself runs at a fixed moment, before or after a tool call. When the script exits with an error code, what it printed goes back to Claude as a refusal. Anthropic's best practices split instructions in two kinds: the ones you write and the model reads (a prompt, a CLAUDE.md file, a skill) and the ones you configure and the harness executes (a hook, a deny rule, a managed setting). The memory documentation says CLAUDE.md is for guidelines, and that Claude may decide a guideline does not apply.
We tested that split on a small invoicing API with no rules written, asking Claude for recurring schedules and a CSV export of the outstanding report. Claude came back green: typecheck passing, every test passing. A duplication detector told another story: the invoice parser had been copied line for line into the new schedule parser, and the handler's customer lookup into the new handler.
| Setup | Features | Exact clones found | Tests passing |
|---|---|---|---|
| Rules written as prose in CLAUDE.md | 1 | 0 | 45 |
| No rules written | 1, then a second one on top | 3, still 3 | 47, then 55 |
The clones stayed invisible in Claude's report across both features. Every enforcer in this article lives in one settings file inside the .claude folder, with a hooks block and a deny list.
Rule one: reuse before you write
The enforcer is a PostToolUse hook on the Edit and Write tools. The script reads the edited file's path from its input, runs jscpd on the source folder, and compares the clone count with a baseline stored in the repo, so old duplication does not block today's work. When the count goes up, the script prints the rule and the location of the twin and exits with code 2. The hooks reference says that after a tool ran, exit code 2 shows the message to Claude; a script that exits 0 is never seen, whatever it prints.
On the replay of the schedules feature with the hook installed, Claude wrote the new handler and the hook fired at once, naming the customer lookup in the invoices handler as the twin. Claude's next line was that the check was now in both handlers and that it would move it into the customer repository as one method called from both places. The detector was clean at the end and the shared check lived in a single place.
The limits: jscpd catches an exact copy, not a helper rewritten from scratch, and a hook that runs after the edit cannot undo it. It feeds back.
Rule two: no module nobody asked for
The enforcer is a PreToolUse hook on the Write tool. The script checks a single thing: is the path under the source folder and does the file not exist yet. If so, it prints a JSON decision that says ask with a reason, and Claude Code turns it into a permission prompt. The hooks reference gives a PreToolUse hook four possible decisions: allow, deny, ask or defer.
On the replay, Claude Code stopped and asked before each new module of the schedules feature. The feature called for a schedule module, a store and a handler, like the rest of the repo, so each one was approved. A later request to move the CSV helpers into a new utils module raised the same prompt, which was refused: Claude Code rejected both writes of that batch, the turn ended with nothing written, and Claude did not try again.
Two limits on the version we ran, 2.1.294: the prompt shows the file name and the reason goes to Claude's transcript, not to the dialog; and a file created through a shell command is not a Write tool call, so it slips past this hook.
Rule three: conventions are lint, not prose
The enforcer is the project's linter, run on every edited file by a hook. The conventions (type aliases instead of interfaces, no enums, no any, a domain layer that does no input or output) move from prose into the ESLint config: a restricted-syntax rule rejects an interface or an enum with the project's own message, and a restricted-imports rule keeps file access out of the domain folder. A PostToolUse hook on Edit and Write runs ESLint on the file that just changed and exits with code 2 on an error, so the violation reaches Claude at the exact line.
The words of the convention stay in a rules file under .claude/rules/ with a paths header, which loads the file only when Claude touches that folder. The memory documentation says a path-scoped rule loads when Claude reads, writes or edits a matching file, and warns that a header that does not parse makes the rule load everywhere.
Asked to turn a status union into an enum and a type into an interface, Claude edited nothing. It said the refactor would break the project's own rules, named the lint config and the hook that would flag the change, and offered a const object instead. Asked for a holidays feature that tempted a file read inside the domain, Claude passed the list in from outside, because the domain is not allowed to do input or output. The hook never had to fire. Fed a bad file by hand, it returned the errors at their lines and the refusal.
Rule four: done means the checks passed
The enforcer is a Stop hook, a script that runs when Claude wants to end its turn and can answer "not yet". The script runs typecheck and the test suite; when anything is red, it prints the failing output and exits with code 2. It also compares the number of passing tests with a stored baseline, so a suite that looks green because a test was deleted still counts as red. It checks the stop_hook_active flag the documentation describes, true when Claude is already continuing because of the hook, and exits 0 in that case so the hook never loops.
Playing the hurried developer, we asked for a quick rename of a report field and told Claude not to run the tests. Claude made the edit through a shell command, said the suite would now fail, and tried to end the turn. The hook ran the tests and refused with "Rule 4: tests fail. Not done yet." followed by the failing assertions. Claude's next line was that the project's stop hook requires green tests, so it would update the outdated expectations. The tests stayed in place.
The documentation caps the loop at 8 consecutive refusals, after which the turn ends anyway. A test rewritten to pass is not caught; a deleted one is. One trap: a widely shared thread complained that Claude ignores stop hooks, and the script in it exited 0, so the harness never blocked anything. The blocking code is 2, with the reason on the error channel.
Rule five: the agent can't loosen its own gates
Every check above has a shortcut: turn strict off in the compiler config, exclude the failing test in the runner config, delete the hook from the settings file. The enforcer is a deny list in the permissions block of the settings file, one Edit(...) line per file: the compiler config, the test config, the lint config and everything inside the .claude folder. The permissions documentation says deny rules are evaluated first and an allow rule cannot carve an exception out of a deny.
Asked to remove the stop hook because it slows things down, Claude read the settings and did not try: it said the file carries a deny rule on the .claude folder, that it could get around it with a shell command, and that doing so would bypass a protection the team deliberately set up. Asked to turn strict off, it refused on the written rule and ran the typecheck with a flag instead. Told to change it anyway, Claude reached for a shell command on the file, and the harness answered that permission to use that command had been denied. Claude's reply was that it had not tried another way around it, because that would defeat whatever put the block there.
The limit is documented too: a deny rule does not cover a script that opens the file itself, and the file can still be edited by hand. That is the point.
Which rule to install first
Each rule is a file you copy, not a sentence you hope Claude reads. With the rules as prose, one feature broke none of them; with nothing written, the next features left three exact clones that stayed; with the enforcers on, each one refused a real edit.
| If you install one thing | Why |
|---|---|
| The Stop hook | The most protection for the least setup |
| Then the deny list | Four lines in the settings file |
| Nothing | On a throwaway prototype |
When the suite takes minutes, keep the quick part in the hook and move the rest to the pipeline. The honest limit comes from a long issue on the Claude Code repository: a hook enforces what a tool call can show, and whether an abstraction is right stays a human call. The documentation's own rule of thumb: if you keep adding emphasis to a line in CLAUDE.md and Claude still misses it, that line belongs in a hook.
AIDive