Claude Code Hooks: Enforce the Rules Agents Forget

Claude Code hooks are shell commands, HTTP calls, MCP tools, prompts or subagents that Claude Code runs automatically at fixed points in a session: before a tool call, after a file edit, when Claude finishes its reply. They run every time instead of when the model remembers to, which the guide calls deterministic control, and that makes them the place for rules an agent must not skip (hooks guide). Below is how I would wire one around the content linter this blog already has, with every detail checked against the hooks reference.

Why a rule in a prompt is not enough

Claude Code's docs say Claude treats CLAUDE.md "as context, not enforced configuration", and that an instruction which must run after each file edit belongs in a hook (memory docs). Lauren Tan, an engineer at Cursor, makes the same point in a recorded talk: she layers rules, skills and a review bot but does not rely on them alone, because they are soft and agents can still forget them. She treats every rule a person has to enforce by commenting on a pull request as a code smell: it should become a lint rule or a CI failure instead.

That is what happened on this blog. Rules that used to live only in prompts now live in scripts/content_lint.py, which fails the run. One run here used 32 agents; a rule that depends on each of them remembering to run a script is 32 chances to skip it. A hook removes the remembering.

The events that can enforce a rule

Wording is quoted from the reference's event table and its exit code 2 table. PreToolUse stops an action before it happens. A linter belongs on PostToolUse and Stop: the file exists, the script reads it, and Claude gets the errors back.

Set it up

python3 scripts/content_lint.py content/blog/some-post.mdx
echo $?

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-mdx.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/lint-mdx.sh: lint every MDX file Claude writes or edits
FILE=$(jq -r '.tool_input.file_path // empty')
case "$FILE" in
  *.mdx) ;;
  *) exit 0 ;;
esac
if ! OUT=$(python3 "$CLAUDE_PROJECT_DIR/scripts/content_lint.py" "$FILE"); then
  echo "$OUT" >&2
  exit 2
fi
exit 0

export CLAUDE_PROJECT_DIR="$PWD"
echo '{"tool_name":"Edit","tool_input":{"file_path":"/full/path/to/bad.mdx"}}' | .claude/hooks/lint-mdx.sh
echo $?

#!/bin/bash
# .claude/hooks/lint-before-stop.sh: no "done" while a changed MDX file fails
INPUT=$(cat)
[ "$(jq -r '.stop_hook_active' <<<"$INPUT")" = "true" ] && exit 0
cd "$CLAUDE_PROJECT_DIR" || exit 0
FILES=$(git diff --name-only --diff-filter=d HEAD -- '*.mdx'
  git ls-files --others --exclude-standard -- '*.mdx')
[ -z "$FILES" ] && exit 0
if ! OUT=$(python3 scripts/content_lint.py $FILES); then
  echo "$OUT" >&2
  exit 2
fi
exit 0

"Stop": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-before-stop.sh",
        "args": []
      }
    ]
  }
]

What I keep out of hooks

Hooks guard the files, not the release. I approve every commit and push myself, and no agent pushes on its own. If you want that enforced rather than agreed, the reference says the if filter is best-effort and points to the permission system for a hard allow or deny: a deny rule Bash(git push *) refuses commands that begin with git push, though a push written another way, such as git -C . push, isn't matched.

Where this fits

The linter holds the rules and the hook makes sure it runs. Neither replaces the fact-checker agent that rereads the vendor's help pages, because no script knows whether a claim about Google Ads is true. How the hard checks and the softer layers fit together is in the guardrails I put around agents that write for this site.