Setting Up Claude Code for a Team (2026 Playbook)

Rolling Claude Code out to one engineer is easy. Rolling it out to 10, 30, or 50 is a different problem. Once you cross five active users, the cracks show up fast: every engineer has a different CLAUDE.md, half the team has wired their own MCP servers with personal tokens, sub-agents drift between forks, and someone has quietly burned through a four-figure month on Opus calls nobody can attribute. The tool is the same. The operating model is not.

The teams getting real leverage from Claude Code in 2026 treat it like infrastructure. There is a shared repo of agents and skills, a vetted MCP catalog, a permission model that does not require a Slack ping every time someone runs a migration, and a cost view the engineering lead actually checks. They have a 30-minute onboarding flow that takes a new hire from npm install -g to shipping a PR. They run Friday demos where engineers show the prompts and workflows that worked. And they accept that the failure modes are mostly organisational, not technical.

This is the playbook we use at AY Automate when we set Claude Code up for engineering teams. It assumes you have read the Claude Code enterprise implementation guide and the Claude Code best practices post — this one is specifically about the team layer: what you put in the repo, what you put in the cloud, and what you put in the calendar.

Centralized vs Distributed setup

The first decision is whether Claude Code config lives in the repo or in each engineer's home directory. Both work. Mixing them badly does not.

A centralized setup keeps everything that matters — CLAUDE.md, .claude/agents/, .claude/commands/, .claude/skills/, MCP definitions, hooks — inside the project repo. Every engineer who clones gets the same starting point. Updates ship as PRs. The downside: personal preferences (verbose vs terse, preferred model, custom keybindings) have to live elsewhere, usually ~/.claude/CLAUDE.md and ~/.claude/settings.json. The upside: the team's working memory is versioned, reviewable, and survives turnover.

A distributed setup leans on ~/.claude/ for everything. Engineers carry their own agents and skills from project to project. This works for solo consultants and very small teams (under five), but it does not scale. New hires inherit nothing. A fix one engineer discovers does not propagate. You end up with N copies of the same broken sub-agent.

For any team above five engineers, the answer is centralized for project knowledge, distributed for personal taste. Repo-level .claude/ is the source of truth for how this codebase wants to be worked on. User-level ~/.claude/ holds preferences. The harness merges them at runtime, with repo settings taking precedence for anything related to the project.

The one wrinkle: secrets. MCP servers and hooks that need API keys must read from .env.local or the engineer's keychain, never from a committed file. We will come back to this in the permissions section.

Shared CLAUDE.md strategy

CLAUDE.md is the most leveraged file in the repo. It is the system prompt every agent loads before doing anything. Get it right and every engineer's Claude Code session starts smart. Get it wrong and you are paying Opus rates to re-explain your stack every morning.

The pattern that holds up at scale is project root + per-package overrides. The root CLAUDE.md covers:

• Stack: language versions, framework, build tool, package manager (exact commands, not "we use npm")
• Repository layout: the top two levels, with one-line descriptions per directory
• Conventions: naming, file placement, where tests live, what gets committed vs ignored
• Workflow: how to run dev, how to run tests, how to lint, how to ship
• Non-negotiables: things that have burned the team before ("never edit generated/", "always run typecheck before commit")
• Pointers: links to the agent registry, the MCP catalog, the runbook

That is it. Two to three hundred lines, max. If it grows past that, it stops being read.

In a monorepo, each package gets its own CLAUDE.md with the package-specific delta only — the deeper conventions, the tricky modules, the gotchas. Claude Code loads them additively as the working directory changes, so an engineer working in packages/api/ gets the root rules plus the API rules, without the marketing-site noise.

Two failure modes to avoid. First: dumping every architecture decision into the root file. ADRs go in docs/decisions/ and get linked. Second: letting the file rot. Assign an owner (usually the tech lead) and review it quarterly. A stale CLAUDE.md is worse than no CLAUDE.md — it gives wrong answers with confidence.

Shared sub-agent + skill registry

Sub-agents and skills are where the real productivity gains live, and where the most chaos accumulates if nobody curates them. By month three of a team rollout, you will have a code-reviewer, a test-writer, a migration-runner, a security-auditor, and probably four variants of each in different engineers' personal directories.

