Claude Code 2.1.126 team conventions

The shortest version of team conventions for Claude Code 2.1.126: write the contract down so a reviewer can check it before merge, not after the incident. Claude Code, Anthropic's coding agent, will follow whatever rules your repo states plainly, so the work is making those rules plain. A team convention is just a habit that someone wrote into a file with an owner attached. Four of those habits do most of the work, and you can adopt them one at a time.

We landed here the boring way. A rollback rehearsal turned up a diff that bundled a refactor with a quiet intent change, and behind it an MCP connector demo that nobody owned. The fix was not a smarter prompt. It was a file that said who answered for that connector.

Give every connector a steward

A connector steward is the named person who answers for an MCP server's scopes, the data classes it touches, and its rollback path. Demos do not need one. Anything that touches production data does.

The trap with a connector built on the Model Context Protocol is that the context feels local while the data quietly leaves your laptop. You notice during an audit, which is the worst time to notice.

So tag every connector with the data classes it reads and the retention you expect. Now a security review starts from an inventory instead of an interview, and a reviewer can check the tag against the merge without replaying a chat log.

Write one retro note a week

Daily sessions rotate, and shared memory rotates with them. The reasoning behind a decision ends up trapped in a transcript that the next teammate will never read.

Fix it with one append-only .md file. Each week, add a short note of the decisions the agent relied on and why. New teammates inherit the reasoning instead of the rumor, and you stop re-litigating settled calls.

This is the cheapest convention on the list. One file, a few lines a week, and session amnesia stops costing you the same argument twice.

Keep a skill index so reviewers know what fired

Skills multiply. Past a certain point a reviewer cannot tell which skill governed a given diff, because discovery beats documentation unless precedence is written down somewhere.

Maintain a skills/README.md that lists each skill's activation cues and what it defers to. An on-call engineer can then resolve a mismatch by reading one file, instead of replaying the session that produced the diff.

Pair the index with a clear precedence rule in CLAUDE.md so there is never a question about which contract wins on sensitive folders:

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

Cap your hooks so the alerts still mean something

Hooks that fire everywhere turn into wallpaper, and wallpaper does not gate permissions. An ignored hook is worse than no hook, because it gives false comfort.

Set a budget: a cap on active hooks per repo, with each trigger and its rollback written down. A small slash command in .claude/commands that lists the active hooks and their owners keeps the budget honest and visible.

When the set is small, the alerts that remain keep their urgency. That is the whole point.

The evidence a reviewer should be able to find

Before trusting a merge that touches a connector, a reviewer needs four answers from the repo alone. If they have to ask in chat, the contract is not written down yet.

Here is a scope receipt you can paste into a pull-request template:

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

If your repo cannot state its boundaries plainly, the agent will guess, and guessing scales poorly. The team conventions cluster collects more of these patterns if you want the full set.

Common questions

• What do Claude Code 2.1.126 team conventions require for MCP connectors?

  They require a steward: a written owner plus a permission note a reviewer can check before merge. Connector demos without stewards are exactly how rollback rehearsals find surprises. The data-class tag adds the classes of data each connector touches and the retention you expect, so audits start from an inventory.

• What is a data-class tag?

  It is a short label on an MCP connector recording which classes of data it touches and what retention applies. It exists because context feels local while data leaves the laptop boundary. With tags in place, a security review reads the inventory first instead of learning the basics mid-incident.

• How does a skill index help reviewers?

  It lists every skill's activation cues and deferrals in skills/README.md, so a reviewer can tell which skill governed a diff without replaying the session. Skill drift keeps coming back because discovery beats documentation unless precedence is explicit. The index is where you make precedence explicit and keep it there.

• Why cap hooks per repo?

  Because hooks that fire everywhere train people to ignore them, and an ignored hook gives false comfort. A hook budget caps the active set and documents each trigger plus its rollback path. The alerts that survive the cap keep their urgency, which is the only reason to have a hook at all.

• Where should these conventions live?

  In files the agent reads and a reviewer can open: CLAUDE.md for precedence, skills/README.md for the skill index, a connector list with owners, and one append-only retro note. Chat is fine for working things out. It is a poor place to store a contract anyone needs to check next quarter.

Start with one file

Pick the convention that fixes your loudest pain this week, usually the connector owner column, and write it down before the next audit asks for it. If you want a hand, book a 15-minute sync and we will walk one rollback rehearsal with your leads; a single rehearsal usually settles the stewardship argument.