Automation Hook Ladder — Claude Code Guide

Deploy automation in steps

A reliable hook is useful in a repeatable situation, predictable, and easy to disable. Start with observation rather than blocking: first confirm that the matcher covers the intended area.

Non-blocking mode fits early experiments. Use blocking only for a narrow, stable, well-checked rule.

Step	Behavior
1. Log-only	Record the trigger without changes
2. Non-blocking	Show a light check or report
3. Formatting	Change only an allowed file through a formatter
4. Test/report	Run an inexpensive check or remind about targeted tests
5. Narrow blocking	Block one specific risky action
6. Policy-managed	Shared artifact with documentation and kill switch

Safe first scenarios

Format the changed file.
Run a light lint or short report.
Remind about a sensitive module.
Protect one path.
Show a session rules banner.

Format-on-edit baseline

Limit the matcher to a source directory.
Enable log-only and inspect actual paths.
Add the formatter after several safe sessions.
Pass only the changed file.
Exclude generated and snapshot files.
Keep the handler non-blocking.
Check both an ordinary and excluded file.

One hook function

after file edit:
  if path matches frontend/src/**/*.tsx:
    format only this file
  if path is generated or snapshot:
    exit without changes

When blocking is allowed

A blocking hook fits only when the matcher is very narrow, the rule is stable, the team understands the consequence, and a simple disable or bypass exists. If automation interferes, return to an earlier step: narrow the matcher, remove blocking, or use log-only.