Claude Code hooks for teams

A Claude Code hook is a deterministic check that fires at a lifecycle point and runs as a shell command, an HTTP endpoint, or a prompt. For a team, the move is to sort every hook into one of four buckets, protect, observe, enrich, or block, and then review the setup like you review production code. Claude Code, Anthropic's coding agent, gives you the building blocks. The hard part is agreeing on how to use them.

Most teams do not lose time because the model is weak. They lose time because each repo quietly grows its own rules for context, review, and permissions. A convention that lives in one person's head is not a convention. This piece is about writing those rules down so a teammate can read them and trust the repo in five minutes.

Sort every hook into protect, observe, enrich, or block

When several people add hooks to the same repo, the config gets busy without getting safer. One person adds a pre-tool check, another adds a post-tool formatter, a third tucks an approval prompt into a shell script. Nobody can say at a glance what changes behavior and what only watches.

The fix is a four-bucket map. Read the hooks docs for the exact event names, then label each hook with one word:

• Protect: enforces a permission or policy. It can stop or change what the agent does.
• Observe: logs or notifies. It records, it never blocks.
• Enrich: adds context for Claude before a step runs.
• Block: halts unsafe work outright.

Name the bucket in the file or a config comment. Now a reviewer knows whether a hook is a guardrail or a camera before reading a single line of script. That alone cuts the "wait, what does this one do?" tax that slows every review.

Split memory between CLAUDE.md and skills

CLAUDE.md is the file Claude Code reads on every session, so it is tempting to dump everything there. Teams do, and it turns into a junk drawer of process notes that nobody trusts.

Keep durable repo facts in CLAUDE.md: what the project is, how it is laid out, the rules that are always true. Move repeatable procedures, checklists, and multi-step workflows into skills, which load only when they are needed. A skill lives in its own SKILL.md and stays out of the way until the task calls for it.

A simple test: if a paragraph in CLAUDE.md starts reading like a runbook, it belongs in a skill. The payoff is quieter sessions and conventions that are easier to review one piece at a time.

Scope MCP connectors before you connect them

MCP connects Claude Code to outside systems, and every connector widens what a reviewer has to think about. The permissions docs and the MCP specification point to the same habit: scope first, then connect.

Before a new MCP server lands, write a short connector note that answers three questions. What can it read? What can it write? What happens if it fails? Keep that note next to the config, not buried in a chat thread.

This changes the review conversation. Instead of asking whether the agent "seems safe," a reviewer asks whether the connector is least privilege and whether the team can describe the blast radius if it misbehaves. No connector without a note.

Put every hook in one table

The last common miss is review blindness. A Claude-authored pull request has a tidy diff, so the team approves it, and only later realizes the real question was the process that produced it, not the diff itself.

Make the process visible. Keep one table that lists every hook with its event, bucket, purpose, owner, failure mode, and the check a reviewer should run. Paste this starter next to your repo config and edit it to match:

| Event             | Bucket  | Purpose                     | Owner         | Failure mode     | Reviewer check                    |
| ----------------- | ------- | --------------------------- | ------------- | ---------------- | --------------------------------- |
| SessionStart      | enrich  | Load repo context           | Platform team | stale context    | Does it match current CLAUDE.md?  |
| PreToolUse        | protect | Block risky tools           | Security      | false blocks     | Is the allowlist narrow?          |
| PostToolUse       | observe | Log tool use                | Infra         | noisy logs       | Can we trace the action?          |
| PermissionRequest | block   | Require approval for writes | Repo owner    | approval fatigue | Is the connector scope documented?|

Pair it with a short CLAUDE.md so the defaults are written down, not assumed:

# CLAUDE.md

- Use skills for repeatable procedures.
- Use hooks for deterministic checks and policy.
- Keep MCP connectors least privilege.
- Review Claude-authored changes for evidence, not just clean diffs.

That is enough to start. The goal is to make the team's default behavior something a newcomer can read, not guess.

Know what hooks are bad at

Hooks are great for deterministic checks, permission boundaries, and audit trails. They are bad for judgment. If you try to encode taste or design decisions into a hook, you will slow everyone down and still get it wrong, so leave those to people and reviews.

The same honesty applies to the rest of the stack. CLAUDE.md can still bloat, and an MCP connector can still be over-scoped. The guardrail is review discipline, not faith that the tool will protect you. A picture that helps: CLAUDE.md is the bench label, skills are the drawers, hooks are the stops, and MCP is the cable that leaves the room.

Common questions

• What are Claude Code hooks best used for?

  Claude Code hooks are best for deterministic checks, permission boundaries, and audit trails, not for creative judgment. They fire at lifecycle points such as SessionStart, PreToolUse, PostToolUse, and PermissionRequest. Each one can run a shell command, an HTTP endpoint, or a prompt, which is why agreeing on the bucket matters more than the exact syntax.

• How do teams stop hook sprawl?

  Use the four-bucket map: put every hook into protect, observe, enrich, or block, and name the bucket in the file or a config comment. A reviewer can then tell whether a hook changes behavior or only records it. That one label removes most of the guesswork when someone new opens the repo and tries to trust it.

• What goes in a hook policy table?

  A hook policy table lists every hook with its event, bucket, purpose, owner, failure mode, and reviewer check. It becomes the first thing a teammate reads before trusting the repo. The starter version in this article covers SessionStart context loading, PreToolUse blocking, PostToolUse logging, and PermissionRequest approvals, so you can edit rather than invent.

• Should process rules live in CLAUDE.md or in a skill?

  Keep durable repo facts in CLAUDE.md and move procedures, checklists, and multi-step workflows into a SKILL.md. The quick test: if a paragraph reads like a runbook, it belongs in a skill that loads only when needed. This keeps the always-on context short and makes each convention easy to review on its own.

Where to take this next

Write down your four-bucket map and hook table today, then check whether a new reviewer can defend a Claude-authored merge without replaying the chat. For a deeper team workflow, see Claude Code team conventions.