Claude Code 2.1.129 team conventions

If your Claude Code review threads have turned into dig sites where you scroll, guess who approved what, then merge on faith, the fix is four small files, not a new tool. Team conventions are the written agreements a team keeps in the repo so a reviewer can judge a merge without replaying the chat session. Claude Code, Anthropic's coding agent, gives every teammate the same power, so the question stops being "what can the agent do" and becomes "can the next person read what it did."

Green CI and an explainable merge are different things. A test suite proves the code runs. It does not tell a reviewer what scope you set, which skill governed the diff, or who signed off on the risky path. That second story lives in chat unless you write it down, and chat is exactly what a reviewer cannot replay six weeks later.

Write the conventions a reviewer can open

Each convention here turns one chat habit into a file someone can read cold. Four problems show up on busy Claude Code teams, and each has a cheap fix.

Skills tend to multiply until nobody can tell which one shaped a given diff. Keep a skills/README.md that lists each skill, its activation cue, and what it defers to. An on-call engineer then resolves a mismatch by opening one file.

Hooks that fire on everything stop getting read, the way an alert that pages you hourly becomes wallpaper. Cap the active hooks per repo and write down each trigger plus its rollback path. Fewer, louder hooks beat a wall of noise.

An encyclopedic CLAUDE.md gets skimmed, and a skimmed file behaves like an absent one. Keep the top 15 lines as the part that wins conflicts, then link to deeper fragments below. Every session then boots with the same assumptions.

Reflexive approvals are how risky bash slips through, because people optimize for flow and permissions need friction on purpose. List the paths that always need a second reviewer and never auto-approve them.

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

The handoff has to survive without the original operator in the room. That is the whole test. The rest of the team conventions cluster works the same way, and the Claude Code 2.1.123 note applies it to an auth-fix release.

Make the merge carry its own evidence

A merge is easy to defend when four questions answer cleanly from the repo alone.

Paste this checklist into your PR template and watch which boxes nobody can tick yet.

• Verification command output is pasted or linked.
• Forked agent work names the parent and child responsibilities.
• Red-folder paths got an explicit human acknowledgement.
• Scopes in the PR body match the folders in the diff.

None of this replaces architecture judgement. The agent speeds up execution. You still own the call.

Roll it out without a big meeting

Start with the checklist, because it costs nothing and exposes the gaps fastest. Add a slash command in .claude/commands that drops the checklist straight into the PR body, so the ritual stays cheap and nobody has to remember it.

This is built for Claude Code teams whose review threads read like archaeology and who want the 2.1.129 conventions in place before the next release. If you want a sharper read, put one receipts-enforced merge next to one vibes-enforced merge and time how long each takes to defend.

Common questions

• What do Claude Code 2.1.129 team conventions include?

  They include four fixes: a skill index that records activation cues and deferrals, a hook budget with documented rollbacks, a CLAUDE TOC that keeps the top 15 lines as the part that wins conflicts, and a red-folder list of paths that never auto-approve. Together they let a reviewer judge a merge without replaying the session.

• How do you stop review threads from becoming archaeology?

  Record the scope, verification output, and approval trail in the repo before review starts. A reviewer cannot reconstruct what the repo never captured, so the checklist asks for pasted verification output, named responsibilities on forked work, and red-folder acknowledgements. The archaeology ends when receipts arrive alongside the diff.

• What is the red-folder ritual?

  It is a list of repository paths that need a separate reviewer and are never auto-approved. It exists because approvals turn reflexive under flow, and risky bash slips through reflexes. Once the list lives in CLAUDE.md, sensitive edits get deliberate eyes again, and shame stops being the only thing enforcing care.

• Why keep CLAUDE.md to 15 supremacy lines?

  Because an unread file behaves like an absent one. A long CLAUDE.md gets skimmed, and newcomers fall back to chat for the real rules. The CLAUDE TOC keeps the top 15 lines as the contract that wins conflicts and links deeper fragments below, so every session starts from the same assumptions.

• Do these conventions slow the team down?

  A little, on purpose, and only where it pays off. The friction lands on risky paths and on writing down scope, which is exactly the work that saves hours during review later. Routine merges stay fast because the checklist is mostly pre-filled by a slash command, and the gates only bite when something genuinely needs a second look.

Start here

Pick the evidence checklist and paste it into your PR template before the next release retro. If your team wants the deeper version, the training walks through the same conventions on a real repo.