Claude Code 2.1.136: team convention fixes
If you run Claude Code on a team, the four fixes that hold up best are a weekly retro note, a skill index, a hook budget, and a short CLAUDE.md table of contents. Claude Code gives every developer a lot of power on day one, and these four conventions keep that power readable to the next reviewer. A team convention fix is a small repo-recorded rule that turns an invisible habit into something a person can audit. Each one started as a real headache we kept hitting around the 2.1.136 release week.
The pattern underneath all of them is the same. Knowledge ends up in chat transcripts instead of files, and transcripts do not survive a session rotation. The work below is mostly about moving that knowledge into the repo, where the agent and the reviewer both read it.
Write a weekly retro note so sessions stop forgetting
Sessions rotate, often daily, and the reasoning behind a decision rotates out with them. A new teammate inherits the code but not the why. That gap is what people mean when they say a session "forgot" something.
The fix is one short markdown changelog, appended once a week, listing the decisions agents actually relied on. Add a /retro slash command in .claude/commands so the append becomes a habit rather than a chore. The note then doubles as the first place a reviewer looks when a session's choices look surprising.
Keep a skill index so reviewers know what governed a diff
Skills multiply fast. Once you have a dozen, a reviewer staring at a diff cannot tell which skill shaped it, and an on-call engineer cannot tell either without replaying the whole session.
Maintain a skills/README.md that lists each skill, its activation cue, and what it defers to. Make precedence explicit, because discovery alone does not tell you which rule won when two could have fired. With the index in place, a mismatch gets resolved by reading one file.
Set a hook budget so alerts keep their meaning
Hooks that fire on everything train developers to ignore them. An alert that shows up on every commit stops being an alert and becomes wallpaper.
Cap the number of active hooks per repo, and document each one's trigger and its rollback path. The cap is the point: a small set of hooks that each mean something beats a large set that nobody reads. When a hook fires under a budget, people still look up.
Trim CLAUDE.md to a table of contents
An encyclopedic CLAUDE.md gets skimmed, and a skimmed file behaves like an absent one. The agent boots with vague assumptions, and so does the human reading along.
Keep the top 15 lines as the rules that override everything, then link out to deeper fragments for the detail. Those first lines are the cheapest alignment a team buys, because every session starts by reading them. Here is the kind of supremacy fragment we put 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.
For how this fits the larger picture, the wider team conventions cluster applies the same split release by release, and the Claude Code 2.1.132 note is the closest sibling. Our methodology draws the line at review: a test proves behavior, a review proves the team can explain that behavior.
Hand reviewers a checklist they can run
Four gates decide whether a merge is explainable or just green. Each one asks a question a reviewer can answer by reading the repo, not by guessing.
| Gate | Question |
|---|---|
| Risk routing | Were red folders touched, and who approved? |
| Replay proof | Which commands prove regression guards? |
| Receipt match | Does the PR body list scopes plus a verification transcript? |
| Rules precedence | Which .mdc, SKILL.md, or CLAUDE.md governed behavior? |
Paste this into your PR template so the handoff is the same every time:
- MCP connectors mentioned (if any) list owners.
- Verification command output is pasted or linked.
- Forked agent work lists parent plus child responsibilities.
- Red-folder paths received explicit human acknowledgement.
If your repo cannot state its boundaries plainly, agents will guess, and guessing scales badly.
Where to go next
Pick the weekly retro note first, since it costs one paragraph a week and immediately preserves the reasoning agents leaned on. If rolling this out across squads is the blocked step, book a 15-minute sync; we have run it in rooms where half the team was skeptical.