CLAUDE.md Configuration — Detail & Examples

Part of Claude Code · overview: domain-3.html

In this page

The classic user-vs-project-level trap traced step by step, and a clear comparison of @path imports against path-scoped rules.

3.2aThe trap, traced

WORKED EXAMPLE · THE CLASSIC CLAUDE.MD TRAP

SCENARIODeveloper A has used Claude Code on this project for months. Developer B just joined and cloned the repo.

Developer A long ago wrote down the team's API naming and error-handling conventions — but saved them in ~/.claude/CLAUDE.md, their personal user-level file.
For Developer A, Claude Code has always followed these conventions perfectly, because their user-level file is always present on their machine.
Developer B clones the same repository. Nothing about Developer A's user-level file comes along with the clone — it was never part of the repo.
Claude Code, working in Developer B's environment, has no idea these conventions exist and produces code that doesn't match the team's actual standards.

Fix:Move the conventions into .claude/CLAUDE.md (or a root CLAUDE.md) — version-controlled, so every clone gets them automatically.

Same goal, different mechanism

@path imports: good for organizing a large CLAUDE.md into readable pieces. Every import is inlined in full at load time — splitting a 500-line file into five 100-line imported files still loads all 500 lines.
.claude/rules/: good for reducing what's actually loaded. A rule scoped to /frontend/** only loads into context when Claude is working inside that path — work in /backend/ never pulls it in.
Rule of thumb: reach for imports when your goal is maintainability of the source; reach for path-scoped rules when your goal is shrinking per-session context.

Claude Certified Architect — Study NotesDWG 3.2