Claude Code Hooks for Team Rules

Keep hooks narrow. Claude Code hooks from Anthropic are useful when a team wants a small rule to run at a known point in the coding session, not when the team wants to replace review, tests, or judgment with automation.

The official Claude Code hooks documentation answers the practical question first: which event can run which command, and when does Claude Code see the result? In a Claude Code workshop or team rollout, I would treat hooks as part of Team conventions: a shared boundary around file writes, tool calls, prompts, and final review evidence.

The Anthropic Claude Code hooks documentation is worth reading with a policy table beside it. The docs give the hook types and event behavior. Your team still has to decide which checks are allowed to block work, who owns them, and how a developer can see what happened.

Put hooks at boundaries the agent cannot judge

Use Claude Code hooks where the rule is mechanical. A hook can check that a generated file was not edited directly, run a narrow formatter after a write, or block a prompt that appears to contain a secret.

Do not use a hook for a rule that needs design context. If the question is whether a migration is a good idea, that belongs in review, not in a shell command wired into every agent session.

A concrete workflow I see teams reach for is a pnpm workspace where apps/web and packages/ui have different lint and test costs. A PostToolUse hook can run a cheap changed-file lint after edits in apps/web, while the full package test stays in CI or a human-triggered slash command.

Choose the event before writing the command

Pick the lifecycle event first, then write the smallest command that fits it. As of November 2026, I would use the official Claude Code hooks reference as the current source for event names rather than copying a private Claude Code hooks events list 2026 into the repo.

This is the part of the workflow that maps to Review in our methodology. The hook should make evidence easier to inspect, not hide the decision from the engineer.

Paste the hook policy before implementation

Write the convention before the hook script. That keeps the discussion about boundaries, owners, and failure behavior instead of turning the first implementation into the policy by accident.

# Claude Code hook policy

| Boundary | Hook event | Owner | Allowed action | Blocks work? | Review evidence |
|---|---|---|---|---|---|
| Generated API clients must not be edited by hand | PreToolUse | Platform | Block direct edits to generated client folders and print the generator command | Yes | Hook message includes the blocked path and generator command |
| Web edits should get fast feedback | PostToolUse | Web | Run changed-file lint for `apps/web` and `packages/ui` | Warn for first week, then decide | Hook log shows command, duration, and exit code |
| Prompts must not include copied secrets | UserPromptSubmit | Security | Detect obvious `.env` style values and ask the user to remove them | Yes | Redacted match count, no secret value stored |
| Agent completion should leave a review receipt | Stop | Repo maintainers | Append changed files, commands run, and open questions to the review receipt | No | `.claude/hook-receipts/latest.md` or equivalent path |

Adoption path: the person who wants the hook proposes one row, the repo maintainer reviews the boundary, and the team that owns the command reviews the runtime cost. Store the table beside the hook settings or in docs/ai/hook-policy.md; if you use CLAUDE.md, link to the policy rather than pasting the whole table into always-on memory.

Review rule: a hook stays enabled only while its evidence is readable by a developer who did not write it. Every blocking hook needs a clear message, an owner, and a documented way to fix or override the failure.

When a hook protects an external action, keep the integration permission separate from the hook policy. For GitHub-specific boundaries, the related note on Claude Code GitHub MCP Permissions is the place I would pair with this work.

Install one hook in three steps

1. Start with one row from the policy table and choose the matching event from the Claude Code hooks reference. Avoid implementing three hook types at once, because you will not know which one changed the team’s behavior.

2. Write the command as if it will run on a fresh developer machine. Check for missing tools, print a short failure message, and keep output small enough that it helps rather than floods the session.

3. Run the hook in warning mode where the workflow allows it, then review the evidence after a few real tasks. If the hook is noisy, slow, or unclear, fix that before it blocks work.

This is also where Claude Code training should be hands-on. People need to see the hook fire on an ordinary edit, read the message, and decide whether the rule helped.

Keep hooks boring and visible

Hooks run commands, so they inherit the usual command problems: missing dependencies, slow startup, platform differences, and unclear exit codes. A good hook feels like a small guardrail. A bad one feels like a flaky local CI system attached to every agent move.

Do not put secrets in hook logs. Do not make a hook call a production system unless the team has explicitly reviewed that boundary. Do not let hook scripts grow into a second build system.

Claude skills and repository memory can support this convention, but they should not carry the enforcement burden. Use skills for reusable instructions and workflows. Use hooks for the small checks that must happen at a specific lifecycle point.

Further reading

• Claude Code hooks
• Claude Code docs
• Claude Code skills

Run one hook review this week

Pick one risky boundary in your repo and turn the policy row into a warning-only Claude Code hook before your next team session. If you want a guided rollout, our hands-on training covers Claude Code workflow conventions for teams.