A practical guide to CLAUDE.md in Claude Code: hierarchy, loading, best practices
4310sy · x · 2026-08-15
A Japanese developer published a systematic reference on Qiita for writing CLAUDE.md, Claude Code's instruction/memory file, clarifying features many use only by intuition.
File hierarchy and loading
- Four locations: user-global /.claude/CLAUDE.md (not in git), project ./CLAUDE.md (committed), ./CLAUDE.local.md (not committed), and subdirectory-level CLAUDE.md
- Loading runs from the filesystem root toward the working directory; subdirectory files load on demand when Claude reads that directory
- Multiple files are simply concatenated, not overridden — conflicting instructions resolve unpredictably, so avoid clashes; use claudeMdExcludes with glob patterns to exclude files
Advanced usage
- The @path/to/file import syntax expands another file's contents in place, supports relative/absolute paths and /, with nesting up to 4 hops; wrapping in backticks keeps it a plain string
- /init analyzes the codebase and generates a draft without overwriting an existing file (it proposes improvements instead); /memory lists loaded CLAUDE.md files and opens them in an external editor
Best practices: keep it under 200 lines; write commands, conventions, quirks and decisions rather than what code already reveals; be specific ("2-space indent" not "format properly"); use headings and lists; emphasize with keywords like IMPORTANT.
More from coding & agent
- GitHub workflows show cracks under heavy AI workloads — talkaboutdesign · 2026-08-15
- Deconstructing the AI Agent: Loops, Memory, and MCP — noninertialframe96 · 2026-08-15
- AI coding agent adds workspaces with automatic hinting — zeeg · 2026-08-15
- Deep dive: How Claude Desktop handles MCP resource links and embedded data — SnooDoubts8106 · 2026-08-15
- MongoDB: Small retrieval errors compound significantly in autonomous agent workflows — schwentker · 2026-08-15
- MongoDB.local demo: agent places a PO but only writes a record — no funds move — schwentker · 2026-08-15