Claude Code Hooks for Team Conventions
Treat hooks as a team boundary before you treat them as automation. Claude Code hooks are most useful when they turn a risky local habit into a repeatable check, such as blocking a destructive shell command, recording review evidence, or stopping an MCP-backed workflow before it touches production data. In Claude Code training, I teach teams to read the official hooks reference, then write one small convention that says which hook types are allowed, who owns them, and what failure should look like.
The Claude Code hooks documentation answers the reference question: what events exist, what data a hook receives, and where hook configuration belongs. The engineering question is narrower: which of those Claude Code hooks should your team standardize first, and which ones should stay experimental until you have review evidence?
Make hooks enforce small team rules
A hook should guard a decision the team has already made. If the rule is still being debated, a hook will only hide the disagreement behind a script.
Good first hooks are boring. Block rm -rf in the repository, warn before editing generated files, require tests after changing a migration, or capture the command transcript when Claude Code finishes a task. These are ordinary Team conventions, just enforced at the moment the workflow can go wrong.
This sits in the Review step of our methodology: delegate the work, then make the evidence cheap to inspect. A hook does not replace review. It reduces the chance that a reviewer has to reconstruct what happened from chat history.
Rolling this out in your team?
We train engineering teams on their own codebase in two days. Claude Code setup, shared rules and review included.
Choose the hook by the risk
Use the official Claude Code hooks reference for the current event names and payload details. As of October 2026, teams commonly start with tool-use hooks and stop hooks because they sit close to code edits, shell commands, and review evidence.
| Risk you want to control | Hook choice | Team use | Limit |
|---|---|---|---|
| A command may change files, delete data, or call an unsafe tool | PreToolUse |
Block or require confirmation before the action runs | Too many blocks will train people to bypass the hook |
| A tool just changed code or ran a command | PostToolUse |
Log evidence, check changed paths, suggest the next verification step | It is after the fact, so do not use it for hard prevention |
| The agent says the task is done | Stop |
Require a test summary, diff summary, or review note | It can become noisy if every task needs the same receipt |
| A subagent finishes delegated work | SubagentStop |
Collect outputs from parallel work before a human review | Useful only if the team has a real subagent workflow |
| A long session is about to be compacted | PreCompact |
Preserve decisions, files touched, and unresolved questions | It cannot fix missing context that was never written down |
I would not keep a private Claude Code hooks events list for 2026 in a wiki unless someone owns it. Link to the official reference instead, then keep your repo policy focused on the few hook types your team actually uses.
Paste this hook policy table
Put the convention in the repo where engineers will find it. I usually prefer a short docs/claude-hooks.md note or the team engineering handbook, with a pointer from repository memory only if your team already maintains that habit.
| Hook boundary | Event | Default action | Owner | Review evidence | Escape hatch |
|---|---|---|---|---|---|
| Destructive shell commands in the repo | PreToolUse | Block and print the safer command or required approval path | Platform team | Hook output plus PR note when bypassed | Senior engineer approval in the PR |
| Database migration edits | PostToolUse | Require migration test command before completion | Backend team | Test command and result in the review note | Issue link explaining why tests cannot run locally |
| Generated files | PreToolUse | Warn before manual edits to generated paths | Owning feature team | Diff shows source file change or regeneration command | Allowed for emergency patch with follow-up ticket |
| Task completion | Stop | Ask for changed files, verification run, and remaining risk | Tech lead for the repo | Short review receipt in the PR or handoff note | Skip only for read-only investigation |
| MCP tools with write access | PreToolUse | Require explicit task intent and approved server name | MCP server owner | Tool name, target system, and reason for use | Disable server or switch to read-only mode |
A team lead or repo owner should propose the first version. The people who maintain the affected systems should review it, especially when the hook touches shell commands, databases, deployment paths, or MCP tools. Keep the policy beside the hook configuration, and link to it from the repo’s normal contributor docs.
Review the policy whenever a hook blocks legitimate work twice in a week, or when a bypass appears in a pull request. That review rule matters because stale hooks are worse than no hooks. They look like control, but they teach engineers to route around the control.
Keep hooks close to MCP risk
Hooks become more important when Claude Code can reach external systems through MCP. A local formatting mistake is annoying. A write-capable MCP server pointed at issues, documents, or a database needs a clearer boundary.
For example, in a Next.js repo that uses Prisma migrations, I would let a PreToolUse hook stop shell commands that edit migration files directly unless the task includes the migration command the team expects. If the same workflow can call an MCP server with write access to a ticketing system, the hook policy should record the server name, the intended target, and the evidence reviewers should see later.
This is where ownership matters. If no one owns the MCP server, no one can answer whether the hook is too strict or too loose. I covered that boundary separately in Claude Code MCP Server Ownership, and the same rule applies here: the integration owner should also own the failure mode.
Roll out one enforced check
Start with one hook that prevents a real failure, not a suite of clever automations. Pick a workflow where the team already agrees on the rule, add the smallest script that enforces it, and run it in warning mode if the cost of a false positive is high.
Then make the failure message useful. A blocked action should tell the engineer what happened, why the team cares, and what command or review path to use instead. A hook that only says “denied” will slow people down without teaching the convention.
After a week, read the hook output and the pull requests where it appeared. Keep the hook if it prevented a real problem or improved review evidence. Change it if engineers had to bypass it for normal work.
Put one hook under review
Choose one risky Claude Code workflow this week and write the hook boundary before you write the script. Our hands-on training covers Claude Code conventions, hook review, and safe integration rollout.
Further reading
What to do next
Start from Team conventions.
Train your team on Claude Code
Two days on your team's own repository, onsite or remote, with a written proposal before you commit.
Book a callPrefer to measure first? Take the free team check.