Configure CLAUDE.md

Choose the right scope

Configuration 1

Choose the narrowest correct location

Claude Code combines instructions across managed, user, project, local, and directory scopes.

1. Use `~/.claude/CLAUDE.md` only for personal preferences that should follow you across projects.
2. Commit `CLAUDE.md` or `.claude/CLAUDE.md` for team-shared project guidance.
3. Add `CLAUDE.local.md` to `.gitignore` for machine- or user-specific project notes.
4. Use nested CLAUDE.md files for subtrees; they load when Claude reads files in those directories.

Important: Files above the working directory load at launch. Subdirectory files load on demand, so do not assume every nested file occupies startup context.

Configuration 2

Write concise, verifiable instructions

CLAUDE.md content is context, and concise concrete rules receive more reliable attention than vague prose.

1. Target fewer than 200 lines per file.
2. Replace ‘follow best practices’ with a command, path, measurable constraint, or canonical example.
3. Remove duplicated and conflicting guidance during normal code review.

# Project Instructions

## Commands
- Focused test: `npm test -- path/to/test`
- Full validation: `npm test && npm run build`

## Architecture
- API handlers live in `src/api/handlers/`.
- Do not edit generated files in `src/generated/`.

Configuration 3

Import shared facts deliberately

Use `@path` to load another file into context. Relative imports resolve from the CLAUDE.md containing them.

1. Wrap a path in backticks if you want to mention it without importing it.
2. Expect approval when a project file imports content from outside the working directory.
3. Remember that imported content still consumes startup context.

@AGENTS.md

## Claude Code
- Use plan mode before changing authentication code.

Important: If the repository already uses AGENTS.md, import it instead of maintaining two copies of shared instructions.

Configuration 4

Move conditional guidance into project rules

Files under `.claude/rules/` can be organized by topic and scoped to matching paths.

1. Use one focused topic per rule file.
2. Keep rules without `paths` only when they truly apply to every task.
3. Use `/context` to confirm which memory and rule files loaded.

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate every external input.
- Use the standard error response format.

Validation checklist

• Start a new Claude Code session and run `/context`.
• Confirm the expected project, local, imported, and path-scoped files appear at the correct time.
• Ask Claude to repeat exact commands and architecture boundaries without editing.
• Open a matching file and confirm its path-scoped rule becomes available.
• Use `/doctor` when invalid or conflicting configuration is suspected.

Common configuration mistakes