Claude Code hooks and team conventions

Team conventions for Claude Code, Anthropic's coding agent, are repo rules that keep context, hooks, and permissions explicit enough that any reviewer can read them. The model rarely breaks a team. The handoff does: one person trusts a hook, the next cannot tell what it blocks, and review turns into archaeology. The fix is to move the rules out of people's heads and into files you can open in a pull request. If your team can still explain its Claude Code rules after the first busy week, you got this right.

Move the rules into the repo

A shared prompt is not a convention. Chat instructions and one giant CLAUDE.md feel like agreement until two engineers read them differently and ship two different things.

The repo is where rules survive. Claude Code already gives you four homes for them, and each one has a job:

• Always-on memory in CLAUDE.md for facts the agent should never forget.
• On-demand skills in SKILL.md files for procedures you run again and again.
• Deterministic hooks for checks that should fire without anyone asking.
• Connector permissions in .mcp.json for what outside tools may reach.

When a rule lives in one of these, a reviewer can point at it. When it lives in someone's memory, review becomes a guessing game about intent.

Keep CLAUDE.md from becoming a junk drawer

If you have shipped AI code, you have watched CLAUDE.md swell into a wall of half-true instructions. Keep the global file short. It holds facts: the package manager, the test command, the things that are true everywhere.

Push task rules down to the nearest scoped file or a nested memory file in the relevant folder. Claude then stops dragging a rule from one corner of the repo into work where it does not belong, and reviewers can see which rule applied where.

A quick test: if it reads like a procedure with steps, it is probably a skill, not memory. Memory is for what is true. Skills are for what to do.

Write hooks that answer one question

A hook is deterministic code that runs at a fixed point in the agent's loop, outside the model's reasoning. That is the point of it: the behavior is fixed, not negotiated each turn.

The official hooks reference describes a broad event surface, including SessionStart, PreToolUse, PermissionRequest, PostToolUse, and Stop. Breadth is only useful if your team writes down which of those events this repo actually uses.

Keep each hook to one question. A PreToolUse hook that blocks writes outside src/ is easy to defend. A hook that formats, logs, and gates permissions all at once is the thing nobody wants to touch six months later. Use hooks for lifecycle checks, formatting, logging, and permission gates, and keep the list short enough that someone can name every one from memory.

Review .mcp.json like a door, not a config file

Treat .mcp.json as an integration boundary. A connector that looked handy in a demo can read more than you want in production, and the file makes that easy to miss.

Before approving a server, answer three things: what it can reach, what data it can read, and whether you can describe the blast radius in one sentence. The docs on permissions and MCP make the same case from two directions, since access and sandboxing interact and approval is a real decision, not a rubber stamp.

If nobody on the team can explain the data path, that is your answer for now.

A hook policy you can paste

Drop this table into your repo and edit it for your stack. The value is making the team's real habit visible before it hardens into tribal memory.

# Hook policy table for Claude Code teams

| Area     | Default rule                                            | Owner             | Review check                       |
| -------- | ------------------------------------------------------- | ----------------- | ---------------------------------- |
| CLAUDE.md | Keep global rules short; move procedure into scoped files | Repo owner        | Is this a fact or a workflow?      |
| Hooks    | Use only for deterministic checks and boundaries        | Platform team     | Does one event map to one action?  |
| MCP      | Approve least-privilege access only                     | Security + owner  | Can we explain the data path?      |
| Skills   | Package repeatable procedures as SKILL.md               | Team lead         | Does this replace pasted steps?    |
| Reviews  | Require a Claude-authored change checklist              | Reviewer          | Can I see the artifact and test?   |

A word on limits, since the cleanest setup is not the most locked-down one. Too many hooks slow the loop, and too many scoped files can make a rule harder to find than the old monolith. And no convention saves a team that will not review its own permissions. The goal is less surprise, not more ceremony.

Common questions

• What does the Claude Code hooks documentation say about events?

  The hooks documentation describes a broad event surface, including SessionStart, PreToolUse, PermissionRequest, PostToolUse, and Stop. That breadth helps only if your team writes down which events this repo uses, with each hook answering one question. A hook that tries to do three jobs at once is the one nobody will trust later.

• Where should Claude Code rules live so they survive the first week?

  In the repo, split by job. Keep global facts short in CLAUDE.md, move task rules into the nearest scoped or nested memory file, and put repeatable procedures in a SKILL.md. Claude then stops pulling old instructions into unrelated work, and any reviewer can open a pull request and see which rule applied where.

• How should teams review .mcp.json changes?

  Treat .mcp.json as an integration boundary, not a convenience file. Review what the server can reach, what data it can read, and whether someone can describe the blast radius in one sentence. Access and sandboxing interact, so connector approval is a real decision. If nobody can explain the data path, hold the approval.

• Do more hooks make a Claude Code setup safer?

  No. The cleanest setup is rarely the most locked-down one, because too many hooks slow the loop and too many scoped files make rules hard to find. Conventions should cut surprise, not add ceremony. Keep each hook focused on one question and let the rest stay simple.

Where to go next

Take this into the related training topic and test it: hand a fresh reviewer one Claude-authored change and see if they can defend the merge without replaying the chat.

Further reading

• Claude Code docs: getting started
• Claude Code docs: skills
• Claude Code docs: hooks
• Claude Code docs: permissions
• MCP docs: specification
• Claude Code product page
• github.com: anthropics skills