The fix is a single, repo-committed registry under .claude/agents/ and .claude/skills/, treated like any other production code: PR-reviewed, versioned, with an owner. Each agent file is a markdown file with a scope (which directories it owns), a model tier (Haiku for grep-tier work, Sonnet for the middle, Opus for architecture), and a clear handoff protocol. Each skill is a focused knowledge pack with concrete examples, not a generic prompt.

For a 20-person team, ten to fifteen well-curated agents beats fifty mediocre ones. The agents we ship most often:

• A reviewer agent scoped to the diff, with the team's actual review checklist
• A test-author agent that knows the test framework and the team's coverage conventions
• A migration agent that knows the DB tool and the staging-first rule
• A docs agent that updates README.md, the changelog, and the relevant runbook in one pass
• A debugger agent for log triage with access to the observability MCP

The sync pattern is simpler than it sounds. The agents live in the main repo. Engineers do not edit them directly during a session — if they want to improve one, they open a PR. To pull updates, they git pull. There is no second source of truth, no symlink farm, no scripts that copy files between ~/.claude/ and the repo. The harness reads from the repo's .claude/ directly.

For agents and skills that should be shared across multiple repos (a company-wide style guide, a shared incident-response runbook), publish them as a small internal package or a git submodule. Avoid manual copy-paste — it diverges within a week.

Shared MCP catalog

Model Context Protocol servers are the bridge between Claude Code and your actual systems: GitHub, Linear, Postgres, Sentry, your internal API. They are also the single biggest source of "why does this work for Alice and not for Bob" in a team rollout.

The fix is a shared MCP catalog committed to the repo, with three tiers:

