2.2 · CLAUDE.md — hierarchy & precedence

User-level (~/.claude/CLAUDE.md) applies to all your projects across your machine. Project-level (./CLAUDE.md at the repo root) applies to that project. Subdirectory-level (./some/path/CLAUDE.md) applies only when you're working in files under that path.

~/                              # user home
├── .claude/
│   └── CLAUDE.md              # applies to ALL your projects
│                              # e.g. "Prefer TS over JS"
│
└── work/monorepo/             # this repo
    ├── CLAUDE.md              # applies to the whole repo
    │                          # e.g. "Python 3.12, black, pytest"
    ├── services/
    │   ├── api/
    │   │   ├── CLAUDE.md      # applies under services/api/
    │   │   │                  # e.g. "2-space indent, FastAPI"
    │   │   └── main.py
    │   └── worker/
    │       └── main.py         # inherits root only
    └── .claudeignore          # excludes dist/, .env, secrets/

When rules conflict, more specific overrides less specific: subdirectory > project > user. Non-conflicting rules from all levels compose. This is the model of every well-designed config system.

User-level: your personal preferences (coding style, comment style). Project-level: repo conventions, build/test/lint commands, architectural rules, vocabulary. Subdirectory-level: local overrides where a subsystem differs from the project default.

Write it like briefing a senior engineer joining the team. Say what to do, not encyclopedic what things are. Include the exact commands (npm test, not 'run tests'). Note the anti-patterns you want avoided. Keep it under a screen — every turn re-reads it.

The .claude/rules/ directory holds rule files with YAML glob frontmatter — patterns like 'apply this rule to **/*.test.ts.' Unlike directory-level CLAUDE.md, which only applies when you're working IN that directory, rules can cross the codebase. Use for rules that must span many directories (test conventions, security patterns, review checklists).

# .claude/rules/test-conventions.md
---
globs: ["**/*.test.ts", "**/*.spec.ts"]
---

- Use vitest, not jest
- Test file lives next to source
- No mocking unless calling the network

.gitignore syntax. Excludes files from Claude's reads. Essential for monorepos, generated code, vendored dependencies, and (especially) secrets. Note this is about reading — writing to protected paths needs hooks.