Claude Code team conventions

Claude Code team conventions are one durable repo memory, one on-demand skill layer, and one review boundary, written down so agent work stays legible. Teams do not usually lose time because Claude Code is weak. They lose time because every repo invents its own rules, every reviewer asks the same questions, and nobody can tell which context is durable and which is just task noise. If you are trying to ship with Claude Code teams, the real job is to make the workflow legible before it gets clever.

The situation

Counter-thesis: the problem is not more agent power; it is less shared convention.

The wrong path: we believed better prompts would fix drift. We tried to keep everything in chat, then in one giant CLAUDE.md, then in ad hoc review comments. Here is what happened to teams on the floor: the agent got faster, but the handoff got fuzzier, and reviewers had to reconstruct intent from diffs.

Diagnosis: this is the old “local knowledge becomes process debt” trap. The fix is not mystical. It is context engineering.

Thesis: Claude Code teams need one durable repo memory, one on-demand skill layer, and one review boundary.

That thesis holds up across the Claude Code docs. CLAUDE.md is always-on context, skills are loaded when needed, hooks run outside the model loop, and MCP defines the connector boundary. The changelog keeps pushing teams toward a more explicit operating model, not a looser one.

What breaks first, and what to change

Shared context drifts when everything lives in chat. If you have shipped AI code, you have hit this: the model remembers the last request, not the repo rule. The named fix is the Three-Tier Memory Rule: put durable repo facts in CLAUDE.md, task procedures in a skill, and temporary instructions in the prompt. Claude’s docs already separate always-on context from skills that load only when used, which is the right shape for team work. The payoff is simple: fewer repeated explanations, fewer “why did it do that?” reviews, and less accidental policy spread. Keep the rule short enough that people will actually maintain it.

Review expectations stay vague. Teams often say “review the diff,” but that is not a standard. The named fix is the Review Receipt Checklist: every Claude-authored change should say what rule it followed, what file or skill it used, and what the reviewer must verify. This is where CLAUDE.md and team conventions matter most. A reviewer should not have to guess whether a change was meant to be local, reusable, or policy-bearing. The result is faster trust.

Automation leaks into the model loop. Hooks exist for a reason. They are deterministic infrastructure for lifecycle checks, permission boundaries, logging, formatting, and validation. The named fix is the Hook Boundary Rule: use hooks for things that must always happen, and keep model prompts for judgment. Claude Code’s hooks reference makes this boundary explicit, including session, tool, and permission events. When teams move checks out of chat and into hooks, they get fewer surprise failures and cleaner blame when something blocks. That is the point.

Connector scope gets too broad too fast. MCP is useful because it connects Claude to external systems, but every connector widens the review surface. The named fix is the MCP Permission Note: every new server or tool should ship with a short note that says what it can reach, why it needs it, and who approved it. The permissions docs and MCP spec both point in the same direction: least privilege, explicit scope, and reviewable settings. If you skip that note, you do not just add risk; you add confusion for the next engineer who inherits the setup.

Skills become junk drawers. A skill should be a reusable procedure, not a second CLAUDE.md. Claude Code skills load on demand, support supporting files, and can be invoked directly. The named fix is the Skill Description Test: if the description cannot tell a teammate when to use it, the skill is not ready. Good descriptions matter because they control discovery. Bad ones create invisible sprawl. This is where Claude Code workflow discipline pays off.

Synthesis: make memory durable, make procedures reusable, and make enforcement deterministic.

A practical team artifact

Use this as a starter checklist for a repo that wants Claude Code team conventions to stay reviewable:

# Claude Code team checklist

- [ ] `CLAUDE.md` contains only durable repo rules, not task scripts.
- [ ] Repeated procedures are moved into `SKILL.md` files with clear descriptions.
- [ ] Hooks cover checks that must always run: formatting, validation, permission gating.
- [ ] Every MCP connector has a short permission note and an owner.
- [ ] Pull requests include a review receipt: what changed, what rule it followed, what to verify.
- [ ] Reviewers know where to look for scoped context before they trust the diff.
- [ ] Temporary instructions are removed after the task ends.

If you want one concrete file fragment, keep CLAUDE.md small and blunt:

# CLAUDE.md

- Prefer small diffs.
- Do not change auth, billing, or deployment settings without explicit review.
- Use the repo skill for release steps.
- If a hook blocks, fix the cause; do not bypass it.

That is enough to start. It is also enough to expose where the team is still improvising.

Tradeoffs and limits

The thesis is not “put everything in files.” Some work still belongs in chat, especially exploratory debugging and one-off judgment calls. Hooks can also become brittle if teams overload them, and MCP can slow adoption if permissions are too strict without explanation.

The rule is balance, not purity. Keep the durable parts durable. Keep the temporary parts temporary.

Best ways to use this research

• Best for: Claude Code teams deciding which CLAUDE.md convention, hook, skill, or MCP boundary to standardize next around “Claude Code team conventions.”
• Best first artifact: turn the named fix into a CLAUDE.md convention, hook checklist, skill note, or review receipt before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Common questions

• What are Claude Code team conventions?

  Claude Code team conventions are one durable repo memory, one on-demand skill layer, and one review boundary, kept explicit so reviewers stop reconstructing intent from diffs. In practice that means CLAUDE.md for always-on context, SKILL.md files for procedures, hooks for checks that must always run, and MCP permission notes.

• What is the Three-Tier Memory Rule?

  The Three-Tier Memory Rule puts durable repo facts in CLAUDE.md, task procedures in a skill, and temporary instructions in the prompt. The payoff is fewer repeated explanations, fewer why-did-it-do-that reviews, and less accidental policy spread, provided the rule stays short enough that people maintain it.

• What goes in a review receipt for Claude-authored changes?

  Every Claude-authored change should say what rule it followed, what file or skill it used, and what the reviewer must verify. That is the Review Receipt Checklist, and it exists because "review the diff" is not a standard; reviewers should not guess whether a change was local, reusable, or policy-bearing.

• Should everything move out of chat and into files?

  No, some work still belongs in chat, especially exploratory debugging and one-off judgment calls that do not repeat. The rule is balance, not purity: keep the durable parts durable, keep the temporary parts temporary, and remember hooks become brittle when teams overload them.

Further reading

• Claude Code — getting started
• Claude Code — skills
• Claude Code — hooks
• Claude Code — permissions
• Model Context Protocol — specification
• Anthropic — Claude Code product page
• GitHub — anthropics/skills
• Claude Code team conventions
• Our methodology

Next step

Pick one repo and write the first version of CLAUDE.md, then review it with the team before you add any new skill or connector. If you want the broader training path, start at /topics/team-conventions.