Skip to main content

3.1 CLAUDE.md hierarchy, scoping, and modular organization

The hierarchy​

Full reference: Manage Claude's memory.

LevelPathShared via version control?Scope
User~/.claude/CLAUDE.mdNoOnly that user, across all their projects
ProjectCLAUDE.md at the repo root, or .claude/CLAUDE.mdYesEveryone who clones the repo
DirectoryCLAUDE.md in a subdirectoryYesWork touching that subtree
The canonical diagnosis item

"A new team member isn't getting our conventions." The instructions are in ~/.claude/CLAUDE.md — user level, never shared through version control. Move them to the project level.

Use /memory to verify which memory files are actually loaded and to diagnose inconsistent behaviour across sessions.

@import for modularity​

Reference external files so CLAUDE.md stays small and each package pulls only what it needs:

packages/api/CLAUDE.md
# API package

@../../standards/error-handling.md
@../../standards/api-conventions.md
@./fixtures.md

Selective imports let each package's maintainer include the standards files relevant to their domain rather than loading everything everywhere.

.claude/rules/ as an alternative to a monolith​

Split a large CLAUDE.md into focused topic files:

.claude/rules/
├── testing.md
├── api-conventions.md
└── deployment.md

Preparation exercise 2 — Claude Code for a team development workflow​

Objective: CLAUDE.md hierarchies, custom slash commands, path-specific rules, and MCP server integration for a multi-developer project.

  1. Create a project-level CLAUDE.md with universal coding standards and testing conventions. Verify project-level instructions apply consistently for every team member.
  2. Create .claude/rules/ files with YAML frontmatter glob patterns — e.g. paths: ["src/api/**/*"] for API conventions, paths: ["**/*.test.*"] for testing conventions. Confirm rules load only when editing matching files.
  3. Create a project-scoped skill in .claude/skills/ with context: fork and disallowed-tools restrictions. Verify it runs in isolation without polluting the main conversation.
  4. Configure an MCP server in .mcp.json with environment variable expansion for credentials. Add a personal experimental server in ~/.claude.json and verify both are available simultaneously.
  5. Test plan mode vs direct execution on three tasks: a single-file bug fix, a multi-file library migration, and a new feature with multiple valid implementation approaches. Observe when plan mode earns its cost.

Reinforces: Domain 3, Domain 2

Quiz​

  1. Question 1

    A new engineer reports that Claude keeps generating Jest syntax although the team migrated to Vitest six months ago. Every other engineer gets Vitest output from the same prompts in the same repository. The convention was written by the tech lead at migration time, and the root CLAUDE.md has not been touched since before the migration. What is the most likely cause and fix?

  2. Question 2

    Your monorepo root CLAUDE.md has reached 900 lines covering React, Go services, Terraform, and data pipelines. Claude now applies Terraform naming rules inside React components, and the file crowds out task context. Each package is owned by a different team, several packages share the same API-conventions and security standards files, and the conventions align cleanly with package directories. What structure fits best?

  3. Question 3

    Two engineers on the same repository and the same commit get different behaviour from the same prompt: one gets tests in the project style, the other does not. Neither has changed anything locally that they are aware of. What is the first diagnostic step?

  4. Question 4

    Your CLAUDE.md now covers testing, API conventions, deployment and security in one file. Engineers report Claude applying deployment rules to unrelated code, and edits to the file cause merge conflicts on nearly every pull request. None of the four topics maps to a particular directory. What organisation helps?