A good team CLAUDE.md is short, specific and shared through version control. Put the standards everyone must follow in the team-level file, keep personal preferences in your own file, add directory-specific notes only where a folder really differs, and use path-specific rules for conventions that apply to certain kinds of files. Write instructions Claude Code can act on, not general advice, and review the file like any other code.
What a CLAUDE.md is for
Claude Code starts each session without memory of the last one. CLAUDE.md is how you give it standing instructions so each engineer does not repeat them in every prompt. If you are new to the tool, start with what Claude Code is and who it is for. This article covers the next step: making the file useful for a whole team.
Where each kind of instruction belongs
Claude Code reads instructions from several places, and choosing the right place is most of the skill. The levels below follow the hierarchy in the CCAR-F cheat sheet.
| Location | Use it for |
|---|---|
~/.claude/CLAUDE.md | Your personal preferences. Not in version control, so teammates never see it. |
.claude/CLAUDE.md (or a project-root CLAUDE.md) | Team-wide standards, shared through version control. |
CLAUDE.md in a subdirectory | Conventions that apply to that directory only. |
.claude/rules/ with YAML paths: | Rules loaded conditionally by file glob. |
A common mistake is putting everything in one file. Team standards mixed with one person's habits confuse everyone, and a rule meant for a single folder adds noise everywhere else.
What to put in the team file
- How to build, test and lint. The exact commands a new engineer would need on day one.
- Project layout. A few lines on where the main parts live, so it does not have to guess.
- Conventions that are not obvious from the code. Naming, error handling, how dependencies are added.
- Things to avoid. Files it should not edit, commands it should not run, areas that need a human's approval.
- What "done" means. For example, tests pass and the change is described in the pull request.
Leave out anything Claude Code can read from the code itself, long explanations of why the company exists, and anything that goes out of date quickly. Never put passwords, keys or customer data in the file, because it is shared with the whole repository.
Example rules: vague versus usable
Compare these pairs. The second version in each pair gives Claude Code something it can follow and you can check.
- Vague: "Write clean code." Usable: "Run the project's lint command before finishing and fix every warning in files you changed."
- Vague: "Be careful with the database." Usable: "Never edit existing migration files; add a new migration instead."
- Vague: "Test your work." Usable: "Run the unit tests for the package you changed and report any failures."
- Vague: "Follow our style." Usable: "Name new service classes with the Service suffix and place them in the services folder."
These are illustrations of the style, not rules for your project. Replace them with your own commands and conventions.
Keep it short and keep it true
A short, accurate file usually helps more than a long, vague one. Long files bury the rules that matter, and outdated instructions are worse than none because Claude Code will follow them confidently. A practical routine:
- Start with five to ten rules that fix problems you have actually seen.
- When Claude Code repeats a mistake, add or sharpen one rule.
- When a rule no longer applies, delete it.
- Review changes to the file in pull requests, the same as code.
- Name one person who owns it, so it does not decay.
When to use path-specific rules
Some conventions only apply to certain files, such as test files, database migrations or front-end components. Instead of adding them to the main file, place them in .claude/rules/ with a paths: glob in the YAML header so they load only when Claude Code works on matching files. This keeps the main file small and the guidance relevant at the moment it is needed. Directory-level CLAUDE.md files serve a similar purpose when a whole folder follows its own conventions.
Rules guide behaviour; they are not a security control
CLAUDE.md shapes what Claude Code tends to do. It does not replace review, permissions or access control. Keep humans responsible for what gets merged, limit what commands it may run, and check your company's AI usage rules before pointing it at sensitive code. See what a company AI usage policy should include.
Learning this properly
The CLAUDE.md hierarchy and path-specific rules are tested in the Claude Code domain of the Claude Certified Architect exam. See the Claude Code domain study notes and the CCAR-F workshop. Agmo Studio is a Select Partner of the Anthropic Claude Partner Network; certifications are issued by Anthropic, and Agmo runs exam-preparation workshops.