Claude Code hooks and team conventions

The Claude Code hooks documentation gives you the event surface, SessionStart, PreToolUse, PermissionRequest, PostToolUse, and Stop; the team convention decides which of those events the repo actually uses. Claude Code team conventions are repo rules that keep context, hooks, and permissions explicit and reviewable. Teams usually do not fail on the model. They fail on the handoff: one person trusts a hook, another cannot tell what it blocks, and review turns into archaeology. If you are shipping with Claude Code, the real question is whether the team can still explain the rules after the first week.

The situation

Counter-thesis: more automation does not mean less process; it means the process has to move into the repo.

The wrong path: we believed a shared prompt was enough. We tried one long CLAUDE.md, a few loose instructions in chat, and a couple of ad hoc checks. What happened on teams on the floor was familiar: context drift, surprise tool calls, and reviews that could not tell policy from preference.

Diagnosis: this is the old implicit-knowledge trap. If a rule matters, it needs a home.

Thesis: Claude Code team conventions work when context, hooks, and permissions are explicit, local, and reviewable.

That is why the official docs matter more than folklore. Claude Code separates always-on memory, on-demand skills, deterministic hooks, and connector permissions for a reason.

What changes when the rules live in the repo

Scoped Memory — if you have shipped AI code, you have hit the moment where CLAUDE.md becomes a junk drawer. The fix is to keep global rules short and move task rules into the nearest project file or nested memory file. When teams do this, Claude stops dragging old instructions into new work, and reviewers can see which rule applied where. If it reads like a procedure, it is probably not memory. The thesis holds because the thesis holds: explicit context beats inherited guesswork.

Hook Boundary Policy — if you have shipped AI code, you have also hit the “it ran, but what did it do?” problem. Hooks are deterministic infrastructure outside the loop. Use them for lifecycle checks, permission gates, formatting, logging, and validation, and keep the event list small enough that the team can name it. The official hooks reference shows a broad event surface, including SessionStart, PreToolUse, PermissionRequest, PostToolUse, and Stop. That breadth is useful only if the team writes down which events it actually uses. A hook should answer one question, not three. This is the thesis in practice: explicit boundaries beat hidden behavior.

Least-Privilege Connector Review — if you have shipped AI code, you have seen a connector that was useful in demo and risky in production. Treat .mcp.json like an integration boundary, not a convenience file. Review what the server can reach, what data it can read, and whether the team can explain the blast radius in one sentence. The docs on permissions and MCP make the same point from different sides: access and sandboxing interact, so approval is not a formality. The thesis survives because the thesis survives: explicit scope beats broad trust.

Skill, Not Snippet — if you have shipped AI code, you know the pattern: someone pastes a checklist into chat, then pastes it again next week. Move repeatable procedures into a SKILL.md file with a clear description and supporting files. Claude Code skills are on-demand, which means they cost little until used and can be invoked directly when needed. Teams stop retyping the same review steps and start versioning them. The thesis stays intact when repeatable work becomes a named artifact.

Review Gate Checklist — if you have shipped AI code, you know the review comment that says “looks fine” and means “I did not know what to check.” Require a short checklist for Claude-authored changes that names the memory file, the hook, the connector, and the test or verification step. This is where our methodology matters in practice: in review, the team should verify the artifact, not the intent. The thesis becomes visible when review can point to the rule, not the vibe.

A hook policy you can paste

# 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 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 + repo owner | Can we explain the data path? |
| Skills | Package repeatable procedures as SKILL.md | Team lead | Does this replace pasted instructions? |
| Reviews | Require a Claude-authored change checklist | Reviewer | Can I see the artifact and test? |

Use that table as a starter, not a law. The point is to make the team’s actual habit visible before it becomes tribal memory.

Tradeoffs and limits

The cleanest setup is not the most locked-down one. Too many hooks can slow the loop, and too many scoped files can make discovery harder than the old monolith. Keep the thesis in view: Claude Code team conventions should reduce surprise, not add ceremony.

There is also a limit to what docs can solve. If the team will not review permissions, no amount of naming will save the workflow. If the team will not own the repo rules, no hook policy will stay current.

One image: think of the repo as the workshop wall. If the rule is not pinned there, it is already fading from memory.

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.

Practical starter checklist

• Name the Claude Code artifact first: a CLAUDE.md fragment, a Claude skill outline, a hook boundary, an MCP permission note, or a review checklist.
• Write the review checklist before generation starts: scope, owner, tests, rollback.
• Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Failure modes to watch

• Named fix: Scope Receipt. Keep one short note that names the Claude Code artifact, the owner, and the files the agent may touch.
• Named fix: Review Gate. Require the reviewer to see the changed rule, checklist, or verification output before approving the work.
• Named fix: Rollback Note. Add the fastest safe undo path next to the change so the team can recover without reconstructing the session.

Synthesis

Synthesis: Treat the agent as a fast implementer behind a receipt gate: it can move quickly only when scope, checks, and ownership are visible.

Best ways to use this research

• Best for: Claude Code teams deciding which CLAUDE.md convention, hook, skill, or MCP boundary to standardize next around “Claude Code hooks and team conventions.”
• Best first artifact: turn the named fix into a CLAUDE.md convention, hook checklist, skill note, or review receipt before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Common questions

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

  The Claude Code hooks documentation describes a broad event surface, including SessionStart, PreToolUse, PermissionRequest, PostToolUse, and Stop. That breadth is useful only if the team writes down which events it actually uses in this repo, with each hook answering one question, not three.

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

  If a rule matters, it needs a home in the repo: keep global rules short in CLAUDE.md, move task rules into the nearest scoped file, and put repeatable procedures in a SKILL.md. Claude then stops dragging old instructions into new work, and reviewers can 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 the team can explain the blast radius in one sentence. Access and sandboxing interact, so connector approval is not a formality.

• Do more hooks make a Claude Code setup safer?

  No, the cleanest setup is not the most locked-down one: too many hooks slow the loop, and too many scoped files make discovery harder than the old monolith. Conventions should reduce surprise, not add ceremony, and a hook should answer one question.

Further reading

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

What to do next

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.