A CLAUDE.md template for teams (copy it and adapt)

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.

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.json and 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.md inside 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:

1. Review it like code. Changes go through PRs, and any PR that changes a convention updates the file in the same PR.
2. 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. 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.