On this page
TLDR
CLAUDE.md gives Claude Code persistent instructions. Multiple applicable files contribute context; conflicting instructions do not have a guaranteed winner.
What you are deciding
Team configuration has two layers with different guarantees: CLAUDE.md files carry instructions that Claude reads as context, and settings files carry enforced configuration. Put each rule in the layer that matches how firmly it must hold.
Where does each team rule belong: shared instructions, a personal preference, a project setting or a managed control?
What it is
CLAUDE.md is a configuration file for Claude Code that defines project rules, conventions, and architectural decisions. It's not a .gitignore or a README, it's a working set of instructions that Claude reads every time it edits code or runs a command. CLAUDE.md gives Claude Code persistent instructions, and multiple applicable files contribute context; conflicting instructions do not have a guaranteed winner. Scopes include managed (organization guidance), user (~/.claude/CLAUDE.md, your personal preferences), project (.claude/CLAUDE.md or root CLAUDE.md, shared rules), nested directory files, and path-scoped rules (.claude/rules/*.md with glob frontmatter, rules for specific files).
The content is free-form Markdown but structured: stack info, test commands, code-style rules, key architectural decisions, gotchas, and @import directives that pull in modular rule files. Claude parses it as plain text, there's no schema validation, so mistakes in naming or structure cause silent ignores. The real power is reusability: rules travel with the code (version-controlled in .claude/), every teammate sees them on git clone, and new team members onboard faster.
Path-specific rules use YAML frontmatter with a paths glob array. When Claude edits a file matching the glob (e.g. **/*.test.tsx), that rule file auto-loads alongside the project CLAUDE.md. This enables scoped rule enforcement without drowning the main CLAUDE.md in per-file details. A testing rule file specifies pytest/Jest conventions, coverage thresholds, naming, all loaded only when you touch a test file.
Production misuse centers on scope creep (main CLAUDE.md becomes 500 lines of every possible rule) and scope traps (team expects user rules to apply but they don't: user rules are personal, project rules are shared). A contributor clones the repo, uses their personal style from ~/.claude/CLAUDE.md, and produces inconsistent code. The fix is always: put team rules in `.claude/CLAUDE.md`, never in user files.
How each certification frames it
CCA-P: How CCA-P tests team configuration
CCARP-D7-O1Configure Claude tools and environments for teams (e.g., Claude Code)
The Professional guide lists configuring Claude tools and environments for teams, with Claude Code as the example (PDF page 6, Domain 7). Expect scenarios where two developers behave differently and you must find which layer holds the difference.
Anthropic's Claude Code documentation describes CLAUDE.md scopes (managed policy, project, user and local) and settings scopes, and says Claude treats memory files as context, not enforced configuration. A rule that must always hold belongs in settings or a managed control, not only in prose.
How it works
When Claude Code starts, it loads the applicable CLAUDE.md files: user ~/.claude/CLAUDE.md (personal preferences), the project .claude/CLAUDE.md or root CLAUDE.md (shared), and nested directory files when Claude works in those directories. While editing a file, it also checks .claude/rules/*.md files, tests the paths glob against the filename, and loads matches. The loaded content is added to Claude's context. The result is a set of scoped instructions that contribute together; conflicting instructions do not have a guaranteed winner, so keep them consistent.
When a CLAUDE.md file contains an @import line such as @import ./subdir/rules/testing.md, Claude resolves the import and inlines that file's content. This prevents the main CLAUDE.md from exploding; rules live in modular files and compose via import. Keep the import graph simple and acyclic so each rule has one clear home.
Path-specific rules are scoped via glob frontmatter. A testing rule file declares paths: ["**/*.test.tsx", "**/*.spec.ts"]. When you create or edit a file matching either glob, the rule auto-loads. Token-efficient: irrelevant rules don't load, keeping context focused. A migration rule (paths: ["migrations/*.sql"]) only loads when you touch SQL files.
Claude reads CLAUDE.md once at startup, not continuously. Changes take effect in a new session. This is a UX tradeoff: rules are stable within a session (no surprise mid-conversation changes), but editing CLAUDE.md does not take effect immediately. Plan edits before sessions, not during.
Worked example: two developers, two behaviours
Authored teaching example, not a bank question.
On one repository, Dana's Claude Code runs the unit tests before each commit and never reads .env files. Sam's does neither.
| Rule | Layer | Shared with | Enforced? |
|---|---|---|---|
| Run unit tests before commit | Project CLAUDE.md | Everyone who clones | No, it is guidance |
| Never read .env files | Project .claude/settings.json deny rules | Everyone who clones | Yes, as a permission rule |
| Personal editor habits | User or local files | Only you | Not applicable |
| Rule no one may override | Managed settings | The organization | Yes, highest precedence |
Both developers now get the same behaviour from files that live in the repository. Check afterwards that no team rule exists only in one person's local files.
How this decision goes wrong
Instructions mistaken for enforcement
Looks right: CLAUDE.md says never to read .env, so the file is protected.
Why it fails: Claude Code's documentation treats CLAUDE.md as context, not enforced configuration. The model may weigh it differently in a given case.
Instead: Express must-hold rules as permission deny rules, hooks or managed settings, and keep CLAUDE.md for conventions.
A team policy kept in local files
Looks right: The policy works on the author's machine, so the team has it.
Why it fails: User and project local settings stay on one machine, and the local file is not in the clone. Only committed project files reach teammates.
Instead: Commit shared rules to the repository files, and keep personal exceptions in the local file.
Conflicting configuration left unresolved
Looks right: Both the project and the local file set the key, and somehow it works.
Why it fails: The higher level silently overrides the lower one, so behaviour differs between people and nobody knows why.
Instead: Decide which level owns the key, remove the duplicate, and confirm with /status after a restart.
Where you'll see it
Open-source repo onboarding
New contributor clones the repo. Project CLAUDE.md auto-loads: stack, test commands, code-style rules, key decisions. Saves a 30-min onboarding email per contributor. Rules travel with the code; nobody works from outdated docs.
Monorepo with subteam directories
Frontend team has rules in app/.claude/CLAUDE.md (component patterns, testing conventions); backend has api/.claude/CLAUDE.md (db migration discipline, error handling). Root CLAUDE.md holds shared rules. Editing inside app/ loads frontend rules; inside api/ loads backend rules.
Show 1 more examples
Personal vault across many projects
Solo dev keeps personal preferences in ~/.claude/CLAUDE.md (preferred indent, commit message format). Each project repo has its own root CLAUDE.md with stack details. Switching projects: project rules change automatically; personal style stays consistent.
Code examples
# Project: PrecisionCare Navigator
## Stack
- Python 3.11 + FastAPI + Postgres
- React 19 + ShadCN + Tailwind
- Claude Opus for medical NER
- AWS ECS + RDS, region us-east-1
## Commands
- Dev: `make dev` (FastAPI :8000, React :3000)
- Test: `pytest -v --cov=app`
- Lint: `ruff check . && black --check .`
- Deploy: `make deploy ENV=staging`
## Code style
- 4-space Python (Black), 2-space React (Prettier)
- Type hints on every function (mypy strict)
- Named exports only
- Server actions for mutations; route handlers for queries
## Key decisions
- All patient data encrypted at rest and in transit
- Never log PII (mask in middleware)
- Async background work via Celery + Redis (not asyncio in FastAPI)
## Modular rules
@import ./rules/testing.md
@import ./rules/healthcare-compliance.md
@import ./rules/api-design.md
## Don't
- Add new endpoints without a corresponding test
- Mock the database in integration tests
- Commit secrets (use .env.example as the template)
Looks right, isn't
Each row pairs a plausible-looking pattern with the failure it actually creates. These are the shapes exam distractors are built from.
Put all team rules in ~/.claude/CLAUDE.md so they live with each developer.
User-level files are personal and not in the repo.
Team rules belong in project-level CLAUDE.md (root, committed). Otherwise new team members miss them.
Document every framework convention exhaustively in CLAUDE.md.
CLAUDE.md is appended to every prompt.
Bloated files burn tokens and dilute attention. Keep it concise (~1500 tokens). Use @import for modular detail; link to long-form docs.
Embed API keys in CLAUDE.md so Claude has them on every session.
CLAUDE.md is committed to git.
Secrets leak. Use environment variables and reference them in CLAUDE.md by name (e.g., 'OPENROUTER_API_KEY required in env').
User CLAUDE.md always overrides project CLAUDE.md when they conflict.
No file has a guaranteed win.
Multiple applicable files contribute context, and conflicting instructions do not have a guaranteed winner. A teammate's personal ~/.claude/CLAUDE.md is not a way to change a team rule, so keep team rules in the project file and keep applicable instructions consistent.
Edit CLAUDE.md mid-session and Claude will pick up the changes immediately.
CLAUDE.md is loaded once at session start.
Mid-session edits are silent no-ops until a new session; this is why teams discover that "my new rule isn't being followed", they edited but didn't restart.
Side-by-side
| Scope | Location | Purpose |
|---|---|---|
| Managed | Organization-managed CLAUDE.md | Organization guidance |
| User | ~/.claude/CLAUDE.md | Personal preferences |
| Project | CLAUDE.md or .claude/CLAUDE.md | Shared project instructions |
| Directory | Nested CLAUDE.md | Local directory context |
| Path-scoped | .claude/rules/*.md | Instructions for matching paths |
Decision tree
Does this rule apply to everyone on the team?
Does the rule apply only to certain file types or directories?
paths: [...]. Loads on demand.Is it a reusable workflow (e.g., PR review process)?
Is the CLAUDE.md exceeding ~1500 tokens?
@import chunks: @import ./rules/testing.md, @import ./rules/security.md. Keeps the always-on context lean and lets you scope detailed rules to topics.Are you running other agentic tools (Codex, Cursor) on the same repo?
AGENTS.md file with cross-tool instructions and have CLAUDE.md include @AGENTS.md at the top. Single source of truth across tools.The exam trap
Team members often miss project rules because the rules live only in user-level CLAUDE.md. Team standards must be project-level and version-controlled; user-level should hold only personal preferences.
Question patterns
CCA-P practice questions
2 approved CCA-P questions for this topic. Tap an answer to check it, then read the rationale for every option.
A 500-developer engineering organization wants to standardize how Claude Code is configured across all teams -- shared coding conventions, shared MCP server connections, and consistent project-level rules -- without forcing every individual developer to manually reconfigure their own environment. What is the most scalable architectural approach?
CCA-F practice questions
2 approved CCA-F questions for this topic. Tap an answer to check it, then read the rationale for every option.
Cross-task context like a vendor matrix path should live in: project Instructions or session messages?
CCD-F practice questions
2 approved CCD-F questions for this topic. Tap an answer to check it, then read the rationale for every option.
A team wants a shared Claude Code workflow (a set of skills, hooks, and an MCP server config) to be reusable by every developer on the team rather than living in one developer's personal .claude/ directory. What is the correct application-design pattern?
Frequently asked
Showing 15 of 15 questions
@import ./rules/testing.md from CLAUDE.md reads ./rules/testing.md. URLs are not supported. Keep the import graph acyclic.paths: array in their frontmatter. Use imports for organization, glob rules for scoped policy.@AGENTS.md import inside CLAUDE.md, or directly if present. Use AGENTS.md for tool-agnostic rules; use CLAUDE.md for Claude-specific patterns (skills, hooks, MCP).settings.local.json is per-developer (your local permissions, env vars). The shared file is .claude/settings.json. Add settings.local.json to .gitignore; otherwise teammates inherit each other's accidental "allow all" permissions.@import ./shared-rules/*.md. Drift management is the #1 reason large orgs adopt the modular import pattern.CLAUDE.md exceeds recommended size) and continues. The model still receives it but with degraded attention to any single rule. The fix is decomposition: move detailed rules to .claude/rules/*.md with path globs, keep the main CLAUDE.md as a high-level index of imports.Sources and next steps
- Claude Certified Architect - Professional Exam Guide v1.0 (July 2026), PDF page 6, section: Domain 7: Developer Productivity & Operational Enablement, detailed objectives. Checked 2026-10-16.
- Settings files and precedence (Claude Code docs), section: Settings files and who they affect; Precedence; Confirm what loaded. Checked 2026-10-16.
- How Claude remembers your project (Claude Code docs), section: CLAUDE.md vs auto memory; CLAUDE.md files. Checked 2026-10-16.
CCA-P exam guide: Domain 7, Developer Productivity & Operational Enablement