Claude Code Hook Conventions

Claude Code hooks are safest when your team treats them as repository conventions, not personal shell tricks. Start with the official hook reference, then decide which events your repo may use, who owns each command, and what reviewers must check.

Claude Code, Anthropic's coding agent, gives teams several convention surfaces: CLAUDE.md for shared memory, hooks for deterministic workflow steps, MCP for integrations, and permissions for tool boundaries. A good Claude Code workshop should connect those pieces, because the hard part is not installing a hook; it is keeping the hook understandable six months later.

As of June 25, 2026, the official changelog entry for Claude Code 2.1.193 sits in the MCP and integrations area. The practical takeaway for Claude Code teams is simple: when integrations change, write down the team rule that decides what may connect, what may run, and what must be reviewed.

Start from the official hook surface

Use the official Claude Code hooks reference as the source of truth for hook types, event payloads, and supported behavior. A Claude Code hook is a configured command that runs at a defined lifecycle event, giving your team deterministic checks around an otherwise conversational workflow.

That definition matters. Hooks are not prompts. They do not rely on Claude remembering a preference from chat history. They are repo policy in motion.

A typical example is a pre-tool hook that blocks edits to generated files, or a post-tool hook that runs a formatter after file changes. That is useful in a real repo where humans and Claude Code both touch files, and where a small mistake can create noisy diffs.

The trap is copying an old hook snippet from chat or a wiki and assuming the event names still match. Treat the Anthropic Claude Code hooks documentation as the live reference, especially when someone asks for a claude code hooks events list 2026 or a new hook type.

Put the team rule in CLAUDE.md

Put the human-readable convention in CLAUDE.md before you add the shell command. CLAUDE.md is always-on repository context for Claude Code, so it should explain the intent behind hooks, not just the mechanics.

A useful pattern is to keep the root CLAUDE.md short and durable. Put broad rules there: generated files are not edited by hand, migrations require review, production data access needs approval. Then use nested CLAUDE.md files for local conventions, such as frontend package rules or backend migration rules.

For example, a monorepo might have this in the root file:

## Claude Code workflow

- Prefer small diffs that a human can review in one sitting.
- Do not edit generated files directly. Change the source and regenerate.
- Before adding or changing a hook, update docs/claude/hooks.md and request review from Developer Experience.
- MCP servers may read project context by default, but write actions require an explicit permission rule.

This gives Claude Code the why before the how. It also gives reviewers a plain place to point when a hook feels too broad.

The trap is stuffing CLAUDE.md with task-specific instructions. If a rule only matters for today’s migration, keep it in the prompt or the pull request. CLAUDE.md is for durable team memory, not every clever thought you had while debugging.

For broader patterns, keep this close to your team training material and link it from the related training topic.

Connect hooks, MCP, and permissions deliberately

Hooks and MCP solve different problems, but they meet in the same workflow. Hooks run local commands at known moments. MCP connects Claude Code to external systems such as issue trackers, repositories, databases, document stores, or internal services.

That means a hook convention should say when a local check is enough and when an integration needs a permission boundary. A formatter hook is usually local and low-risk. A hook that calls an MCP-backed deployment system is a very different animal.

Use the same review instinct you use for production code. Ask what the command can read, what it can write, whether it calls the network, whether it handles secrets, and what happens when it fails.

The trap is treating MCP access as a convenience toggle. A helpful integration can still leak context, mutate state, or make a review impossible to reconstruct. If your team is still designing its MCP baseline, pair this guide with MCP Setup for Claude Teams.

Paste this hook policy into your repo

Use this as a starting convention. Put it in docs/claude/hooks.md, then summarize the durable parts in CLAUDE.md.

# Claude Code hook policy

