How to set up Claude Code for your whole team (not just your own laptop)

A developer's guide explains how teams can standardize Claude Code behavior by checking a shared CLAUDE.md file into the repository, covering ownership tables, escalation rules, exact build/test/lint commands, and quantified standards like 80% test coverage and p95 latency under 300 ms. The writeup recommends keeping shared rules short and splitting role-specific defaults into per-role profile files, warning that the file degrades once it grows past a few screens.

Most developers who try Claude Code start the same way: open a repo, ask for a change, and get something that is almost right. The code compiles, but it uses the wrong logging library, skips the test convention your team agreed on, and opens a PR against the wrong branch. The model is not the problem. Context is. Claude Code knows nothing about your team unless you write it down, and the place you write it down is a file called CLAUDE.md . This guide covers what goes in that file when a team shares it, not just one person, and the mistakes that make it stop working after a month. Claude Code reads CLAUDE.md automatically at the start of every session. You do not paste it, reference it, or remind the agent. If the file is in your project root, it is in context. There are three places it can live: | Location | Scope | Who edits it | |---|---|---| | ~/.claude/CLAUDE.md | Every project on your machine | You only | | <repo /CLAUDE.md | Everyone working in this repo | The team, via PR | | <repo /<folder /CLAUDE.md | Work inside that folder | The team that owns the folder | For a team, the repo-level file is the one that matters. It is checked in, reviewed like code, and every developer's agent reads the same rules. If you have never made one, run /init inside Claude Code. It scans the repo and writes a starter file. That starter covers the code. It does not cover the team, and that is the part you need to add. The agent cannot ask "who reviews payments code?" unless the answer is in the file. Ownership | Area | Owner | Reviews required | |---|---|---| | payments/ | Payments team | 2, one from payments | | api/ | Platform team | 1 | | web/ | Frontend team | 1 | This alone stops a whole class of bad suggestions, like refactoring a module across a team boundary in one PR. Write down what the agent should do when a task crosses a line: stop and ask, open an issue, or proceed. Escalation - Schema changes: never apply directly. Write the migration, open a PR, tag the platform team. - Anything touching billing: stop and ask before writing code. - Dependency upgrades: allowed for patch versions only. Short imperatives work better than prose. The agent follows "never apply directly" far more reliably than "we generally prefer that schema changes go through review." List the build, test, and lint commands character for character. If you do not, the agent invents plausible ones, and plausible is not the same as correct. Commands - Install: pnpm install - Test one package: pnpm --filter <pkg test - Lint: pnpm lint must pass before any commit - Never run: pnpm db:reset wipes the shared dev database That last line has saved more than one team a bad afternoon. Every team has standards that are obvious to them and invisible to an outsider. Write the number down. Standards - Test coverage on new code: 80% minimum - API responses: p95 under 300 ms - No new any types in TypeScript - Commit messages: Conventional Commits feat:, fix:, chore: Which issue tracker, which CI, where logs live, which environments exist. The agent will reference these when it explains what to do next, so they should be real. A single CLAUDE.md works until your team has people who need different defaults. A tech lead wants the agent to flag architectural risk. A new joiner wants it to explain conventions. A PM wants it to stay out of the code entirely. A pattern that works well: keep the shared rules in CLAUDE.md , and add a short profile per role that someone loads when they start a session. profiles/ tech-lead/profile.md backend-engineer/profile.md product-manager/profile.md Each profile covers how that role thinks, what they prioritize, and what they never compromise on. The shared file stays short. The profiles carry the difference. It grows until nobody reads it. Past a few screens, the important rules get lost among the trivia. If a section only matters for one folder, move it into that folder's CLAUDE.md . It describes, instead of instructing. "Our team values clean code" changes nothing. "Functions over 40 lines need a comment explaining why" does. It drifts from reality. The file says the tests run with Jest. The repo moved to Vitest in March. Now the agent is confidently wrong. Review the file when you review the code it describes. It is written once by one person. The best CLAUDE.md files are edited by everyone who catches the agent getting something wrong. Treat a bad agent suggestion as a bug report against the file. Most of what goes into a team CLAUDE.md already exists somewhere: an onboarding doc, an engineering handbook, a Notion page about who owns what. The slow part is turning that prose into short, enforceable rules. That is the problem we built AI Workspace Builder https://aiworkspacebuilder.ai to solve. You upload the docs your team already has PDFs, markdown, Word files, or a Notion page , and it pulls out roles, processes, metrics, tools, and escalation paths, then generates the CLAUDE.md , a profile per role, and team-level files. It takes 15 to 30 seconds, and the free tier gives you one trial workspace with no card required. Whether you use it or write the file by hand, the principle is the same: the agent is only as good as what you tell it about your team. Write it down once, keep it short, and keep it true. What is the one rule in your CLAUDE.md that made the biggest difference? Drop it in the comments.