Claude Code team conventions

Good Claude Code team conventions come down to one thing: write down what's durable so agent work stays readable to the next person. Claude Code is Anthropic's coding agent, and a team convention is just a shared rule about where context lives and how changes get reviewed. Most teams don't lose time because the agent is weak. They lose it because every repo invents its own rules, every reviewer asks the same questions, and nobody can tell which context is permanent and which is just leftover from one task.

The fix is small and boring, which is why it works. Put durable facts in one place. Put repeatable procedures in another. Make the must-run checks deterministic. Then a reviewer can trust a diff without rebuilding the whole story behind it.

Sort your context into three buckets

The first thing that breaks is shared memory, because everything ends up in chat. The model remembers your last message, not your repo's rules. So write three buckets and keep them separate:

• Durable repo facts go in CLAUDE.md. This is always-on context the agent reads every session.
• Repeatable procedures go in a skill. These load only when they're needed.
• One-off instructions stay in the prompt and get thrown away when the task ends.

This mirrors how Claude Code already works. CLAUDE.md is always loaded, skills load on demand, and the prompt is temporary by design. The payoff is fewer repeated explanations and far fewer "why did it do that?" reviews. Keep CLAUDE.md short enough that people will actually maintain it, or it rots.

Here's a starter CLAUDE.md that's blunt on purpose:

# 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's enough to start. It also exposes where the team is still improvising, which is the more useful half.

Make every Claude change reviewable

"Review the diff" is not a standard. It asks the reviewer to guess whether a change was meant to be a local hack, a reusable pattern, or a policy decision. That guessing is where trust goes to die.

Attach a short receipt to every Claude-authored change instead. Three lines, no more:

• What rule it followed.
• What file or skill it used.
• What the reviewer needs to verify.

This is the convention that pays off fastest. A reviewer who can see the intended scope in three lines approves in seconds rather than reconstructing it from the diff. Put the receipt in the pull request description and treat a missing one as an incomplete change.

Push must-run checks into hooks

Hooks are deterministic infrastructure that runs outside the model loop. Formatting, validation, logging, and permission gating belong here, not in a prompt where the agent might forget them on a busy day.

The line is simple: hooks handle what must always happen, prompts handle judgment. Claude Code's hooks reference covers session, tool, and permission events, so most lifecycle checks have a natural home. When a check lives in a hook, failures are predictable and blame is clean. When the same check lives in chat, it works until the one time it silently doesn't.

One caution: don't overload hooks. A wall of brittle hooks that block for unclear reasons is its own kind of debt. Add them for the checks you'd be angry to merge without.

Keep skills and MCP scoped

Two things sprawl quietly if you let them: skills and connectors.

A skill is a reusable procedure, not a second CLAUDE.md. The test for whether one is ready is its description. If the description can't tell a teammate when to reach for the skill, it isn't done, because the description is what controls discovery. A junk drawer of vaguely-named skills is invisible until someone trips over it.

MCP connects Claude to external systems, and every connector widens what a reviewer has to think about. Ship each new server with a short permission note: what it can reach, why it needs that, and who approved it. Both the permissions docs and the Model Context Protocol spec point the same way: least privilege, explicit scope, reviewable settings. Skip the note and you hand the next engineer a setup they can't reason about.

A checklist you can paste

Drop this into a repo that wants its Claude Code 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 find scoped context before they trust the diff.
- [ ] Temporary instructions are removed after the task ends.

Common questions

• What are Claude Code team conventions?

  They 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 a permission note on every MCP connector. The goal is legibility before cleverness.

• Where should durable rules live versus task instructions?

  Durable repo facts go in CLAUDE.md, repeatable procedures go in a skill, and one-off instructions stay in the prompt and get discarded. Keeping these three separate prevents accidental policy spread and cuts repeated explanations. The catch: CLAUDE.md has to stay short, or people stop maintaining it and it drifts out of date.

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

  Three lines: what rule the change followed, what file or skill it used, and what the reviewer must verify. This exists because "review the diff" isn't a standard. A receipt lets a reviewer see the intended scope at a glance instead of guessing whether the change was a local hack, a reusable pattern, or a policy decision.

• Should everything move out of chat and into files?

  No. Exploratory debugging and one-off judgment calls still belong in chat, since they don't repeat and don't need to be remembered. The rule is balance, not purity: keep the durable parts durable and the temporary parts temporary. Overloading hooks or over-restricting MCP without explanation just trades one kind of friction for another.

Start with one repo

Pick a single repo, write the first CLAUDE.md with your team, and review it together before you add any skill or connector. For the broader path, start at /topics/team-conventions.