Claude Code 2.1.122 team conventions

If your merge queue got slower as you added more agents to Claude Code, Anthropic's coding agent, the fix is conventions, not lanes. A team convention is a small written rule that lets a reviewer approve a change without replaying the chat that produced it. Four of them clear the four problems that show up most: session amnesia, skill drift, hook thunder, and CLAUDE.md bloat.

The rule underneath all four is simple. If you cannot narrate the scope of a change, you cannot delegate it safely. So every convention here exists to make intent something a reviewer can read instead of reconstruct.

Write a weekly retro note so memory survives the day

Sessions rotate, and shared memory goes with them. The decisions an agent leaned on yesterday are gone by the time a new teammate opens the repo today. That is session amnesia, and a transcript buried in history does not cure it.

The fix is one Markdown changelog you append to each week. Write down the decisions agents relied on and why. New people inherit reasoning instead of rumor, and reviewers get context without digging through old sessions.

Keep it boring and short. A few lines per decision is enough, as long as the next person can find it.

Index your skills before they drift

Skills multiply fast. Once you have a dozen, a reviewer staring at a diff cannot tell which skill governed it. That is skill drift, and it makes every review slower than it should be.

Keep a skills/README.md that lists each skill, its activation cues, and when it defers to something else. An on-call engineer can then resolve a mismatch by reading the index, not by replaying the session that triggered it.

This one pays off the moment someone unfamiliar with the repo has to debug it at 2am.

Set a hook budget so alerts still mean something

Hooks are useful right up to the point where they fire constantly. Then people learn to ignore them, and the safety automation you built becomes wallpaper. That is hook thunder.

Cap the number of active hooks per repo, and document each one's trigger and its rollback path. When only the hooks that matter fire, the alerts that matter get read. Treat the budget as a real limit, not a suggestion.

Cut CLAUDE.md down to a TOC

A long CLAUDE.md gets skimmed, and an unread file behaves exactly like an absent one. Keep the top of the file to roughly 15 lines: the rules that always win, plus links to the deeper fragments. Sessions then boot with the same assumptions every time.

Here is a supremacy fragment you can paste 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.

A /handoff slash command in .claude/commands that pastes your scope template into the PR body closes the loop, so the reviewer gets the receipt automatically. You can read more in our team conventions cluster, which runs this same order release after release.

Check the PR before you wave it through

When you review an agent's pull request, four questions tell you whether it is safe to approve without a chat replay.

Paste this strip into your PR template and work down it:

• Forked agent work lists parent and child responsibilities.
• Red-folder paths got explicit human acknowledgement.
• Scopes in the PR body match the folders in the diff.
• Primary-doc links were smoke-checked after publishing edits.

None of this replaces architecture judgement. Agents speed up execution, not ownership.

Common questions

• What do Claude Code 2.1.122 team conventions fix?

  They fix four recurring failures: session amnesia, skill drift, hook thunder, and CLAUDE.md bloat. The matching fixes are a weekly retro note, a skill index, a hook budget, and a CLAUDE TOC. The shared goal is a merge a reviewer can defend without replaying the chat that produced it.

• Why do merge trains clog on agent-heavy teams?

  Because parallel agent streams add coordination cost faster than they add throughput. When scope lives only in chat, every change needs an interview before it can move, and that interview is slow. Receipts in the PR body turn the interview into a quick read, so changes flow one at a time.

• What is hook thunder?

  Hook thunder is hooks firing so often that developers learn to ignore them. The noise drowns the alerts that actually matter, which defeats the point of safety automation. A hook budget caps the active hooks per repo and documents each trigger plus its rollback path, so the signal comes back.

• What goes in the weekly retro note?

  The decisions agents relied on that week, appended to one Markdown changelog. Institutional knowledge cannot live only in transcripts, so this note is where session reasoning becomes team property. New teammates inherit the reasoning, and reviewers get context without archaeology through old sessions.

Start with the PR strip

Pick one convention to ship first, and make it the PR proof strip above. Add it to your template today, and the next agent pull request arrives with its scope already written down.