Claude Code 2.1.128 team conventions
Team conventions are the small written rules that let a team running Claude Code 2.1.128 settle disagreements by checking a file instead of arguing from memory. The four that matter most are a red-folder approval list, data-class tags on your connectors, a weekly retro note, and a skill index. Each one turns a recurring debate into a lookup.
We learned this the slow way. During a rollback rehearsal, two skills claimed the same diff, and nobody could say which one was supposed to win. The merge sat there while the room argued precedence from memory. The skills worked fine. The problem was that the rule for choosing between them lived in people's heads, not in the repo.
Stop arguing skill precedence
Skill precedence is the written order that decides which skill governs when two of them touch the same change. When that order is written down, the question takes ten seconds. When it isn't, it takes a meeting.
The fix is a skill index: a skills/README.md that lists every skill, its activation cues, and what it defers to. An on-call engineer can resolve a mismatch by reading one file instead of replaying a session.
Put the precedence rules somewhere they govern everything else too. A short CLAUDE.md fragment does that well:
# CLAUDE.md precedence 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 point is not these exact lines. The point is that the next person who disagrees can point at the file.
Add friction where approvals get risky
Approvals drift toward autopilot. People optimize for flow, so after the tenth "yes" a risky bash command slips through on reflex. Guardrails only help when they add friction in the right spot.
A red-folder ritual is that spot. You list the paths that always need a separate reviewer and never get auto-approved: auth, migrations, billing, secrets, whatever your repo treats as load-bearing. Sensitive edits get deliberate eyes again, and the list lives in CLAUDE.md so the rule is visible before anyone hits approve.
Do this before you add the next connector, not after the first scare.
Tag connectors so security reviews are a read
MCP data surprises happen when a connector quietly pulls customer data and the team only notices during an audit. Context feels local while the data has already left the laptop.
Data-class tags fix this. Each connector carries its data classes and its retention expectations, written down where reviewers can see them. The security review becomes a read of an existing inventory instead of a discovery exercise during an incident. The surprise is the thing you are engineering away.
Keep a weekly retro note so memory survives
Sessions rotate daily, and shared memory erodes with them. A decision an agent relied on last Tuesday is gone by Friday unless someone wrote it down outside the transcript.
A weekly retro note is a single .md changelog of the decisions agents leaned on that week. New teammates inherit the reasoning instead of the rumor. A /retro slash command in .claude/commands keeps the habit from slipping.
Here is the reviewer handoff we use on any agent-assisted change:
- MCP connectors used (if any) list their owners.
- Verification command output is pasted or linked.
- Forked agent work names parent and child responsibilities.
- Red-folder paths got explicit human acknowledgement.
If your repo cannot state its boundaries plainly, agents will guess, and guessing scales badly.
Where to start
Pick the convention tied to your last painful moment, and write the smallest version of it today. If you want the rest of the pattern, the team conventions cluster applies the same bar release by release.