The .claude/ Folder, Actually Mapped
A widely-shared map of Claude Code's project folder claims to show "every canonical file Claude Code reads." We checked every row against the official documentation. The verdict is unusual for the genre: most of it is right — including the row we were most sure was invented. Here is the corrected, dated reference.
01 — The corrected mapWhat actually lives in a Claude Code project
├── CLAUDE.md — project instructions, loaded every session; advisory context, keep it lean
├── CLAUDE.local.md — personal additions; keep out of version control
├── .mcp.json — project-scope MCP servers; lives at the project root
└── .claude/ — everything below is optional; add what you need
├── settings.json — permissions, model, hook registry — shared with the team
├── settings.local.json — personal overrides, not committed
├── hooks/ — shell commands fired deterministically on events (SessionStart, PostToolUse, PreCompact…)
├── commands/ — custom slash commands; the simpler sibling of skills, still fully supported
├── skills/ — folder-based procedures the model invokes on demand
├── agents/ — subagent definitions; each runs in its own isolated context
├── rules/ — modular rule files, discovered recursively; path-scoped via glob patterns
├── output-styles/ — custom response formats
└── plugins/ — bundled commands + agents + MCP, installed as units
statusline — configured in settings, not a folder: the bottom-bar display
02 — The surpriseThe row we expected to kill survived
The poster's least-known claim — a rules/ directory whose files load only
when Claude works on matching paths — sounded like an invention. It is not. The
official documentation confirms it: rule files declare glob patterns
("src/api/**") in their frontmatter and load only when a matching file is
touched, keeping area-specific conventions out of context until they earn their
tokens. This is the third time in this series a claim we doubted was vindicated by a
primary source. Skepticism is not verification — in either direction.
03 — What needed correctingThe folklore rows
- "CLAUDE.md, under 200 lines." The principle is real — short, specific instructions outperform long ones — but the number is folklore. No documented line limit exists. Write the shortest file that states your real rules.
- "commands/ — legacy, still works." Half right. Custom slash commands remain documented and supported; "legacy" is editorializing. The honest framing: commands for simple, single-file prompts; skills for structured, multi-file procedure. Different tools, both current.
- The auto-commit hook example. Hooks firing deterministically on events is correct and documented. A hook that auto-commits after every edit is one author's pattern — powerful, but a choice with consequences (noisy history), not a canonical setup.
- "MUST be at root" for
.mcp.json. True for project-scope servers. The nuance the poster drops: user-scope and enterprise-scope MCP configuration live elsewhere; the root file is one of several layers.
04 — The ledgerEighteen rows, checked 2026-08-05
| Claimed | Verdict | The record |
|---|---|---|
| CLAUDE.md — project rules, loaded first | VERIFIED | Core documented mechanism. |
| CLAUDE.md "< 200 lines" | NUANCE | Principle sound; the number is folklore. |
| CLAUDE.local.md — personal, keep out of git | VERIFIED | Documented personal-overrides file. |
| .mcp.json at project root | VERIFIED | Project-scope MCP config; other scopes exist elsewhere. |
| settings.json / settings.local.json split | VERIFIED | Shared vs personal, exactly as drawn. |
| hooks/ — deterministic, fires every time | VERIFIED | Shell commands on lifecycle events. |
| SessionStart / PostToolUse / PreCompact as events | VERIFIED | All three are real hook events. |
| Auto-commit-after-edit hook | NUANCE | Works; a personal pattern, not canon. |
| commands/ "legacy, still works" | NUANCE | Supported and current; "legacy" overstates. |
| skills/ — canonical home, model-invokable | VERIFIED | Folder-based, loaded on demand. |
| agents/ — subagents, isolated context | VERIFIED | As documented. |
| rules/ — path-scoped, loads on glob match | VERIFIED | Real: recursive discovery, frontmatter globs. |
| output-styles/ — custom response formats | VERIFIED | As documented. |
| plugins/ — "first-class in 2026" | VERIFIED | Bundled commands/agents/MCP, namespaced invocation. |
| statusline — bottom-bar config | NUANCE | Real feature; configured in settings, not a standalone file as drawn. |
| "CLAUDE.md is advisory" | VERIFIED | Context, not enforcement — the poster's own footer gets this right. |
| "Hooks are deterministic" | VERIFIED | The correct contrast with model-read context. |
| "Every canonical file" (completeness) | NUANCE | Strong coverage; the directory is optional and evolving — date any map, including this one. |
05 — Operating ruleMaps of moving software expire
Fourteen of eighteen rows verified is an excellent score for the genre — and it still doesn't make the poster safe to trust in six months. Claude Code's directory docs are the living source of truth; this sheet is dated in its title block for exactly that reason. Use the map; check the date; when in doubt, read the documentation page it was checked against.