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 will follow whatever your repo states plainly, so the work is making the rules legible, not adding more of them.
Watch for 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.
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.