Setting Up Claude Code for a Team

One developer using Claude Code well is a productivity story. A whole team using it is a consistency problem. Left alone, each person builds up their own private habits — one has a slick CLAUDE.md, another types the same "run the tests before you commit" reminder into every session, a third never verifies anything and merges code that only typechecks. The agent is the same; the results are all over the map.

The fix is the same one you already use for everything else that has to be consistent across a team: put it in version control. Claude Code reads its configuration from files in your repo, so the behavior you want can be committed, reviewed, and shared like any other code. This post covers what to put in that shared configuration, how to split team rules from personal preferences, the conventions worth agreeing on, and how a new teammate inherits all of it on day one.

Why a shared .claude/ directory beats everyone improvising

Claude Code discovers its project configuration from a .claude/ directory at your repo root, plus a CLAUDE.md file it reads at the start of every session. Both are just files. When they're committed, every clone of the repo gets the same setup automatically — there's nothing to install and nothing to register.

That's the whole argument. When the configuration is improvised per-person, three things go wrong. Behavior drifts: the same task produces different code depending on who ran it. Knowledge stays trapped: the one engineer who figured out the right verification flow can only hand it over by talking. And onboarding is slow: a new hire starts from a blank agent and rediscovers traps the team already mapped.

A committed .claude/ directory turns all three around. The rules are shared by construction, they improve through pull requests, and a fresh clone is a fully configured one. You review a change to how the team's agent behaves the same way you review a change to CI — because that's what it is.

The shared CLAUDE.md

CLAUDE.md is the highest-leverage file to get right first. It's a plain Markdown file Claude Code loads at the start of a session — project memory that rides along with every request in that repo. A CLAUDE.md at the repo root is the shared, checked-in version: commit it so the whole team, and Claude, works from the same rules.

For a team, four things earn their place:

• Commands. The exact install, dev, build, typecheck, lint, and single-test commands. This is what stops the agent from guessing — and guessing is where per-person inconsistency starts.
• Conventions. The decisions already made, stated concretely: where data access lives, how errors are returned, what to validate and where. These are the choices you don't want each session re-deciding.
• Gotchas. The non-obvious traps that cost someone an afternoon the first time — the cross-tenant query that has to be scoped, the env var that leaks into the client bundle. This is exactly the tribal knowledge that otherwise lives in one person's head.
• A short do/don't list. The corrections your reviewers keep typing. If a human keeps leaving the same comment, encode it once.

Keep it short and high-signal — every line sits in the model's context for the entire session, so a tight, accurate file beats a long, comprehensive one. Treat it like code: when a change breaks a rule in it, fix the file in the same pull request. A stale CLAUDE.md is worse than none, because it makes the agent confidently wrong for the whole team at once. (Starting fresh, /init drafts a first version by scanning the codebase — a useful starting point to edit down.)

Shared skills, subagents, and workflows

Beyond CLAUDE.md, Claude Code lets you package repeatable behavior into files that also live in version control:

• Skills are procedures that load into the current conversation when relevant — "before you commit, run these four gates." They live under .claude/skills/, and Claude picks one up automatically when a task matches its description; you can also invoke one explicitly rather than waiting for it to trigger.
• Subagents are separate Claude instances with their own context and tool permissions — an independent reviewer that attacks a diff without being anchored to the reasoning that produced it, or a read-only scout that hunts a specific class of bug. They live under .claude/agents/.
• Orchestrations aren't a separate file type — you compose the pieces above into a repeatable multi-step routine, such as a fan-out of subagents followed by a synthesis step, captured as a skill so an audit runs the same way every time.

The point for a team is that these encode how your team works, not just what your project is. When everyone shares the same review subagent, every change gets the same scrutiny; when the same "definition of done" skill fires for everyone, "done" means the same thing regardless of who typed the prompt. That consistency is impossible when each person keeps their favorite skills in a personal folder — the whole value is that they're shared.

Check the exact directory layout and frontmatter fields against the official Claude Code docs before you write your own, since those are the details worth getting precisely right. If you'd rather start from working examples than a blank file, the open-source claude-code-starter ships a ready-to-commit .claude/ directory — a CLAUDE.md template, a "ship" discipline skill, and an adversarial review subagent — that you can drop into a repo and adapt.

Conventions worth agreeing on

Shared files set the defaults; a few team agreements make them stick.

Verification means running it, not typechecking it. The single most valuable team convention is a shared definition of "done" that requires evidence a change actually works — a response body, a test output, a log line — not a green build. Put that definition in CLAUDE.md (typecheck && lint && test all pass, plus an actual exercise of any runtime surface) and make it a review expectation. A passing build quietly ships broken code; it's the failure mode worth being blunt about with the whole team.

An independent review pass on load-bearing changes. The Claude that wrote a change is anchored to the reasoning that produced it, so its self-review is blind to the fake fix — the check-then-write that isn't actually atomic reads fine to its author. A fresh reviewer subagent, not invested in the code, catches that class of bug. Agree as a team on when to run one: normal changes get it, and anything touching auth, money, or data gets the heavier audit. Don't spend the expensive tools on a one-line tweak — match effort to stakes.

Split shared config from personal preferences. Claude Code separates project-level configuration you commit from personal, machine-local settings you keep out of the repo — a personal permission allowlist or a local model preference belongs in the ignored file, not the shared one. Keep team rules in the committed files so one person's preference never changes everyone else's setup. Check the docs for the exact settings filenames and which one is gitignored by default so you commit the right one.

Onboarding a new teammate

Here's the payoff. When the configuration lives in the repo, onboarding is git clone. A new engineer opens the repo, starts Claude Code, and the agent already knows the build commands, follows the house conventions, and avoids the known traps — because all of that came down with the clone. There's no setup doc to follow.

Point new teammates at the CLAUDE.md and the .claude/ directory on their first day — not as setup, but as reading. It's the most honest onboarding document you have, because it's the one that's actually enforced. A wiki page rots; a CLAUDE.md that's wrong makes the agent misbehave immediately, so the team keeps it true.

The takeaway

Getting a team onto Claude Code isn't about everyone learning better prompts. It's about moving the behavior you want out of individual habits and into committed files: a short, accurate CLAUDE.md, a shared .claude/ directory of skills and subagents, and a couple of conventions — verify by running, review the load-bearing changes — that everyone agrees on. Do that and consistency stops depending on who ran the task, improvements ship through pull requests, and a new hire's first clone is a fully configured one. The agent was always going to be powerful; the shared configuration is what makes it a team's tool instead of a collection of private ones.

Related guides

• Automating Your Workflow With Claude Code Hooks
• Working in Large Codebases With Claude Code
• Using MCP Servers With Claude Code