Claude Code 2.1.141 team conventions

Team conventions for Claude Code, Anthropic's coding agent, are the repo files, hooks, and permission lists that record how agent work gets reviewed. The four worth standardizing around the 2.1.141 release are a CLAUDE TOC, red-folder approvals, data-class tags on MCP connectors, and a weekly retro note. Write the record down now, because a prompt experiment is one quiet week away from becoming production behavior, and by then nobody remembers it was an experiment.

The trap is thinking better prompts fix this. They don't. The real problem is that a reviewer cannot trace why an agent did what it did, and you fix that with files, not cleverness.

Keep CLAUDE.md short enough to read

An encyclopedic CLAUDE.md trains newcomers to skim, and an unread file behaves exactly like an absent one. So keep the top of the file tiny: roughly the first 15 lines as a table of contents plus links to deeper fragments. Sessions boot with the same assumptions instead of each person guessing.

Here is the shape of a supremacy fragment that fits at the top:

# 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 point of putting it first is precedence. When a skill and the file disagree, the file wins, and everyone can see the rule that says so.

Add friction to the approvals that matter

Approvals go on autopilot fast. People optimize for flow, so a risky bash command slips through on the same reflex that approved the last twenty safe ones. The fix is a short list of paths that always need a second reviewer and never auto-approve, the red-folder list. The permissions docs cover the mechanics of wiring it up.

This is deliberate friction, applied only where it earns its cost. Everything outside the red folders stays fast.

Tag MCP connectors with the data they touch

Context feels local, but an MCP connector can move data off the laptop, and usually the audit finds out before the team does. Tag each connector with the data classes it handles and the retention you expect. Then a security review reads the tags instead of learning the basics during an incident.

Run a change against those four questions before you merge it. If any answer is "we'd have to ask the person who did it," the trail is too thin.

Write down the week's decisions

Sessions rotate daily, and shared memory leaks out with them. So append one .md changelog of the decisions agents relied on that week, the retro note. New teammates inherit the reasoning instead of rumor, and you stop relitigating settled calls. Paste this strip into the PR template to keep the habit honest:

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

None of this replaces architecture judgement. Agents speed up execution, not ownership, and the conventions exist so a human can still answer for the result.

Common questions

• What does Claude Code 2.1.141 mean for team conventions?

  Around the 2.1.141 release the work is contract hygiene: the repo records what is allowed before prompts get clever. The four fixes to standardize are a CLAUDE TOC for the top of CLAUDE.md, a red-folder approval list, data-class tags on MCP connectors, and a weekly retro note. Contracts live in files, not in memory.

• How do you stop CLAUDE.md bloat?

  Keep the top of CLAUDE.md to about 15 lines as a table of contents plus links to deeper fragments, the fix this article calls the CLAUDE TOC. An encyclopedic file gets skimmed, and an unread file behaves like an absent one, so newcomers fall back to chat instead of the repo contract you actually wrote.

• What are data-class tags for MCP connectors?

  Data-class tags label each MCP connector with the data it touches and the retention you expect. The goal is audit readiness. Context feels local while data can leave the laptop, so tagged connectors let a security review read the boundary at a glance instead of discovering it mid-incident.

• What is a weekly retro note in Claude Code workflows?

  A weekly retro note is one appended .md changelog recording the decisions agents relied on that week. It fixes session amnesia, since sessions rotate daily and shared knowledge cannot live only in transcripts. New teammates read the note and inherit the reasoning behind a choice instead of guessing at it.

Start with one convention

Pick the convention that hurts most right now, probably the red-folder list, and put it in the repo this week. Our training installs all four with your team in a working repo, from the TOC to the retro note, so they become muscle memory instead of good intentions.