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, Anthropic's coding agent, 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.

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.

Common questions

• What are the Claude Code 2.1.136 team convention fixes?

  They are a weekly retro note, a skill index, a hook budget, and a CLAUDE.md table of contents. Each targets one recurring failure: session amnesia, skill drift, hook thunder, and CLAUDE.md bloat. They work because trust on a team scales through permission literacy, meaning everyone can read who can do what, not through adding one more prompt template.

• How does a weekly retro note fix session amnesia?

  It appends one markdown changelog each week with the decisions agents relied on, so reasoning lives in a file instead of a transcript that rotates out. New teammates inherit the why, not rumor. The note also becomes the first artifact a reviewer checks when a session's choices look surprising, which makes it earn its keep quickly.

• What evidence should a Claude Code PR hand to reviewers?

  Four receipts: MCP connectors list their owners, verification command output is pasted or linked, forked agent work lists parent and child responsibilities, and red-folder paths show explicit human acknowledgement. Behind those, the gates ask who approved risky paths and which commands prove the regression guards held. A green test suite without these is only half a receipt.

• Does testing replace review for agent work?

  No. A test proves behavior, and a review proves the team can explain that behavior, so the two do different jobs. Agents amplify whatever clarity already exists in your files, hooks, and scopes, so an unexplainable diff with passing tests still fails review. Keep both gates.

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, talk to us; we have run it in rooms where half the team was skeptical.

Further reading

• Claude Code getting started
• Claude Code permissions
• Model Context Protocol specification
• anthropics/skills on GitHub