A Team Operating Model for Claude Code

Claude Code works best for teams when the repo has shared rules, clear integration boundaries, and a review habit that humans still own. Claude Code, Anthropic's coding agent, can follow your workflow more reliably when team conventions live in the repository instead of in scattered chat prompts.

Claude Code team conventions are the durable instructions, permissions, review expectations, and integration rules that make a Claude Code workflow predictable across engineers. As of June 22, 2026, the official Claude Code changelog lists version 2.1.186; do not infer hidden feature behavior from the version number alone, but do use release checkpoints like this to tighten how your team uses CLAUDE.md, hooks, MCP, and reviews.

Start with the workflow your team already trusts

Begin with the path a real change takes through your repo: issue, branch, implementation, tests, review, merge, release. Your conventions should make that path easier for Claude Code to follow, not replace it with a parallel fantasy process.

For example, a backend team might say: small PRs only, schema changes require a migration plan, public API changes need docs, and test failures must be pasted into the PR summary. That belongs in team memory because it changes how Claude should plan and report work.

The trap is writing a giant policy document that nobody reads. If your CLAUDE.md is longer than your onboarding guide, it will go stale quickly. Keep the root file short, then push local details into nested files near the code they govern.

This is the same operating-model idea behind the related training topic: make the shared path visible before you ask an agent to move faster.

Put durable repo rules in CLAUDE.md

Use CLAUDE.md for rules that should survive across tasks. Good entries describe architecture boundaries, testing commands, package manager rules, review expectations, and terms the team uses in a specific way. A useful root CLAUDE.md might say the web app lives in apps/web, shared UI lives in packages/ui, database changes require a migration, and end-to-end tests are expensive so unit tests should run first. A nested apps/web/CLAUDE.md can then add local rules about routing, server components, or feature flags. Keep task prompts out of memory; those belong in the chat or issue.

For a deeper pattern library, see Practical Rules for Claude Code Teams. Keep your own version shorter than you think.

Use hooks and permissions as guardrails, not vibes

Hooks are useful when the same boundary should fire every time. A pre-tool hook might block edits under infra/prod unless the branch name includes a change ticket. A post-tool hook might run formatting after edits in a TypeScript package.

Permissions should match the risk of the action. Reading code is low risk. Editing generated files, touching secrets, pushing branches, running migrations, or calling production systems is not. Make those boundaries explicit so a claude code for teams rollout does not depend on everyone remembering the same unwritten rule.

The trap is using hooks to hide team disagreement. If engineers argue about whether Claude may edit migrations, solve the policy first. A hook is an enforcement point, not a substitute for a decision.

Treat MCP as access to real systems

MCP is the integration layer that lets Claude-compatible clients and servers connect to external tools and data. In a team setting, that can mean GitHub issues, internal docs, design systems, ticketing systems, databases, or private knowledge bases.

That power needs ownership. If Claude Code can read a document store, decide which collections are allowed. If it can open GitHub issues, decide whether it may comment, label, or create branches. If it can query a database, prefer read-only access and safe environments unless you have a very strong reason to do more.

The trap is treating MCP as harmless because it feels like context. It is not just context once the server can perform actions. Document each server, its owner, allowed operations, and the review path for changing permissions.

Adopt agent teams only after the single-agent path is boring

Claude Code agent teams can help when work is naturally parallel: one agent investigates tests, another reads the UI layer, another drafts migration notes, and a coordinator compares outputs. That is useful for broad refactors or bug hunts with several unknowns.

For normal product work, start with one clear agent workflow. Ask Claude to plan, edit, test, summarize, and prepare the PR notes. Once that is boring and repeatable, split work into subagents with named responsibilities.

The trap is parallelizing before you have review conventions. More agents create more artifacts to reconcile. Without a checklist, you get speed plus confusion, which is a bad trade.

Copy this team starter checklist

Paste this into a repo issue, team handbook, or CLAUDE.md draft. It is intentionally small. The goal is to create one shared operating model, then improve it after two or three real PRs.

# Claude Code team starter checklist

## Repository memory
- [ ] Root CLAUDE.md explains architecture, package manager, test commands, and PR expectations.
- [ ] Nested CLAUDE.md files exist for areas with special rules, such as apps/web, packages/ui, or infra.
- [ ] Task-specific prompts are kept out of CLAUDE.md.

## Review expectations
- [ ] Every Claude-assisted PR includes: goal, files changed, tests run, tests not run, and known risks.
- [ ] Humans review architecture, security, data migrations, and user-visible behavior.
- [ ] Claude may suggest fixes after review comments, but the author owns the final diff.

## Hooks and permissions
- [ ] Hooks enforce formatting, test commands, or blocked paths where the rule is stable.
- [ ] Destructive commands require explicit approval.
- [ ] Generated files, migrations, secrets, and production config have named rules.

## MCP integrations
- [ ] Each MCP server has an owner.
- [ ] Allowed operations are documented: read, comment, create, update, or execute.
- [ ] Production data access is read-only or unavailable by default.
- [ ] Permission changes are reviewed like code changes.

## Adoption habit
- [ ] Run the workflow on one low-risk repo first.
- [ ] Collect three confusing moments from real PRs.
- [ ] Update CLAUDE.md, hooks, or MCP permissions based on those moments.

Common questions

• How should Claude Code teams get started without making a mess?

  Start with one repo, one CLAUDE.md, and one review checklist. The first rollout should cover a low-risk service or internal tool, not a production-critical migration path. After three Claude-assisted PRs, update the memory and permissions based on what reviewers actually corrected.

• Should every repo have a CLAUDE.md?

  Yes, every active repo should have at least a short CLAUDE.md if the team uses Claude Code there. A useful first version can be under 40 lines: architecture map, install command, test command, review rules, and areas Claude should not edit without approval.

• Where do hooks end and MCP begins?

  Hooks enforce local workflow boundaries; MCP connects Claude to external systems. Use hooks for repo actions like formatting, path restrictions, or test checks. Use MCP for tools such as issue trackers, docs, GitHub workflows, databases, and private knowledge stores, with permissions documented per server.

• Do we need Claude Code agent teams for normal product work?

  No, not at first. Most teams should make a single-agent claude code workflow reliable before adding parallel agents. Agent teams become useful when the work can be split cleanly, such as investigation, implementation, testing, and documentation, and when review expectations are already written down.

• What should humans still review manually?

  Humans should still review architecture, security, data handling, migrations, API contracts, and user-facing behavior. Claude can summarize evidence and propose fixes, but it should not be the final authority on business risk. A PR checklist is the simplest artifact that keeps this boundary visible.

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

Make the next PR the test

Pick one real PR this week and run it through the checklist above. If the review catches a missing rule, add that rule to CLAUDE.md, a hook, or an MCP permission note before scaling the workflow.

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.