Claude Code 2.1.132 team conventions

A Claude Code team convention is a rule you write into the repo so a reviewer can tell which file, skill, or hook governed a change. Claude Code, Anthropic's coding agent, moves fast enough that the thing breaking first is not model quality, it is the story a reviewer can read after the fact. The four conventions below all do one job: they move a habit out of chat and into a file someone can audit.

You feel the gap most when a pull request stalls because CLAUDE.md says one thing and a skill that just activated says another. The diff is fine. Nobody can tell which rule won. Write the contract before the session boots and that argument never starts.

Set up a skill index so reviewers know which skill won

When skills pile up, no one can tell which one shaped a given diff. That is skill drift, and it gets worse as you add skills because discovery beats documentation unless you make precedence explicit.

The fix is a skills/README.md that lists each skill's activation cues and what it defers to. With that file, an on-call engineer resolves a mismatch by reading one page instead of replaying a whole session. This is the cheapest convention to adopt and it ends most precedence arguments on its own, so start here.

Put a budget on hooks so the alerts still mean something

Hooks that fire everywhere train people to ignore them. Once a developer learns to scroll past a hook, the safety automation you built has quietly stopped working.

Cap the active hooks per repo and write down each trigger plus its rollback path. A smaller set of hooks keeps its urgency, and the rollback note means a teammate can undo one without paging you. Treat the cap as protection for signal, not a limit on ambition.

Keep CLAUDE.md short with a table of contents

When CLAUDE.md grows encyclopedic, newcomers skim it and trust the chat instead. An unread file behaves like a missing one.

Keep the top 15 lines as your supremacy block: the short rules that win when guidance conflicts. Link everything deeper from there. Sessions then boot with the same assumptions, and a reviewer can verify the part that actually matters because it fits on one screen. Here is the supremacy block that holds all four conventions together:

# CLAUDE.md supremacy fragment

- Hooks win over informal chat agreements; document each hook's rollback path.
- Skills defer to this file on security-sensitive folders.
- Bash approvals never bypass the red-folder list maintained here.

Add a red-folder ritual for approvals that should never be reflexive

When approvals become reflexive, a risky bash command slips through because the human was optimizing for flow. People do that. The guardrail has to add friction on purpose.

List the paths that require a separate reviewer and never auto-approve them. A small slash command in .claude/commands that prints the red-folder list keeps the ritual one keystroke away, so sensitive edits get deliberate eyes again. The Claude Code 2.1.129 note walks these same fixes against an earlier release if you want to see how they hold up across versions.

Before a merge, a reviewer should be able to answer four questions from the PR alone:

And a quick strip to run down before you hit merge:

• Primary-doc links were smoke-checked after publishing edits.
• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.
• Forked agent work lists parent and child responsibilities.

None of this replaces architecture judgement. Agents accelerate execution, not ownership.

Common questions

• What do Claude Code 2.1.132 team conventions cover?

  They cover four named fixes: a skill index in skills/README.md, a hook budget with documented rollbacks, a CLAUDE TOC that keeps the top 15 lines as supremacy, and a red-folder ritual for approvals. Each one replaces a habit that used to live in chat with a rule a reviewer can audit straight from the pull request.

• How do reviewers tell which skill governed a diff?

  A skill index answers that: a skills/README.md listing every skill's activation cues and what it defers to. Skill drift keeps coming back because discovery beats documentation unless precedence is written down. With the index, an on-call engineer resolves a mismatch by reading one page, not by replaying a whole session.

• Why do Claude Code hooks need a budget?

  Because hooks that fire everywhere train developers to ignore them. A hook budget caps the active hooks per repo and documents each trigger plus its rollback path, so the alerts that remain keep their urgency. The cap protects the signal that makes safety automation worth having in the first place.

• What belongs in CLAUDE.md versus a skill?

  CLAUDE.md holds supremacy: the short rules that win when guidance conflicts, like hooks beating chat agreements and skills deferring on security-sensitive folders. Skills hold the task-specific depth. The CLAUDE TOC keeps the top 15 lines as that contract and links everything deeper, so the file stays readable.

Where to start

Adopt the skill index first, since it is one README and it ends most precedence arguments by itself. If you want these four fixes drilled against your own repos with receipts enforced, our training runs them live, so bring one real repo and one skeptical reviewer.

Further reading

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