Put Team Standards Where the Team Can Actually Get Them

Claude Code loads instructions from CLAUDE.md files. Where you put them determines who gets them and when. Get the level wrong and you either ship inconsistent behavior or drown every edit in irrelevant rules.

The Three Levels

User-level: ~/.claude/CLAUDE.md Lives on one developer’s machine. Not version-controlled. Not shared. Think of it as personal preferences — tab size, verbosity, shortcuts. Nobody else sees it.

Project-level: .claude/CLAUDE.md Lives in the repo root. Version-controlled. Every developer who clones the repo gets it automatically. This is where team coding standards belong — naming conventions, test requirements, commit message format. One file, committed once, applied to everyone on next pull.

Directory-level: subdirectory CLAUDE.md Lives inside a specific directory. Only loads when Claude Code edits files in that directory or its children. Database migration rules in database/CLAUDE.md load when you touch migrations, not when you edit React components.

All active levels load simultaneously. When editing src/api/handler.py, Claude Code sees user-level + project-level + src/api/CLAUDE.md if it exists. They stack — they don’t replace each other.

The Classic Mistake: Team Standards in User-Level

This is the single most common anti-pattern. A senior developer sets up coding standards in ~/.claude/CLAUDE.md. Everything works on their machine. A new hire clones the repo — no standards. Claude Code ignores every convention the team agreed on.

The root cause is obvious once you see it: ~/.claude/ is a home directory. Cloning a git repo does not copy another person’s home directory. If only 5 of 8 developers have manually configured user-level standards, 40% of Claude Code suggestions will violate team conventions. The fix is a one-line move to .claude/CLAUDE.md at the project root.

User-level config is for things that are genuinely personal — your preferred level of explanation detail, your editor habits, your language preferences. Anything the team must follow does not belong here.

The Second Mistake: Everything in One File

A colleague says: “Let’s keep it simple. One root CLAUDE.md, all rules in one place.”

The problem: a single root-level file loads for every file edit. Your React component rules load when editing Python backend code. Your database migration rules load when editing frontend tests. This wastes context tokens and can produce irrelevant suggestions — 25% of suggestions may reference the wrong framework entirely.

Team size is not the deciding factor. A 5-developer project with React, Python, and SQL benefits from scoping just as much as a 50-developer project. The criterion is file type diversity, not headcount.

Correct Scoping in Practice

Standard project: Three types of config → three levels.

Monorepo with multiple services: Root-level for universal standards (shared library conventions). Service-level for service-specific rules.

monorepo/
├── .claude/CLAUDE.md          ← universal shared-lib standards
├── api/CLAUDE.md              ← Python API rules
├── web/CLAUDE.md              ← React frontend rules
└── mobile/CLAUDE.md           ← mobile app rules

When editing shared library code, only universal rules load. When editing api/ code, both universal and API-specific rules load. Claude Code doesn’t selectively apply “sections” within one file — separate files at appropriate levels achieve the scoping.

.claude/rules/ — Modular Alternative

Instead of one monolithic .claude/CLAUDE.md, you can split project-level rules into topic-specific files under .claude/rules/. Each file can use YAML frontmatter with paths globs to control when it loads.

This solves the scoping problem at project level. A rule file with paths: ["tests/**"] loads only when editing test files. A rule file with paths: ["src/api/**"] loads only for backend code. Rules without paths load for all files — same as root CLAUDE.md.

Rules files without paths configuration load for everything. If you put React and Python and database rules in .claude/rules/ without paths, you get the same “everything loads everywhere” problem as a single root CLAUDE.md.

Audit Data: What Misscoped Config Actually Costs

One team’s audit found three distinct problems, each caused by a scope mismatch:

• 40% of suggestions violated standards — Standards were in user-level config. Only 5 of 8 developers had them. Fix: move to project-level.
• 25% of suggestions referenced wrong framework — React rules at root loaded for Python files. Fix: directory-level or paths-scoped rules.
• 15% of test suggestions ignored conventions — Test rules weren’t scoped to test files. Fix: .claude/rules/ with paths: ["tests/**"].

All three fixed by putting each rule at the right scope.

Separately, combining MCP tool configuration (.mcp.json) with CLAUDE.md usage guidelines pushed tool selection accuracy from 65% (tools alone) to 91% (tools + guidelines). CLAUDE.md doesn’t replace tool descriptions — it complements them with contextual guidance that descriptions alone can’t provide.

Things That Don’t Exist

• Conditional comments in CLAUDE.md — You cannot write “if editing Python, apply these rules” inside one file. Scoping comes from file placement and paths globs, not inline conditions.
• MCP server config in CLAUDE.md — .mcp.json is the dedicated mechanism for MCP servers. CLAUDE.md is for instructions. They serve different purposes and different formats.
• Subdirectory .mcp.json — MCP configuration lives at the project root. Directory-scoped MCP servers are not a thing.

One-liner: User-level is personal, project-level is team, directory-level is context — put each rule where it actually needs to be and stop loading database rules for React edits.