| Hook area | Allowed use | Requires review from | Must not do | Failure behavior |
|---|---|---|---|---|
| Formatting | Run local formatters after file edits | Code owner for the package | Rewrite unrelated files | Fail closed only when formatter exits non-zero |
| Generated files | Block direct edits to generated outputs | Owning team for the generator | Guess the source file to edit | Explain the source path to change |
| Tests and checks | Run narrow checks for touched packages | Package owner | Run the full monorepo suite on every edit | Warn first; block only for required checks |
| Secrets | Detect obvious secret patterns before commits or file writes | Security or platform owner | Print secret values into logs | Block and show the matching rule name only |
| MCP-backed actions | Call approved MCP tools for read-only context | Developer Experience and system owner | Perform writes, deploys, or ticket updates without explicit permission | Block by default and link to the permission rule |
| Slash commands | Wrap repeatable team workflows such as /review-branch | Developer Experience | Hide broad file edits behind a friendly name | Show the command, scope, and expected outputs |

## Adoption path

1. Any engineer may propose a hook by opening a pull request against docs/claude/hooks.md.
2. The pull request must include the hook command, event, owner, expected inputs, expected outputs, and failure behavior.
3. Developer Experience reviews hook shape. The code owner reviews repo impact. Security reviews hooks that read secrets, call networks, or touch MCP-backed systems.
4. After approval, add the durable rule to CLAUDE.md and the executable configuration to the repo-managed Claude Code settings.

## Pull request review rule

A Claude Code hook change is not approved until the reviewer can answer three questions: what event runs it, what data can it read or write, and how a developer recovers when it blocks useful work.

The policy is intentionally boring. Boring is good here. Your future teammate should be able to read a hook diff, understand the blast radius, and decide whether the automation is helping or hiding risk.

The trap is approving hooks because they worked once on one laptop. Hooks become team infrastructure. Give them owners, failure behavior, and a removal path.

Make adoption boring on purpose

Roll out Claude Code hooks the same way you would roll out a lint rule. Start in warning mode where possible, collect the false positives, then decide what deserves to block work.

One practical sequence works well: document the rule in CLAUDE.md, add the hook in one package, ask two engineers to try it during normal work, then promote it to the repo root. If it needs an MCP server, review the permissions before the hook lands.

Use pull requests as the forcing function. A hook should be visible in code review, named in a changelog entry for the repo, and covered by a short review checklist. That is what turns Claude Code conventions from tribal knowledge into something a new teammate can follow.

The trap is centralizing everything too early. A root hook that touches every package feels tidy, but it can punish teams with different build systems. Prefer scoped conventions first, then promote the ones that prove useful.

Common questions

• Where is the official Claude Code hooks documentation?

  Use the official Claude Code hooks page for supported events, configuration shape, and the current claude code hooks reference. Treat blog posts, copied snippets, and old workshop notes as examples only. The citable rule is simple: if the event name or payload matters, verify it against the official reference before shipping the hook.

• Is there a Claude Code hooks events list for 2026?

  The safest Claude Code hooks events list 2026 is the official hooks reference, not a static copied table. Hook events can be product-specific and time-bound, so teams should link to the reference from docs/claude/hooks.md. In review, require the pull request to name the hook event and explain why that event is the right boundary.

• Should hook policy live in CLAUDE.md or a separate file?

  Put the durable rule in CLAUDE.md and the detailed policy in a separate repo file such as docs/claude/hooks.md. CLAUDE.md should stay short enough for Claude Code and humans to use every day. The longer file can hold tables, owners, adoption steps, examples, and recovery instructions.

• When should an MCP integration require extra review?

  Require extra review when an MCP-backed workflow can write to an external system, access sensitive data, call the network, or affect production operations. Read-only context is still worth documenting, but write actions need clearer permission rules. The artifact to ask for is a permission note plus a hook policy row that names the owner.

• Can hooks replace human code review?

  No. Hooks can make review easier by catching predictable issues, but they cannot judge architecture, product intent, or maintainability. A good team rule is to let hooks block mechanical risks and let reviewers decide design questions. If a hook hides too much behavior, make it noisier or split it into smaller checks.

Further reading

• Claude Code — getting started
• Claude Code — skills
• Claude Code — hooks
• Claude Code — permissions
• Model Context Protocol — specification
• Anthropic — Claude Code product page
• GitHub — anthropics/skills

Make the next hook reviewable

Pick one Claude Code hook your team already uses, then add the policy row, owner, failure behavior, and CLAUDE.md summary this week. If nobody can explain what the hook reads, writes, and blocks, it is not ready to be a team convention.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.