Claude Code 2.1.140: team conventions

A team convention is a rule written into the repo that tells a reviewer which skill, hook, or file governed a given change. Once your team runs Claude Code, Anthropic's coding agent, at scale, the thing that slows you down is not the model. It is review bandwidth: a diff lands and nobody can say why the agent did what it did. Around Claude Code 2.1.140 there are four small conventions that fix that, and this piece walks through each one.

The shape of the problem is always the same. A prompt experiment ships as a "temporary" default, becomes policy by accident, and onboarding week is where someone finally asks who owns it. The four fixes below are a skill index, a hook budget, a CLAUDE TOC, and a red-folder ritual. None of them are clever. They just move precedence out of chat and into the repo, where a reviewer can read it.

Write down which skill governs what

When skills multiply, reviewers lose the thread. Two skills can both plausibly fire on the same change, and the only record of which one actually did lives in a session log nobody wants to replay.

The fix is a plain index. Keep a skills/README.md that lists every skill, its activation cue, and what it defers to. Now an on-call engineer resolves a mismatch by reading one file instead of re-running a session. That single page is the cheapest review tool you will add all quarter.

The rule that makes it work: discovery beats documentation unless precedence is explicit. If you do not state the order, the agent will pick one for you, and you will find out in production.

Cap your hooks so the alerts still mean something

Hooks that fire everywhere train people to ignore them. By the third repo where a hook blocks a commit for a reason nobody remembers, developers stop reading the output. The tool is fine. The missing piece is an operating contract.

So set a budget. Pick a cap on active hooks per repo, and for each one document the trigger and the rollback path. When a hook fires, the alert means something again, because there are few enough of them that someone bothered to write down why each exists.

Keep CLAUDE.md short enough to read

An encyclopedic CLAUDE.md is an unread CLAUDE.md, and an unread file behaves exactly like a missing one. Newcomers skim it, trust chat instead, and boot every session with slightly different assumptions.

Treat the top of the file as a table of contents. Keep the first 15 lines as the rules that win, plus links to deeper fragments for anyone who needs detail. Sessions then start from the same baseline, which is the part a reviewer can actually verify against a diff.

Here is the kind of supremacy fragment that belongs at the top:

# 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.

Put deliberate friction on the risky paths

Reflexive approvals are how risky bash slips through. People optimize for flow, so a stream of "yes" clicks eventually approves something it should not have. The answer is not more discipline. It is designed friction in the permissions layer.

Keep a red-folder list: the paths that always need a second reviewer and never auto-approve. Add a slash command in .claude/commands that prints the list, so the ritual stays one keystroke from where you work. Sensitive edits get deliberate eyes again, and the approval leaves a trace a reviewer can follow.

Before an onboarding cohort inherits your defaults, run them through four gates:

And a scope receipt to paste into the PR:

• 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 plus child responsibilities.

None of this replaces architecture judgement. Agents speed up execution. They do not take over ownership.

Common questions

• What is a team convention in Claude Code?

  A team convention is a rule recorded in the repo that tells a reviewer which skill, hook, or file governed a change. In Claude Code 2.1.140 the four conventions worth adopting are a skill index, a hook budget, a CLAUDE TOC, and a red-folder ritual. Each one moves precedence out of chat and into a file a reviewer can read.

• How do reviewers tell which skill governed a diff?

  Through a skill index: a skills/README.md that lists every skill's activation cue and what it defers to, so precedence is explicit. Skill drift recurs because discovery beats documentation when the order is left unstated. With the index, an on-call engineer resolves a mismatch by reading one page instead of replaying a session.

• Why cap hooks with a budget?

  Because hooks that fire everywhere teach people to ignore them, and a blocked commit nobody can explain is worse than no hook at all. Cap the active hooks per repo and document each trigger and its rollback. The alerts then carry signal again, since there are few enough that someone wrote down why each one is there.

• What keeps a CLAUDE.md readable for new teammates?

  A CLAUDE TOC: keep the top 15 lines as the rules that win, plus links to deeper fragments. An encyclopedic file makes newcomers skim and trust chat instead, and an unread file behaves like a missing one. The short top section lets every session boot from the same assumptions a reviewer can check.

Where to start

Adopt the skill index first, since every temporary default it catches is one fewer mystery for the next cohort. The team conventions cluster collects the rest, and the Claude Code 2.1.142 note extends these fixes to parallel agent streams.

Further reading

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