1. Required servers (everyone needs these): GitHub, the project's database, the team's issue tracker. Wired in .mcp.json at the repo root, with config that reads tokens from env vars, never from committed files.
2. Optional servers (use if relevant): Sentry, PostHog, Stripe, internal APIs. Documented in the catalog with one-paragraph descriptions and the env vars they need.
3. Personal servers (engineer's choice): their note-taking app, their calendar, their personal Notion. Lives in ~/.claude/ and never touches the repo.

The catalog is a markdown file — .claude/MCP_CATALOG.md — listing every approved server, what it does, how to authenticate, and which env vars to set. New servers go through a quick review: who owns it, what data does it touch, what scopes does the token need. Unreviewed MCP servers are not banned, but they are not loaded by default either.

One pattern that has saved us repeatedly: a read-only by default policy for shared MCP servers. The GitHub server lets engineers query issues and PRs without authentication ceremony. Anything that writes — opening a PR, creating an issue, merging — either requires explicit confirmation or is gated behind a separate higher-trust server. Same for the database server: read replica access for everyone, write access only via a dedicated migration agent with logging.

Permissions + secret handling

The two questions that decide whether your Claude Code rollout survives quarter two: what can it run without asking, and where do the secrets live.

For permissions, the working model is a layered allowlist in .claude/settings.json at the repo level, with personal overrides in ~/.claude/settings.local.json. The repo file pre-approves the obvious safe commands — git status, git diff, npm test, pnpm typecheck, rg, ls, cat on non-secret paths — so engineers do not get prompt fatigue on every benign tool call. Anything that mutates state outside the working tree — git push, gh pr merge, vercel deploy, raw psql against production — stays prompt-on.

The trap to avoid is wildcards. Bash(*) ends your security model. Be specific: Bash(npm run *), Bash(git status), Bash(rg *). Yes, it is more lines. Those lines are the difference between an agent that runs the test suite and an agent that runs rm -rf node_modules because it misread an instruction.

For secrets, the rule is: never in the repo, never in CLAUDE.md, never in chat. Tokens live in .env.local (gitignored) and the engineer's keychain. MCP server configs reference env vars, not values. Hooks that need credentials read from the same place. Anything that gets logged — and Claude Code logs more than people realise — has secrets scrubbed before write. If you cannot rotate a credential without paging an engineer, it is in the wrong place.

For sensitive repos, add a pre-commit hook that scans staged files for likely secrets and blocks the commit. gitleaks, trufflehog, or a small custom regex pass all work. The hook lives in the repo, runs locally, and catches the obvious mistakes before they reach origin.

Cost dashboards + budgets

Claude Code costs vary by an order of magnitude across engineers doing the same job. The difference is almost always model choice and context discipline, not skill. Without visibility, you find out at month-end.

The minimum viable dashboard tracks four things per engineer (or per team, if your privacy stance prefers that): total spend this month, cost per session, model mix (% Haiku / Sonnet / Opus), and cache hit rate. Anthropic's console gives you the first three. Cache hit rate you compute from the API metadata — and it is the single most important number, because a team running at 70% cache hits pays roughly a third of a team running at 20%.

Set per-engineer monthly soft budgets and a team hard budget. Soft budgets ping the engineer; hard budgets ping the lead. The numbers depend on stack and seniority — a backend engineer doing heavy refactor work will legitimately spend 3-5x what a frontend engineer doing component work spends. Calibrate over the first month, then commit.

The behaviours that move cost down without hurting output: route grep-tier work to Haiku, default to Sonnet for the middle, reserve Opus for genuinely hard architecture and review. Use prompt caching aggressively — system prompts, large file contexts, repeated tool descriptions all cache. Compact long sessions instead of letting context bloat. Kill stale sub-agents. Most teams cut their bill in half within two weeks of looking at these numbers honestly.

Onboarding new engineers fast

The goal is: a new hire opens the repo on day one, runs through a checklist, and ships a real PR with Claude Code before lunch on day two. Anything slower means the tool gets framed as optional, and within a quarter half the team is not using it.

The onboarding checklist that consistently works:

1. Install: npm install -g @anthropic-ai/claude-code, confirm version
2. Authenticate: log in via the Anthropic console or set ANTHROPIC_API_KEY from the team password manager
3. Clone the repo and cd in — the harness picks up .claude/ automatically
4. Run claude and ask it to summarise the project — sanity check that CLAUDE.md loaded
5. Walk through .claude/MCP_CATALOG.md and wire the required MCP servers (GitHub token, DB read-only credential)
6. Run a guided dry-run task: ask Claude Code to add a unit test to a designated easy file, review the diff, do not merge
7. Pair on a real ticket with an existing team member for 30 minutes
8. Ship a small PR solo with Claude Code

The whole flow is two to four hours. The dry-run task matters — it gives the new hire safe practice on a real codebase before they touch anything that ships. Pick a file the team agrees is "always fine to add tests to" and keep the prompt in the onboarding doc.

If you want this on rails, hire an AI agent development partner to run the rollout, deliver the agent and skill registry, and train the team. That is most of what we do.

Team rituals

Tooling without rituals decays. The teams that keep getting better at Claude Code have two recurring practices baked into the calendar.

Friday demo, 30 minutes. Two or three engineers each show one prompt, agent, or workflow that worked this week. Not polished — actual session recordings or screenshots. The point is propagation: the trick someone discovered on Tuesday becomes the team's default by next Monday. Keep a WINS.md in the repo with the headline of each demo. Within a quarter it becomes a powerful onboarding doc on its own.

Prompt review, biweekly, 45 minutes. Pick three recent Claude Code sessions — one that went great, one that went poorly, one that was mid. Walk through the prompts, the context, the tool calls, the cost. What made the good one good? What blew up the bad one? Updates to CLAUDE.md, the agent registry, or the MCP catalog get opened as PRs during the meeting. This ritual is where most of the durable improvements come from.

A lighter third option: a #claude-wins channel in Slack where engineers post one-line "this saved me an hour" notes. Low friction, high signal, surfaces the underused parts of the setup.

Common failure modes

The four ways team rollouts go sideways, in rough order of frequency:

Drift. Personal ~/.claude/ configs diverge from the repo. Six months in, no two engineers have the same setup, and the team's collective improvements are scattered across laptops. Fix: enforce repo-level .claude/ as source of truth, review the user-level files quarterly.

Permission fatigue. The allowlist is too tight, every action requires a prompt, engineers turn off confirmation entirely and now nothing is safe. Fix: tier the allowlist properly — generous on reads, strict on writes, explicit on production.

Cost surprise. Nobody watches the dashboard, an engineer leaves a runaway agent loop running over a weekend, the bill is 4x normal. Fix: hard budget alerts at the team level, not just soft per-engineer pings. Also: a kill switch the lead can pull without paging Anthropic.

Tool sprawl. Every engineer wires their own MCP server for their pet workflow, the catalog balloons to forty entries, half are unmaintained, security review never happens. Fix: a curation owner and a quarterly cull.

A fifth, quieter one: prompt monoculture. Everyone ends up using the same five prompts, the team stops exploring. Counter-pressure with the Friday demo. Variety is the engine of finding the next 10x prompt.

Closing CTA

Setting up Claude Code for a team is mostly about owning three artifacts — the shared CLAUDE.md, the agent and skill registry, the MCP catalog — and running two rituals that keep them alive. Get those right and a 20-engineer team consistently ships 30-50% faster than the same team did a year earlier, with fewer regressions and far less context-switching pain.

If you want a faster path than building this from scratch, AY Automate deploys a vetted starter pack — agents, skills, MCP catalog, hooks, onboarding doc — tuned to your stack, then runs the first two onboarding cohorts with your engineers. Most teams are productive inside two weeks. Read the Claude Code enterprise implementation guide for the broader rollout picture, the Claude Code best practices post for the per-engineer working habits, and book a consultation when you want to map your team's setup.

FAQ

Should every engineer use the same Claude Code config?

For project-level config — CLAUDE.md, agents, skills, MCP catalog — yes. That lives in the repo and is the same for everyone. For personal preferences — model defaults, verbosity, keybindings — no. Those live in ~/.claude/ and engineers tune them to taste. The harness merges both at runtime, with repo settings winning for anything project-specific.

Do we need a paid Anthropic plan to use Claude Code on a team?

You need API access for every engineer. Most teams use Anthropic's standard API with per-engineer keys provisioned through the console, billed centrally. Some teams route through AWS Bedrock or Google Vertex for compliance reasons — Claude Code supports both. For 10-50 engineers, the standard API is simpler and usually cheaper unless you have a specific procurement constraint.

How do we stop an engineer from accidentally running destructive commands?

Tier your .claude/settings.json allowlist. Pre-approve safe reads (git status, npm test, rg), prompt on writes (git push, gh pr merge), block production access entirely unless behind a dedicated agent with logging. Never use Bash(*). Add a pre-commit hook that scans for secrets. The combination catches 95% of mistakes before they ship.

What is the right model mix for a team?

For most engineering teams: roughly 60% Sonnet, 25% Haiku, 15% Opus. Haiku handles grep-tier search and small edits, Sonnet handles the bulk of feature work, Opus is reserved for architecture, hard debugging, and code review on large diffs. Teams that flip to Opus-default see costs 3-5x higher with marginal quality lift. Track the mix in your dashboard and recalibrate quarterly.

How do we share sub-agents across multiple repos?

Two options. For agents tightly coupled to a single repo, keep them in that repo's .claude/agents/. For agents that should be company-wide — a shared style reviewer, an incident-response agent — publish them as a small internal npm package or a git submodule that each repo pulls into its .claude/ directory. Avoid manual copy-paste; it diverges within a week and you lose the propagation benefit entirely.

How long does a team rollout take?

For a 10-20 engineer team with no prior Claude Code usage: two to four weeks to ship the repo config, the agent registry, the MCP catalog, and onboard everyone. Add another month before the rituals (Friday demo, prompt review) are running smoothly and the team is at steady-state productivity. Teams that try to do it in a week ship a config that needs a rebuild by month three.

Can Claude Code work offline or in air-gapped environments?

Not natively — the model calls go to Anthropic's API. For air-gapped or strict data-residency environments, route through AWS Bedrock or Google Vertex inside your VPC, which keeps inference traffic within your cloud perimeter. Self-hosted inference of Anthropic models is not currently supported. If your security team requires fully on-prem, you are looking at a different tool, not a different Claude Code config.

Should we let engineers wire their own MCP servers?

For personal productivity servers (notes, calendar, personal Notion) — yes, in ~/.claude/. For anything that touches company data or company systems — no, those go through the catalog with a short review. The review takes ten minutes and prevents the slow drift toward a security audit you cannot pass. Make the catalog easy to extend, not closed.