How to Write CLAUDE.md: A Practical Guide for Claude Code Teams

To write an effective CLAUDE.md, put only always-relevant, project-specific instructions in it, keep it short, use concrete examples instead of adjectives, and push everything else into scoped rules files, Skills, or hooks. The file is loaded into every Claude Code session, so its job is to be the shared brief a new engineer would need on day one, not a manual for every workflow the team has ever run.

That distinction is also what the Claude Certified Architect – Foundations exam tests in Domain 3 (Claude Code Configuration & Workflows, 20% of the exam). The questions are scenario-based: a team’s config is misbehaving, and you pick the least-bad fix. This guide covers the mechanics and the judgment calls.

What is CLAUDE.md actually for?

CLAUDE.md is persistent context. Claude Code reads it at session start and treats the content as standing instructions: how the project is laid out, which commands run tests, what conventions the team follows, and which things Claude should never assume.

Two properties follow from that and shape everything else in this post:

• It is always on. Every line is in context for every session, whether the current task needs it or not. There is no “skip this section” mechanism; section headers do not control loading.
• It is guidance, not enforcement. The model reads it and usually complies. It can also decide, in the moment, that a rule does not apply. That is a feature for style advice and a liability for safety rules.

Where do the three levels of CLAUDE.md live?

Claude Code stacks three files. They do not override each other; they combine.

Level	Path	Shared via git?	Use for
User	~/.claude/CLAUDE.md	No	Personal preferences: verbosity, editor habits
Project	CLAUDE.md or .claude/CLAUDE.md at repo root	Yes	Team standards everyone must follow
Directory	CLAUDE.md inside a subdirectory	Yes	Rules that only apply when editing that subtree

The classic mistake is a senior engineer putting team standards in the user-level file. It works on their machine, and a new hire clones the repo and gets nothing, because cloning a repository does not copy someone else’s home directory. If the whole team must follow it, it belongs at project level. The study article on the three-level hierarchy walks through the monorepo variant of this decision, and the Foundations primer covers the configuration hierarchy if you are new to Claude Code.

What belongs in CLAUDE.md, and what should be a rule, Skill, or hook?

Sorting by frequency and consequence is the fastest way to decide.

Content	Mechanism	Why
Conventions used in every session (naming, test command, commit format)	CLAUDE.md	Always relevant, always loaded
Conventions for one file type scattered across the tree (*.test.ts)	.claude/rules/*.md with paths frontmatter	Loads only when a matching file is edited
Conventions for one directory (src/backend/)	Directory-level CLAUDE.md	Scoped by location
A multi-step workflow used weekly (release notes, DB migration)	Skill in .claude/skills/	On-demand, keeps CLAUDE.md small
A rule whose failure costs money, data, or security	Hook, permission mode, or allowed-tools	Deterministic; instructions are not

The Skills line is where teams most often go wrong. One team added five detailed procedures to CLAUDE.md and grew it from 300 to 1,200 lines. Each procedure was used at most once a week, yet 900 lines rode along in every session and the model’s attention on the real coding standards degraded. Moving them to Skills brought the file back to 300 lines and task accuracy went up. The full reasoning is in CLAUDE.md is always-on, Skills are on-demand.

The hook line matters for a different reason. Prompt-based rules fail a small but non-zero share of the time because the model applies judgment; “always confirm before rm” gets overridden when the user says “clean up the project.” If a miss is unacceptable, do not make the wording louder, make the rule programmatic. See programmatic vs prompt enforcement and our companion post on hooks vs CLAUDE.md instructions.

What does a good project-level CLAUDE.md look like?

Concrete beats descriptive. In one measured case, “extract key facts accurately” scored 60%, adding “be precise and thorough” scored 63%, and three input/output examples scored 91%. Adjectives hit an ambiguity ceiling; examples do not. That result generalizes to CLAUDE.md, so show the exact commit format rather than describing it. The data is in concrete examples over text.

A compact skeleton:

# Acme API

## Stack
Node 22, TypeScript strict, Fastify, Prisma, Vitest.

## Commands
- Test:  `pnpm test` (must pass before any commit)
- Lint:  `pnpm lint --fix`
- Types: `pnpm typecheck`

## Conventions
- Commit format, example:
  `fix(parser): handle missing JSON field in parse_record()`
- Errors: throw `AppError` subclasses; never return `{ error }` objects.
- Never edit files under `prisma/migrations/` by hand.

## Shared standards
@docs/coding-standards.md
@docs/security-policy.md

Note the last block. Writing “follow docs/coding-standards.md” is just a sentence; Claude does not open the file. The @path import syntax pulls the content in as if it were inline, which lets the main file stay short while the standards live where the team already maintains them. Details in mentioning a file is not loading it.

How do path-scoped rules keep context clean?

Anything that applies to a type of file rather than a location belongs in .claude/rules/ with a paths glob:

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
Use Vitest. One `describe` per exported function.
Assert with `toEqual`, never `toBe`, on objects.

Without paths, a rules file loads for every edit, exactly like root CLAUDE.md. One project with twelve unscoped rules files was spending roughly 4,500 tokens per edit on rules, of which about 1,000 were relevant. Adding globs fixed it without deleting anything. Overlapping patterns load together, which is what you want: Button.test.tsx gets both React and testing rules.

The decision between a glob rule and a directory CLAUDE.md is simple. Scattered by type (tests, CSS modules, YAML configs) means glob. Concentrated by location (a self-contained backend) means directory file. The study articles on YAML frontmatter paths and glob rules vs directory CLAUDE.md cover the edge cases, including why duplicating test conventions across eight directory files is a maintenance trap.

Which CLAUDE.md anti-patterns show up on the exam?

These are the patterns the CCA-F scenarios keep returning to. Recognizing them is most of the work.

1. Team standards at user level. Symptom: “works for me, new hire gets nothing.” Fix: move to project level.
2. One giant root file for a polyglot repo. Symptom: React advice while editing Python. Fix: split into path-scoped rules; the criterion is file-type diversity, not team size.
3. Text references instead of imports. Symptom: “Claude ignores our guidelines.” Fix: @docs/file.md.
4. Cross-importing every subdirectory file. Symptom: 3,000 lines loaded per edit. Fix: import only genuinely shared standards.
5. Rare workflows inline. Symptom: file grows past a few hundred lines, quality drops. Fix: Skills.
6. Safety rules as prose. Symptom: the destructive command runs anyway 4% of the time. Fix: hook or allowed-tools.
7. Assuming inconsistency is randomness. Symptom: “Claude follows the rules some days.” Fix: run /memory to see what actually loaded before adding retries. See /memory diagnosis.
8. Inventing features. There is no <include> tag, no imports: frontmatter in CLAUDE.md, no always-active flag for Skills, and no priority ordering between levels. Answer options that rely on these are distractors.

The exam question behind most of these reads something like: “A team reports X. Which change is the most appropriate first step?” The tempting answers add emphasis, add retries, or add more text. The rewarded answer usually moves the content to the mechanism that matches its scope and consequence.

Next step

If Domain 3 is where your practice scores are weakest, work through the Domain 3 study guide in order; the configuration hierarchy, rules, and Skills articles build on each other. Then take the free 60-question mock exam, which samples questions by official domain weight so you can see how Claude Code configuration scenarios are actually phrased. Exam logistics such as the US$125 fee, 120-minute length, and 720 scaled passing score should be confirmed on the official Anthropic / Pearson VUE page before you register.