Most CLAUDE.md examples online are written for one person working on one side project. A team file has a different job: every developer's Claude Code session reads the same file, so it has to encode how the team works, not how one person likes to work.
Below is a template you can copy into the root of a shared repo. Replace everything in <angle brackets>, delete what doesn't apply, and keep it short. Notes on each section follow.
Prefer to start from a questionnaire instead of a blank file? This two-minute video fills one in for a sample project and saves the result as a starter CLAUDE.md:
The template
# <Project name>
<One sentence: what this repo is and who uses it.>
## Commands
- Install: `<command>`
- Run locally: `<command>`
- Test (all): `<command>`
- Test (one file): `<command> <path>`
- Lint and format: `<command>` (must pass before any commit)
- Never run: `<command>` (<why: e.g. resets the shared dev database>)
## Layout
- `<folder>/`: <what lives here>
- `<folder>/`: <what lives here>
- Reference implementation for new <services/components/endpoints>: `<path>`
## Ownership
| Area | Owner | Reviews required |
|---|---|---|
| `<folder>/` | <team> | <n>, at least one from <team> |
| `<folder>/` | <team> | <n> |
## Rules
- Follow the pattern in `<reference path>` for new <things>. Do not invent a new structure.
- <Database> schema changes: write the migration and open a PR. Never apply it directly.
- Anything touching <billing/auth/data deletion>: stop and ask before writing code.
- Dependencies: patch upgrades are fine. Minor or major upgrades need a separate PR.
- If you can't verify something (a command, an API, a config value), say "I haven't verified this" and stop.
## Standards
- Test coverage on new code: <n>% minimum
- <Language>-specific: <e.g. no `any` in TypeScript, type hints on all public functions>
- Commit messages: <convention, e.g. Conventional Commits>
- PR size: under <n> lines changed where possible
## Glossary
- **<Term>**: <what it means here>. Not "<banned synonym>".
- **<Term>**: <what it means here>.
## Definition of done
- Tests pass locally and the linter is clean
- The change follows the reference implementation
- The PR description explains what changed and why, in plain language
That's the whole file. If yours is much longer, read on.
What each section is for
Commands
This is the section that pays off fastest. Without it, Claude Code guesses the commands, and a plausible guess (npm test in a pnpm monorepo, pytest without the right flags) wastes time on every task.
The "Never run" line matters more than it looks. One destructive command that's easy to type, like a database reset or a deploy script, is worth naming explicitly.
Layout and the reference implementation
Don't describe the whole folder tree. The agent can read it. Name the folders whose purpose isn't obvious, and point to one existing file that shows the right way to do things.
"New endpoints follow the structure of api/orders/" gets better results than a page describing your architecture. Models copy examples far more reliably than they follow descriptions.
Ownership
In a team repo, the most expensive agent mistake is a change that crosses team boundaries: a refactor that touches three teams' code in one PR. An ownership table lets the agent notice the boundary and split the work, or ask first.
Rules
Write rules as short imperatives. "Never apply schema changes directly" is followed. "We generally prefer that schema changes go through review" is not.
Keep the list to the rules that are actually broken. A rule nobody would break anyway is noise that dilutes the ones that matter.
Standards
Numbers beat adjectives. "Clean, well-tested code" changes nothing. "80% coverage on new code" and "no any types" can be checked, by the agent and by your reviewer.
Glossary
This is the section most teams skip and most need. When the agent invents its own names for your domain concepts (a "customer" becomes an "account holder" in one file and a "client" in another), the codebase slowly fills with inconsistent vocabulary. A short glossary, including the synonyms you don't want, stops that.
Definition of done
Tell the agent what it has to check before it says it's finished. This turns "done" from a claim into something it verifies: tests ran, the linter passed, the change matches the reference.
What to leave out
-
Things the code already says. The agent can read your
package.jsonand folder structure. -
Personal preferences. Tone, verbosity, editor habits: those belong in each developer's own
~/.claude/CLAUDE.md, not the shared file. -
Rules for one folder. Put them in a
CLAUDE.mdinside that folder. Claude Code picks it up when working there, and the root file stays readable. - Long prose. If a section needs paragraphs, it's documentation. Link to it instead of pasting it.
Keeping it true
A team CLAUDE.md fails quietly: it says one thing, the codebase moved on, and the agent confidently follows the old rule. Two habits prevent that:
- Review it like code. Changes go through PRs, and any PR that changes a convention updates the file in the same PR.
- Treat a bad agent suggestion as a bug report against the file. If the agent got something wrong because the rule was missing or stale, fix the file, not just the code.
Starting from your team's docs instead
Most of what goes into this template already exists somewhere in your team's documents: the onboarding guide, the engineering handbook, the page about who owns what. Turning that prose into short rules is the slow part.
That's what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and team-level files in 15 to 30 seconds, using your own Anthropic API key. There's a free trial workspace, no card required.
Either way, start small: commands, one reference implementation, and the three rules your team breaks most often. That alone changes how Claude Code behaves in your repo.
Top comments (2)
I'd pay more attention to the agreement part, since a solo file only has to be true and a shared one has to be agreed. This copying goes wrong where people port the contents and not the habit of arguing about them. Which section do you expect to change most as teams adapt it?
Good point, and I think you're right that the habit matters more than the contents. My guess for what changes most: Rules and Definition of done. Commands and Layout are facts, so they're either right or wrong. Rules and Definition of done are agreements, which is where teams argue, and where a copied version is most likely to say something nobody on the team actually believes. If I had to suggest one practice, it's reviewing changes to those two sections like code, with the people who'll be held to them.