Adopt Claude Code as a Team

Teams adopt Claude Code by treating it like a shared engineering workflow, not a personal autocomplete tool. Start with one repo, write the rules in CLAUDE.md, connect only the MCP systems the team can govern, and review AI-assisted changes with the same standards as human changes.

Claude Code, Anthropic's coding agent, is most useful when the repository explains how the team builds, tests, and reviews software. A small Claude Code workshop works best when it ends with copyable conventions, not slides.

Write the repo rules before you scale usage

A Claude Code convention is a durable instruction that helps the agent work inside your team's real constraints. Put those conventions in CLAUDE.md so they travel with the codebase instead of living in one person's prompt history.

For a payments API repo, the root CLAUDE.md might say which test command proves a change, where database migrations live, and which files require security review. A nested CLAUDE.md under services/billing/ can add local rules for idempotency keys, ledger writes, and retry behavior.

This matters because Claude Code memory should separate durable rules from task-specific prompts. The trap is writing a giant root file that tries to explain the whole company. Keep the root short, then add scoped files where the code actually needs local knowledge.

This is also the moment to point teammates to the related training topic. Team conventions are adoption infrastructure, not documentation theater.

Roll out the workflow in one repo

Prerequisites: pick one active repository, choose two maintainers, identify the default test command, list the systems Claude Code may read, and decide who can approve changes to CLAUDE.md. Keep the first rollout boring. Boring is how you learn.

Step 1: name the boundary. Choose one workflow, such as bug fixes in a Node service or UI cleanup in a React package. Do not start with migrations, auth, deployment, and incident response all at once.

Step 2: write the shared context. Add a short CLAUDE.md with architecture notes, commands, review expectations, and non-negotiables. If engineers disagree with the file, fix the file before asking Claude Code to follow it.

Step 3: add one reusable skill. A Claude skill can package a repeatable task like writing a safe migration plan or preparing a release note. Keep the description precise, because that is the activation surface the agent sees before it reads the full skill.

Step 4: connect one MCP integration. MCP is the integration layer that lets tools expose context and actions to coding agents through a common protocol. Start with a read-heavy integration such as issue context or design docs before giving write access to production-adjacent systems.

Step 5: review the first five pull requests together. Use the same checklist every time. Look for whether Claude Code used the repo rules, ran the right tests, and left a change a teammate can maintain.

Step 6: verify the setup works. Ask a new teammate to run the workflow from a fresh clone and produce a small PR. The proof is not that Claude Code can edit files; the proof is that the repo teaches the agent the same habits your team expects from a human contributor.

For engineering team AI adoption, this narrow rollout beats a broad mandate. It gives you feedback on real friction while the blast radius is still small. If you want a facilitated version, a Run a Claude Code Team Workshop session should produce these same artifacts in a shared repo.

Put MCP and permissions behind team decisions

As of June 26, 2026, the official Claude Code changelog identifies Claude Code 2.1.195, which is a useful reminder that the product surface will keep moving. Treat each changelog entry as a prompt to re-check your conventions, permissions, hooks, and integrations.

For example, a team might allow Claude Code to read GitHub issues and internal docs through MCP, but require explicit approval before touching Jira status, posting to Slack, or running deployment commands. That is not mistrust. It is normal production hygiene.

The trap is connecting every useful system on day one. MCP makes integrations easier, but easy access still needs ownership. Write down who owns each server, what it can read, what it can change, and which actions require human approval.

Make review expectations visible

Claude Code for teams works best when review is part of the workflow, not an apology after the agent gets something wrong. Put review rules in the repo and make them specific enough to catch the failures your codebase actually has.

In a backend service, your review checklist might require a regression test, a migration rollback note, and evidence that the agent did not broaden an API contract. In a frontend app, it might require accessibility checks, screenshot review, and a note about shared component reuse.

Hooks can help enforce the boring parts. A pre-tool or post-tool hook can remind the agent to run a formatter, block risky shell commands, or capture a test summary before the session ends. The trap is using hooks as a substitute for judgment; they are guardrails, not reviewers.

Copyable team rollout plan

Paste this into an issue, planning doc, or workshop repo. Trim it until it matches how your team actually works.

# Claude Code team rollout plan

## Scope
- Pilot repo: payments-api
- Pilot workflow: small bug fixes and test-backed refactors
- Pilot length: 2 weeks
- Owners: tech lead, staff reviewer, developer experience owner

## CLAUDE.md starter
Claude should follow these repository conventions:

- Prefer small pull requests with one clear behavior change.
- Before editing code, inspect the nearest package README and nested CLAUDE.md.
- Run the smallest relevant test first, then the package test command before final review.
- Do not change public API behavior without calling it out in the PR summary.
- For database changes, include migration direction, rollback notes, and data safety assumptions.
- Ask before modifying auth, billing, secrets, deployment, or incident tooling.

## MCP permission note
Allowed during pilot:
- Read GitHub issues and pull request discussion.
- Read internal engineering docs marked public-to-engineering.

Requires human approval:
- Posting comments, changing issue status, or assigning reviewers.
- Reading customer data, secrets, production logs, or incident channels.
- Running deploy, migration, or infrastructure commands.

## Hook boundary
Use hooks for repeatable checks only:
- Format changed files before final response.
- Block shell commands that touch production-like targets.
- Capture the final test command and result in the session summary.

Do not use hooks to hide risky behavior. If a workflow needs policy judgment, require review.

## Review checklist
- Did the change follow CLAUDE.md and any nested CLAUDE.md files?
- Is the diff small enough for a human to review carefully?
- Are tests added or updated where behavior changed?
- Did Claude Code explain assumptions and skipped options?
- Are MCP reads and writes appropriate for the task?
- Would we accept the same PR from a human teammate?

## Exit criteria
- Five merged PRs that pass the checklist.
- One rejected or revised PR with lessons captured.
- CLAUDE.md updated from real review feedback.
- Team decision: expand, pause, or narrow the workflow.

Common questions

• How do teams adopt Claude Code for coding workflows?

  Teams adopt Claude Code for coding workflows by starting with one governed repo, writing shared rules in CLAUDE.md, limiting MCP access, and reviewing the first PRs together. A practical pilot needs at least one workflow boundary, one maintainer-owned convention file, one test command, and one review checklist before usage expands.

• Should CLAUDE.md be global or per repository?

  Use both, but keep them different. Global memory is for personal preferences and stable working style; repository CLAUDE.md is for team rules, architecture constraints, commands, and review expectations. The useful pattern is a short root file plus nested files for areas like billing, mobile, infra, or data pipelines.

• When should we add Claude skills instead of more CLAUDE.md text?

  Add a skill when the team repeats a workflow that has steps, templates, or reference material. CLAUDE.md should hold always-on rules; Claude skills should package on-demand capabilities such as release notes, migration planning, or incident follow-up. If the instruction is only relevant sometimes, it probably belongs in a skill.

• How much MCP access should a pilot have?

  A pilot should start with the least access that makes the workflow useful. Read-only issue, pull request, and documentation context is usually safer than write actions across chat, tickets, or infrastructure. Write down each MCP server owner, allowed data class, and approval rule before people depend on it.

• Do we need a Claude Code workshop to make this stick?

  You do not need a workshop, but a focused Claude Code workshop helps teams agree faster. The useful output is not training trivia; it is a committed CLAUDE.md, a permission note, a review checklist, and a pilot plan. Without those artifacts, people drift back to private prompts and inconsistent review habits.

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 changelog

Start with one boring win

Pick one repo, one workflow, and one reviewer-owned CLAUDE.md this week. After five real PRs, you will know which conventions deserve to become your team standard.

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.