Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization

Claude Code assembles its instructions from plain-markdown memory files it discovers by location. Three tiers matter for this exam: user-level at ~/.claude/CLAUDE.md (applies to every project you open on this machine), project-level at the repo root ./CLAUDE.md or .claude/CLAUDE.md (shared with the whole team through version control), and directory-level CLAUDE.md files placed inside subdirectories (scoped to one package or folder).

When a session starts, Claude Code walks up the directory tree from your current working directory toward the filesystem root and loads every CLAUDE.md it finds, plus your user-level file. Directory-level files deeper in the tree are pulled in on demand when Claude reads or edits files in that subtree, so a packages/api/CLAUDE.md governs work inside packages/api without polluting unrelated packages.

All discovered files are combined into context. A separate enterprise managed policy file, if your organization deploys one, sits above everything and cannot be overridden; beyond that, treat the tiers as layered, with more specific files refining the broader ones. The single most testable consequence: only files committed to the repository reach your teammates and CI.

The defining difference between the tiers is who sees them. ~/.claude/CLAUDE.md lives in your home directory, never enters the repository, and therefore never reaches teammates, pull-request automation, or CI runners. Project-level and directory-level files live in the repo, so cloning or pulling the repository is all it takes to receive them.

This produces the canonical exam diagnostic: a convention 'works on my machine' but a new team member's Claude ignores it. The cause is almost always that the instruction sits in your personal user-level file instead of a committed project file. The fix is to move it into ./CLAUDE.md (or a .claude/rules/ file) and commit it, not to reword the instruction.

Use user-level memory only for genuinely personal preferences (how you like responses phrased, editor habits) that should follow you across all projects and that no teammate needs. Anything the team must apply consistently belongs in project scope.

CLAUDE.md supports an @import syntax: writing @path/to/file inline pulls that file's contents into the memory context. Paths may be relative to the importing file or absolute, and ~ is allowed for home-directory paths. Imports can nest up to five levels deep, and an @-reference inside a code span or code fence is treated as literal text rather than an import.

This lets you keep a lean, readable root CLAUDE.md that composes focused standards files instead of duplicating them. In a monorepo you can give each package's CLAUDE.md only the imports its maintainer knows are relevant:

# packages/api/CLAUDE.md
@../../.claude/rules/api-conventions.md
@../../.claude/rules/testing.md

The payoff is a single source of truth: update testing.md once and every package that imports it stays in sync. Copy-pasting the same block into each file instead guarantees drift over time.

When a root CLAUDE.md grows into hundreds of lines covering testing, API design, deployment, and more, it becomes hard to maintain and forces irrelevant context into every session. The modular alternative is the .claude/rules/ directory: split the monolith into focused topic files such as testing.md, api-conventions.md, and deployment.md.

These rule files are still version-controlled project configuration, so the team-sharing property is preserved. You can reference them from CLAUDE.md with @import, and (as covered in task 3.3) rule files can carry YAML frontmatter with a paths: glob field so a rule loads only when Claude edits matching files. For task 3.1 the key idea is purely organizational: many small, purpose-named files beat one sprawling document.

Think of .claude/rules/ as the organized layer of project memory. It complements CLAUDE.md rather than replacing the concept of committed, team-shared configuration.

The /memory slash command is your inspection and editing tool. It shows which memory files are currently loaded and lets you open them for editing, which is exactly how you diagnose 'why does Claude behave differently in this session' or 'why is my rule not taking effect.' If a file you expected is absent from the list, you have found your scoping bug.

Two related mechanics: /init bootstraps a project by generating a starter CLAUDE.md from the codebase, and beginning a line of input with # quickly appends a note to a memory file without leaving the conversation.

Crucially, none of this involves a config.json commands array, an environment variable, or a hidden flag. Memory is just markdown discovered by location, and /memory is the reliable way to confirm what actually loaded.

Deciding where an instruction lives is a design skill. Ask two questions: who needs it and when should it apply. If the whole team needs it always, it belongs in project-level CLAUDE.md (optionally split via .claude/rules/ and @import). If only you need it, user-level. If it applies only to one package, a directory-level CLAUDE.md. If it applies to a file type scattered across directories (for example all *.test.tsx), a path-scoped rule file is better than a directory CLAUDE.md (task 3.3).

Reserve CLAUDE.md for always-loaded, universal standards. On-demand, task-specific workflows belong in skills or slash commands (task 3.2), not in memory, because everything in CLAUDE.md consumes context on every single request. Being disciplined here keeps the always-on context small and the model's attention on what matters.