Lesson 2.315 min · 5 cards · 8 exercises · 1 mission

Shared rules for the team

Split rules by topic, scope a rule to one part of the code, and pick the right home: CLAUDE.md, a skill, a hook or settings.

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.md and 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.md and ~/.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.md

Claude 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 rows

This 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/ with paths.
  • 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.md is 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.md

Keeping 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.

Practice lesson 2.3

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.