Claude Code conventions for shared repos

If two of your agent sessions keep racing into the same module and eating a week in the merge, the fix is four small conventions you write into the repo, not more tooling. A shared-repo convention is a file-recorded rule that keeps parallel sessions from colliding in the same place. Claude Code gives you the files to put them in: CLAUDE.md, skills, hooks, and permissions.

The point release you are on is just the occasion. The durable change is a repo whose parallel streams stay reviewable after they merge. Below are the four conventions, with something you can paste, and the merge check that catches the collision before the retro does.

Why the same retro keeps happening

Green CI and explainable delegation are two different things, and teams keep treating them as one. Your tests can pass while nobody can trace why an agent touched the folder it touched. That gap is where the week goes.

The usual reflex is to widen tool access so seniors move faster. That works right up until two streams edit one module and chat is the only place the boundary was ever written down. Chat cannot arbitrate. A file can.

So the goal here is plain: record scope before streams fork, and verify it at merge. Four conventions make that automatic.

Set up the four conventions

Each one removes a specific failure you have probably already lived through.

Session amnesia. Daily session rotation wipes shared memory, so reasoning lives only in transcripts nobody reopens. The fix is a weekly retro note: append one .md changelog of the decisions agents relied on. New teammates inherit reasoning instead of rumor.

Skill drift. Skills multiply until a reviewer cannot tell which one governed a diff. The fix is a skill index. Keep a skills/README.md that lists activation cues and deferrals, so an on-call engineer resolves a mismatch without replaying a session.

Hook thunder. Hooks that fire everywhere stop gating anything, and the alerts blend into wallpaper. The fix is a hook budget: cap active hooks per repo, and document each trigger plus its rollback path.

CLAUDE.md bloat. An encyclopedic CLAUDE.md gets skimmed, and an unread file behaves like an absent one. The permissions it describes may as well not exist. The fix is a CLAUDE TOC: keep the top 15 lines as the rules that win, then link out to deeper fragments.

Paste this CLAUDE.md fragment

Drop this at the top of your CLAUDE.md so every session boots from the same contract.

# 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 is precedence. When two sessions read the same first 15 lines, they start with the same assumptions, and agent output turns back into work your team owns.

Run the merge check

A shared-repo merge should pass when four gates answer without anyone calling a meeting. Here is the question each gate asks.

Turn that into a checklist you can paste into a PR template:

• MCP connectors mentioned (if any) list owners.
• Verification command output is pasted or linked.
• Forked agent work lists parent and child responsibilities.
• Red-folder paths received explicit human acknowledgement.

None of this replaces architecture judgement. Agents speed up execution, not ownership. Two clocks run on every stream, one for shipping and one for explainability, and when only the shipping clock ticks you pay later with interest. Our methodology starts both at Plan; the team conventions cluster keeps both running.

Further reading

• Claude Code getting started
• Model Context Protocol specification
• Anthropic Claude Code product page
• anthropics/skills on GitHub

Start with the merge check

Pick the merge check first: it is four boxes, and it catches the collision before the retro does. If two streams collided this month, book a 15-minute sync with the retro notes and we will turn the apology into a convention in one working session.