Skip to content

C2 · lesson 2 · 8 min read

The CLAUDE.md hierarchy

Where CLAUDE.md files live, how they are combined, and how imports and rules keep project instructions short and accurate.

Ընտրեք տեքստը՝ հայերեն թարգմանությունը տեսնելու համար։Highlight text to see Armenian. Machine-assisted translation; English is the source of truth.

Official video by Anthropic on YouTube. Pressing play loads it from youtube-nocookie.com. ·open on YouTube

CLAUDE.md is the file Claude Code reads at the start of a session to learn how your project works: build commands, conventions, and the things that must never happen. A good one saves you repeating yourself in every session. A bloated one wastes context on every turn.

The four levels

Level Location Shared with
Managed policy /etc/claude-code/CLAUDE.md (Linux), /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), C:\Program Files\ClaudeCode\CLAUDE.md (Windows) Everyone on the machine, set by IT
User ~/.claude/CLAUDE.md Just you, every project
Project ./CLAUDE.md or ./.claude/CLAUDE.md The team, through git
Local ./CLAUDE.local.md Just you, this project (add it to .gitignore)

How the files are combined

The important part: nothing overrides anything. Claude Code concatenates the files. At launch it loads CLAUDE.md and CLAUDE.local.md from the working directory and from every parent directory, ordered from the filesystem root down, so the files closest to you come last. In the same directory CLAUDE.local.md is added after CLAUDE.md.

CLAUDE.md files in subdirectories are not loaded at launch. They load on demand, the first time Claude reads or edits a file in that subdirectory. That makes them a good place for instructions about one part of a monorepo.

~/.claude/CLAUDE.md~/work/CLAUDE.md~/work/infra/CLAUDE.md ← working dir~/work/infra/CLAUDE.local.md~/work/infra/charts/CLAUDE.md(loads when Claude touches charts/)read order
Launch loads the ancestors of the working directory; subdirectories load when Claude works there.

Imports keep the file short

A CLAUDE.md can pull in other files with @path:

# infra

See @README.md for the layout and @docs/runbooks/deploy.md for releases.

## Rules

- Never run `terraform apply` locally; CI applies after review.
- Prod workspace is `prod-eu`; always confirm the workspace first.

Relative paths resolve from the file that contains the import. Imports can nest up to four hops deep. Importing a file from outside the project asks for approval once.

Path-scoped rules

For rules that only matter for some files, use .claude/rules/*.md. A rule with paths: frontmatter loads only when Claude works on matching files:

---
paths:
  - "charts/**"
---

- Bump `version` in Chart.yaml on every template change.
- Run `helm lint` and `helm template | kubeconform` before proposing a change.

User-level rules live in ~/.claude/rules/.

Commands that help

  • /init writes a starter CLAUDE.md from your codebase, or suggests improvements to an existing one.
  • /memory lists the instruction files loaded in this session and opens them in your editor.

The old # shortcut for adding a memory line has been removed. Ask Claude to edit CLAUDE.md instead.

Recap

  • There are four levels (managed, user, project, local), and they are concatenated. Closer files are read last.
  • Ancestors load at launch; subdirectory files load on demand.
  • @path imports nest up to four hops. .claude/rules/ with paths: scopes rules to some files.
  • /init bootstraps the file; /memory shows what’s loaded.

$ ./try-it.sh

Try it: write instructions for a Terraform/Kubernetes repo

  1. Run /init in a repo that has Terraform and Helm code and read the CLAUDE.md it proposes.
  2. Trim it to the facts a newcomer needs: how to run terraform plan, which workspace is prod, and what must never be applied by hand.
  3. Move the Helm-specific rules into .claude/rules/helm.md with a paths: glob for charts/**.
  4. Add a CLAUDE.local.md with your personal AWS profile name, add it to .gitignore, and check it with /memory.

Check yourself

3 questions. Original practice questions, not taken from the real exam.

  1. ~/.claude/CLAUDE.md says "prefer tabs". The project's CLAUDE.md says "indent YAML with two spaces". You run Claude Code in the project.

    1. How does Claude Code combine these files?

  2. In a monorepo you start Claude Code at the root. services/billing/CLAUDE.md holds billing-specific rules.

    2. When are the billing rules loaded?

  3. Your project CLAUDE.md has grown to 900 lines, most of it Helm conventions that only matter when editing charts/.

    3. Which two changes cut what's loaded on every turn without losing the rules? (Choose two.)

    Choose 2.

Answer every question to check.