todo-api has two new teammates: one looks after the routes, the other writes tests. Two weeks later, CLAUDE.md is three times as long: error rules for routes, test naming conventions, the release steps, and a line in capitals saying "NEVER push to main". Everyone adds; nobody dares delete. Claude starts missing important lines, just as lesson 2.1 warned. This lesson is about organising rules when a whole team uses Claude Code.
What's shared, what's personal
The first step is separating the shared from the personal:
- Shared, committed: the project's
CLAUDE.mdand the.claude/rules/folder. These are the project's standards: test commands, conventions, gotchas. Everyone reads them, so only include what's true for everyone. - Personal, not committed:
CLAUDE.local.md(added to.gitignore) for your preferences in this project;~/.claude/CLAUDE.mdand~/.claude/rules/for your preferences everywhere.
Personal rules in ~/.claude/rules/ load before project rules. But as with CLAUDE.md, neither overrides the other: if a personal rule and a project rule disagree, Claude may follow either. The only real fix is keeping them consistent.
Splitting rules by topic
When a CLAUDE.md starts to grow, move parts of it into .claude/rules/, one topic per file, with clear names:
todo-api/
├── CLAUDE.md
└── .claude/
└── rules/
├── testing.md
├── routes.md
└── security.mdClaude Code finds every .md file in this folder, including subfolders, so you can split further into backend/ and frontend/. A rule without a paths field loads at startup, at the same level as .claude/CLAUDE.md. The main gain here is maintainability: each person edits the file for their area, reviews are smaller, and edits collide less.
Rules for one part of the code
The bigger gain comes from path-scoped rules. Add paths frontmatter with glob patterns at the top of the file:
---
paths:
- "src/routes/**/*.js"
---
- Return errors as { error: "..." } with the right status code
- Deletes stay soft: set deletedAt, never remove rowsThis rule only loads when Claude uses its read, write or edit tools on a matching file. While Claude works on tests or the README, it takes no context at all. Some common patterns: **/*.ts for every .ts file, src/**/* for everything under src/, src/**/*.{ts,tsx} for two extensions at once.
Note that paths is the only frontmatter field Claude Code reads in a rule. Add priority: high or owner: team-api and they are ignored without an error. If you want to record who a rule is for, use an HTML comment in the body.
Guidance, procedure or hard rule
Each line in the overgrown file from the start of this lesson actually belongs somewhere different. The docs split every instruction into two kinds:
- Guidance, Claude decides: your prompt,
CLAUDE.md, rules, skills. Claude reads them and usually follows them, but can decide otherwise when a situation doesn't fit. - Enforced by Claude Code: hooks, deny rules in settings, managed settings. Applied every time, whatever Claude decides.
From there, pick a home for each item:
- Shared standards and gotchas →
CLAUDE.md. - Rules for one part of the code →
.claude/rules/withpaths. - Multi-step procedures such as the release steps → a skill at
.claude/skills/<name>/SKILL.md. In every session Claude only sees the skill's name and description, and reads the whole thing when a task calls for it. Level 3 teaches how to write one. - Things that must never happen, such as pushing straight to main → a hook or a deny rule. "NEVER push to main" in capitals in
CLAUDE.mdis still only a reminder, however loudly it's written.
The whole company and other tools
At organisation scale there are two more layers.
Managed CLAUDE.md and managed settings. IT can place one CLAUDE.md on every machine, or use the claudeMd key in the managed settings file. Developers can't exclude it. The docs draw a clear line: settings are for technical enforcement (blocking tools or commands with permissions.deny, turning on the sandbox, environment variables), while CLAUDE.md is for behavioural guidance (coding standards, data handling reminders). To block a command company-wide, use settings, not CLAUDE.md.
In a large monorepo, other teams' CLAUDE.md files in parent folders can end up in your sessions. The claudeMdExcludes setting skips them; put it in .claude/settings.local.json so it only affects your machine.
AGENTS.md. Many teams keep an AGENTS.md for other coding agents. Claude Code reads AGENTS.md when the working folder and the folders above it have no CLAUDE.md or CLAUDE.local.md. If there is a CLAUDE.md, by default Claude reads only that. To keep one source for every tool, add a single line to CLAUDE.md:
@AGENTS.mdKeeping rules correct
Team rules age just like code. A file that was right last month may point at a renamed folder or contradict a rule someone just added. Treat rule files like code: change them through pull requests, get them reviewed, and go over them regularly.
The tool for that review is /doctor prompt-audit. It reads CLAUDE.md, CLAUDE.local.md, AGENTS.md and the rules, skills, commands and subagents under .claude/ and ~/.claude/, then reports instructions written for older models, references to files or commands that no longer exist, and lines that contradict each other. The report comes with proposed edits, and no file changes until you ask it to apply them. To audit just one part, pass a path, for example /doctor prompt-audit .claude/rules.
For the overgrown file at the start, the reorganised result looks like this: a short CLAUDE.md with only the shared commands and gotchas, rules/routes.md for whoever works on routes, rules/testing.md for whoever writes tests, a release skill, and a hook that blocks pushes to main.
That's level 2. Level 3 moves on to slash commands and Agent Skills: turning the procedures you keep repeating into something Claude can run with one command.