Practical Rules for Claude Code Teams

Claude Code teams work best when the repository teaches Claude the same rules the humans use. Claude Code, Anthropic's coding agent, becomes safer and more useful when CLAUDE.md, hooks, permissions, MCP, and review habits are treated as team infrastructure, not personal preferences.

A Claude Code team convention is a written, versioned rule that tells Claude how your team builds, tests, reviews, and ships code. As of June 20, 2026, the official Claude Code changelog lists Claude Code 2.1.185; the practical takeaway is to re-check whether your shared workflow has kept up with the documented surfaces teams now rely on.

Put durable context in CLAUDE.md

Start with CLAUDE.md because it is the easiest shared contract to adopt. It should hold durable repository context: architecture shape, test commands, migration rules, security boundaries, naming conventions, and the review expectations Claude should remember across tasks.

Keep it short enough that engineers will maintain it. A good CLAUDE.md reads like the first page you wish every new teammate read before touching the repo.

In a payments-service repo, useful memory might say: database migrations must be backward compatible, money math must use the internal Decimal wrapper, and tests for ledger changes must include both success and reversal flows. That is much better than saying: follow best practices.

The trap is using CLAUDE.md as a dumping ground for every preference anyone has ever expressed. Put temporary task details in the prompt. Put durable team rules in memory. For more patterns like this, keep a lightweight owner for team conventions rather than letting the file drift.

Add hooks where mistakes are predictable

Use hooks for checks you would not trust people, or Claude, to remember every time. Hooks are a good fit for formatting, test gates, generated-file warnings, dependency policy, secrets scans, or blocking edits in files that require special review.

This matters because a Claude Code workflow can move quickly. The faster the loop, the more valuable automatic friction becomes at the exact point of risk.

A practical hook boundary might be: allow edits under src/, warn on edits under infra/, and block changes to prod-secrets/ unless the task explicitly says an infra maintainer is pairing. That is not bureaucracy. It is your deployment model encoded close to the work.

The trap is making hooks too clever. Hooks should catch clear, mechanical problems. Do not put architectural judgment into a shell script and then pretend review is solved.

Use MCP and permissions as a trust boundary

Model Context Protocol, usually shortened to MCP, is the integration layer that lets Claude connect to external systems such as GitHub, Slack, Jira, document stores, databases, and internal knowledge bases. For Claude Code for teams, MCP should be treated like any other production integration: useful, permissioned, and reviewed.

Start with read-only access unless the workflow clearly needs writes. For example, a support-engineering repo might let Claude read linked incident notes and GitHub issues, but require human confirmation before creating tickets, changing labels, or posting status updates.

This matters because shared context is powerful. The same connection that helps Claude understand an outage can also expose sensitive data or create noisy side effects if permissions are too broad.

The trap is connecting everything because it feels convenient. Give Claude the smallest useful window into external systems, then expand after the team can name the exact workflow that benefits.

Teach repeatable work with skills and review habits

Use Claude skills for repeatable work that needs more than a sentence of instruction. A skill can package a workflow, scripts, reference data, templates, and examples so Claude can perform a task in the way your team expects.

Good candidates include writing database migration plans, producing release notes, triaging flaky tests, or preparing a security review summary. The activation surface matters: name and describe the skill in plain terms so Claude can choose it at the right moment.

Pair skills with a review habit. If Claude prepares a migration plan, the review checklist should ask whether rollback is covered, whether the migration is backward compatible, and whether any long-running lock is possible.

The trap is using skills as a substitute for code review. Skills make a Claude Code workshop or internal training easier to scale, but they do not remove the need for owners, reviewers, and clear acceptance criteria. If your main risk is review quality, pair this with A Team Claude Code Review Workflow.

Know when not to standardize

Do not standardize every prompt. Teams need conventions for repeated, high-risk, or cross-repo work. They do not need a policy for every small refactor or exploratory question.

A good rule of thumb: standardize when the mistake is expensive, the workflow repeats, or the context is hard for a new engineer to discover. Leave one-off investigation flexible.

This is especially important for Claude Code agent teams. Parallel agents can help explore options, test hypotheses, or split implementation work, but they need sharper boundaries than a single local session. Define ownership, branch strategy, and review expectations before asking multiple agents to change the same area.

The trap is confusing consistency with control. The goal is not to make every Claude interaction identical. The goal is to make safe paths obvious and risky paths visible.

Copyable team operating checklist

Paste this into a repo issue, an onboarding doc, or the top of your first team PR. Keep the owner names real. A checklist with no owner becomes wallpaper.

# Claude Code team operating checklist

## Repository memory
- [ ] Create or refresh root `CLAUDE.md`.
- [ ] Add the repo purpose, main services, local setup, and test commands.
- [ ] Document non-negotiable rules: security, migrations, API compatibility, generated files.
- [ ] Move task-specific instructions out of CLAUDE.md and into prompts or issues.
- [ ] Assign one maintainer to review CLAUDE.md changes each sprint.

## Scoped conventions
- [ ] Add nested memory near areas with special rules, such as `infra/`, `mobile/`, or `packages/billing/`.
- [ ] Prefer local rules for local constraints; do not overload the root file.
- [ ] Include one good example and one forbidden example for fragile workflows.

## Hooks and permissions
- [ ] Add hooks for formatting, tests, generated files, and secret checks.
- [ ] Make dangerous paths warn or block before changes are applied.
- [ ] Review Claude Code permissions as a team, not as individual dotfiles.
- [ ] Start MCP integrations read-only unless write access has a named use case.

## Skills and commands
- [ ] Create skills for repeatable workflows such as migration plans, release notes, or incident summaries.
- [ ] Add slash commands for common team actions that need consistent inputs.
- [ ] Keep skill descriptions specific enough that Claude can select the right skill.

## Review expectations
- [ ] Every Claude-assisted PR says what Claude changed and what a human verified.
- [ ] Reviewers check tests, risk areas, rollback, and whether repository conventions were followed.
- [ ] Agent-team work uses separate branches or worktrees when changes may collide.
- [ ] The team revisits this checklist after two weeks of real usage.

Common questions

• How should Claude Code teams share context without creating noise?

  Share context through a small root CLAUDE.md plus scoped files near code that has special rules. The citable rule is simple: root memory should cover repo-wide behavior, while nested memory should cover local constraints such as billing, infra, or mobile release rules.

• Should we use Claude Code for teams or keep it as an individual tool?

  Use Claude Code as a team tool when the work crosses shared standards, production code, or review expectations. Individual use is fine for local exploration, but team use needs at least one shared CLAUDE.md, a review checklist, and agreed permission boundaries.

• When do hooks become worth the setup?

  Hooks are worth it when the same preventable mistake shows up more than once. Start with two or three mechanical checks, such as formatting, tests, or blocked secret paths, and avoid turning hooks into a second review system with unclear ownership.

• Do we need MCP on day one?

  No, you do not need MCP on day one. Begin with repository context and review habits; add MCP when Claude needs external context, such as issues, incidents, design docs, or internal knowledge bases, and start with read-only access when possible.

• Are Claude skills the same thing as CLAUDE.md?

  No, Claude skills and CLAUDE.md solve different problems. CLAUDE.md is always-on repository memory, while a skill is an on-demand capability for a repeatable workflow, such as preparing release notes or checking a migration plan against a team template.

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 — official changelog

Make one convention real this week

Pick one repo, update CLAUDE.md, add one hook, and require one Claude-assisted PR to use the checklist. Small, reviewed conventions beat a grand rollout that nobody maintains.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.