Claude Code team conventions for coding workflows

Teams adopt Claude Code by making the repo explain itself before the model does. Claude Code, Anthropic's coding agent, is a workflow system rather than a chat box: it does its best work when the team gives it shared context, clear review rules, and one small rollout plan instead of a pile of ad hoc prompts. A team convention is just a durable rule the whole team agrees the agent should always follow. Write those down once, in the repo, and most adoption pain goes away.

The hard part is not getting people access. It is keeping the agent's instructions in one place so reviewers always know what was true.

Put durable rules in CLAUDE.md

CLAUDE.md is the file Claude Code reads automatically as always-on context. This is where your durable repo rules belong: the conventions that hold for every task, like the test command, the directories that are off limits, and the house style.

Keep it short. The goal is placement, not volume. When the same rule lives in chat, in a PR comment, and in a half-forgotten doc, the agent and the reviewers stop knowing what is always true.

Split local exceptions into nested CLAUDE.md files where the code actually lives. Claude Code supports scoped project memory, so a rule that only applies to one package can sit next to that package. After this, the model sees the same boundary every time, and reviewers stop guessing what the agent was told. The getting started docs walk through how this loads.

Move repeat procedures into skills

When you catch yourself pasting the same checklist into every session, that instruction is procedural, not factual. It does not belong in CLAUDE.md. It belongs in a skill.

A skill is a SKILL.md file that describes a repeatable procedure, plus a short description sharp enough that Claude Code can find it when the moment is right. The skills docs note that skills load only when used, which is why they scale better than stuffing every procedure into always-on memory.

The practical change is small and real: less copy-paste, more reuse, fewer stale prompts. Your always-on context stays lean, and your procedures stay where they can be improved over time.

Make automation visible with hooks

If hooks are vague, they become surprise behavior. If they are absent, the team relies on memory for checks that should run on their own. Either way, trust erodes.

Hooks are scripts Claude Code runs at set points in its lifecycle, so you can make a check deterministic instead of tribal. The hooks reference covers events such as PreToolUse, PostToolUse, and PermissionRequest. Use them for validation, formatting, and permission boundaries.

The win is clarity. Once hooks are written down, the team can say plainly what runs automatically and what still needs a human to approve it.

Review MCP access like production config

MCP, the Model Context Protocol, is the connector layer that lets Claude Code reach outside tools and data. It is useful, and a wide connector surface without review quietly turns a coding workflow into a permission problem.

Treat .mcp.json the way you treat production config. Name the data boundary, approve only the minimum scope a pilot needs, and keep least privilege in writing. The permissions docs explain how Claude Code enforces access; the protocol spec defines what each connector can do. Read both before you open anything to shared systems.

Require a review receipt for agent PRs

"The agent wrote it" is not a review. The habit that turns adoption into something repeatable is asking every Claude-authored pull request to carry a short receipt: what changed, what was verified, what permissions were used, and what is still uncertain.

This keeps reviewers honest about the artifact instead of the intention. You can paste the rollout plan below into your pilot repo as the first shared checklist in a workshop.

# Claude Code team rollout plan

## Prerequisites
- One repo owner for the rollout
- One shared place for `CLAUDE.md`
- One reviewer who can approve hooks and MCP access
- One pilot repo with real PR traffic

## Step 1: name the boundary.
Write the repo rules that must always hold in `CLAUDE.md`.
Keep it short and specific.

## Step 2: move repeat work into skills.
Create one `SKILL.md` for a repeated procedure.
Use it for work that is procedural, not permanent.

## Step 3: add deterministic checks.
Add hooks for validation, formatting, or permission review.
Document which events are automatic and which are blocked.

## Step 4: review connector access.
List every MCP server and the data it can reach.
Approve only the minimum scope needed for the pilot.

## Step 5: define review expectations.
Require a Claude-authored PR checklist.
Ask for proof, not just a summary.

## Step 6: verify the workflow.
Run one real change through Claude Code.
Confirm the repo rules, skill, hook, and review path all behaved as written.

Common questions

• How do teams adopt Claude Code for coding workflows? They standardize repo context, repeatable procedures, deterministic checks, and review rules before broad usage. The practical minimum is one CLAUDE.md, one skill for repeated work, one hook boundary, and one PR checklist. That gives the team a shared operating model instead of a pile of private prompt habits that drift apart from each other.

• What should go in CLAUDE.md versus a skill? Put durable repo facts and team conventions in CLAUDE.md, and put repeatable procedures in a skill. The Claude Code docs say skills load only when used, so they suit step-by-step work that should not sit in always-on memory. The split keeps your repo context small and your procedures reusable across many sessions.

• Do Claude Code hooks replace code review? No. Hooks automate checks and boundaries, but a person still has to review the work. The hooks docs describe lifecycle events and decision control, which makes them good for validation and permission gates. A human reviewer judges intent, risk, and whether the change actually matches the repo contract. Keep both.

• What is the safest first Claude Code workshop exercise? Start with a pilot repo and one small change: one CLAUDE.md fragment, one skill, one review checklist. That is enough to test whether the conventions hold without opening every connector or workflow at once. Keep the scope narrow and the verification real, then expand only after the review path stays stable.

• How much setup does this take before it pays off? The tradeoff is setup time against trust. A team can start faster with loose prompts, but it pays later in review noise and inconsistent output. A short CLAUDE.md plus one PR checklist is usually a single afternoon, and it is the cheapest insurance you can buy before the agent touches shared systems.

Start in one pilot repo

Make the repo explain itself, then let Claude Code work inside that boundary. Open the team conventions topic page, run the rollout plan above in one pilot repo, and turn the checklist into your first workshop exercise.