Most CLAUDE.md files mix three different kinds of rules. They look the same on the page, but they need completely different enforcement mechanisms. Getting this wrong means either over-engineering simple problems or leaving critical rules unenforced.

The problem

A typical CLAUDE.md might contain:

- Always run `npm run build` before pushing
- Never use inline styles
- Use gap for spacing, not margin on children
- Never modify .env files
- Always run tests before committing

These all look like instructions for Claude. But they fall into three distinct categories, and each one has a different right answer.

Layer 1: Git hooks (workflow rules)

“Run build before push.” “Run tests before commit.” “Lint before commit.”

These are development workflow rules. They apply to every developer on the team, human or AI. The right tool is a git hook.

# .git/hooks/pre-push
#!/bin/sh
npm run build || exit 1

A git pre-push hook runs every time anyone pushes, regardless of whether Claude or a human initiated it. It is simpler, more reliable, and already standard practice. Putting workflow rules in CLAUDE.md and hoping Claude remembers them is the wrong layer.

If you use Husky or lefthook, you already have this infrastructure. Use it.

Layer 2: PreToolUse hooks (output rules)

“No inline styles.” “Never modify .env.” “No HEX colors in components.”

These are rules about what Claude specifically writes or edits. They cannot be enforced by git hooks because the violation happens at generation time, not at commit time. By the time a git hook runs, Claude has already written the code and the user may have built on top of it.

PreToolUse hooks run before every tool call. They can inspect the file path, the content being written, and the tool being used. They block violations before they happen.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [".claude/hooks/no-inline-styles.sh"]
      }
    ]
  }
}

The hook script checks the content and returns {"decision": "block", "reason": "..."} if it finds a violation.

This is where enforce-hooks operates. It reads your CLAUDE.md, identifies rules that can be enforced this way, and generates the hook scripts. Mark a directive with @enforced and it becomes a hard gate.

Layer 3: Prompt only (semantic rules)

“Use gap for spacing, not margin on children.” “Prefer composition over inheritance.” “Keep functions under 20 lines.”

These require understanding context, intent, and code structure. No hook can reliably enforce them because the decision depends on judgment, not pattern matching.

For these rules, the prompt is the right place. Write them clearly in CLAUDE.md. Accept that compliance will be imperfect. If a semantic rule is critical enough to need 100% enforcement, find a way to express it as a linter rule or a concrete pattern that a hook can check.

How to sort your rules

For each rule in your CLAUDE.md, ask:

1. Does it apply to all developers, not just Claude? Git hook. Remove it from CLAUDE.md entirely.
2. Can you check it by inspecting the file path or content of an Edit/Write? PreToolUse hook.
3. Does it require understanding what the code means? Leave it in the prompt.

Most CLAUDE.md files have rules from all three layers mixed together. Sorting them into the right enforcement mechanism means the important rules actually get enforced, and the simple ones stop relying on prompt compliance.

The underlying principle

The further a rule is from the model’s context window, the more reliably it is enforced. Git hooks are completely outside the model. PreToolUse hooks run as external code. Prompt instructions live inside the context window, subject to decay and compaction.

Match the enforcement mechanism to the reliability you need.