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.
What CLAUDE.md actually does
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 five sections a team CLAUDE.md needs
1. Who owns what
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.
2. How decisions escalate
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."
3. The exact commands
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.
4. What "good" means here
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:)
5. The tools and systems
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.
Per-role profiles: when one file is not enough
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.
Four mistakes that make it stop working
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.
A faster way to write the first version
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 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 with your own Anthropic API key, 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.
