Claude Code 2.1.142 team conventions

If two agent streams edit the same module and only one merge can win, the rules you need are four: a skill index, a hook budget, a CLAUDE TOC, and a red-folder ritual for approvals. Team conventions are the repo-owned rules that keep parallel agent streams explainable after the merge. Claude Code, Anthropic's coding agent, will follow whatever your repo states plainly, so the work is making the rules legible, not adding more of them.

The trap is believing green CI proves a healthy team. It does not. The expensive bug in parallel work is duplicated edits nobody reconciled, and a passing test suite hides that until a reviewer has to replay the whole session to figure out who meant what.

Set up a skill index so reviewers know what governed a diff

Skills multiply fast, and once you have a dozen, a reviewer staring at a diff cannot tell which one shaped it. Discovery beats documentation unless you make precedence explicit.

Fix it with one file. Keep a skills/README.md that lists every skill, its activation cues, and what it defers to. When an on-call engineer hits a mismatch, they read the index instead of replaying a session to reconstruct intent.

The index is also where you settle conflicts. If two skills could fire on the same folder, the README says which one wins, and that answer survives long after the conversation that created it is gone.

Give hooks a budget so people stop ignoring them

Hooks that fire on everything teach developers to tune them out. Noise drowns the one alert that mattered, and your safety automation quietly stops working because nobody reads it anymore.

Cap the active hooks per repo and write down each trigger plus its rollback path. A hook you cannot undo is a hook you will eventually disable in a panic, so the rollback is not optional. With a budget in place, the alerts that remain feel urgent again instead of fading into the background.

Here is a small supremacy fragment you can paste at the top of a CLAUDE.md to encode the precedence:

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

Keep CLAUDE.md short with a table of contents

An encyclopedic CLAUDE.md trains newcomers to skim and trust the chat instead. A file nobody reads behaves exactly like a file that does not exist.

Treat the top of the file as the contract. Keep the first 15 lines as the rules that win, then link out to deeper fragments for anyone who needs detail. Sessions then boot with the same assumptions, and aligned assumptions are the part a reviewer can actually check.

This is the difference between a doc and a wall. The TOC version gets read because there is little to read, and the rules that matter sit where the agent looks first.

Run a red-folder ritual for approvals that matter

Reflexive approvals are how risky bash slips through. When every prompt gets a quick yes, the dangerous one rides along with the harmless ones.

List the paths that require a separate reviewer and agree they never auto-approve. Migrations, secrets, deploy scripts, billing code: name them, and route any edit there to a human who has to think before clicking. Sensitive changes get deliberate eyes again, which is the whole point.

Before a parallel-stream PR merges, this short strip catches the common collisions:

• Red-folder paths got an explicit human yes, not a reflex.
• Scopes in the PR body match the folders in the diff.
• Commands that prove the regression guards are listed.
• Any MCP connectors named in the PR list an owner.

If your repo cannot state its boundaries plainly, agents will guess, and guessing does not scale across streams.

Common questions

• What do Claude Code 2.1.142 team conventions focus on?

  They focus on four fixes: a skill index in skills/README.md, a hook budget that caps active hooks per repo, a CLAUDE TOC, and a red-folder ritual for approvals. The shared goal is explainable delegation. Green CI alone does not prove a team can explain its own merges, so each convention makes intent visible after the fact.

• What is a hook budget?

  A hook budget caps the number of active hooks per repo and documents each trigger plus its rollback. It fixes hook thunder, where hooks fire everywhere and developers learn to ignore them. Once you cap them and write down how to undo each one, the remaining alerts regain urgency instead of fading into wallpaper.

• How do you keep parallel agent streams from colliding?

  Reconcile duplicated edits before they ship. The expensive bug in parallel streams is two agents racing into the same module with edits nobody merged on purpose. The review strip in this article makes that visible by requiring the PR scopes to match the folders that actually changed in the diff.

• What is a skill index in Claude Code?

  A skill index is a skills/README.md that lists each skill's activation cues and what it defers to. It fixes skill drift, where skills pile up and a reviewer cannot tell which one governed a diff. With the index in place, an on-call engineer resolves a mismatch by reading one file instead of replaying a whole session.

• Where should a team start?

  Start with the CLAUDE TOC, because it is the cheapest and unblocks the rest. Trim the file to a 15-line contract that wins, then add the skill index, then the hook budget, then the red-folder list. Each one is a small artifact you can paste and refine, not a rewrite of how your team works.

Where to go from here

Pick the one convention your last messy merge would have caught, and write it down today. The full cluster lives on Claude Code team conventions, and a hands-on session is on the training page.