A map of ~/.claude's components
Building on the harness idea (Agent = Model + Harness) and the classification yardstick (Guides and Sensors), this chapter maps out what is actually placed in the real ~/.claude/ directory. When following a command's flow in the chapters that follow, it serves as an index you can reference: "the file that just fired is in this cell."
The counts below are values measured in the author's environment (as of 2026-06-12. hooks are counted with ls hooks/*.sh, rules by the presence of frontmatter). A harness is something you grow, so the numbers go up and down. Read them as "roughly this scale."
A list of components
The "Category" column uses the three categories from the legend. 🔧 = the author's custom work, 📦 = a built-in Claude Code mechanism, 🌐 = derived from an external repository.
| Element | Location | Role | What triggers it | Category | Classification |
|---|---|---|---|---|---|
CLAUDE.md | ~/.claude/CLAUDE.md | Overall policy and identity | Always loaded (always read at startup) | 🔧 | Inferential Guide |
| rules (34) | ~/.claude/rules/*.md | Standards to follow | 7 are always loaded; 27 when the matching file is opened | 🔧 | Inferential Guide |
| skills (39 = 25 custom + 14 external) | ~/.claude/skills/*/SKILL.md | Commands that package up procedures | A trigger word in an utterance, or /name | 🔧 + 🌐 | Inferential Guide |
| agents (7 roles) | ~/.claude/agents/*.md | Specialized subagents | When the main agent decides to delegate | 🔧 | Inferential (generate or evaluate) |
| hooks (17, of which 5 were added in incident response immediately after this chapter was drafted) | ~/.claude/hooks/*.sh | Auto-run scripts | Events registered in settings.json | 🔧 (the event mechanism is 📦) | Computational |
| MCP | External servers | Fetching official docs, structured reasoning, etc. | Loaded on demand with ToolSearch | 📦 (server selection and usage agreements are 🔧) | Inferential tool |
| memory | learnings/, projects/.../memory/, context/ | Lessons that span sessions | /learn / automatic / handoff | 📦 + 🔧 | Persistence |
| references | ~/.claude/references/*.md | Detailed protocols and templates | Fetched with Read when needed | 🔧 | Supporting material |
| docs/adr | ~/.claude/docs/adr/*.md | Records of design decisions | Appended to and referenced at important decisions | 🔧 | Records |
Of the 39 skills, 14 are taken in from external repositories (Anthropic / Addy Osmani / Vercel Labs) (🌐). These track their sources and licenses in a management file called skills/ATTRIBUTION.md. Even when "incorporating someone else's sample work into your own harness," recording where it came from makes it easier to grow later.
The overall relationship diagram
Solid lines are "the flow of calls," and dotted lines are "hook interrupts." A hook can be inserted from the side at any stage, so it is drawn with a dotted line in the diagram.
Lead and supporting subagents
Seven roles are defined in agents/. They are the foundation of the "separate the implementer from the evaluator" design (Generator-Evaluator separation) covered in a later chapter.
- Generators:
implementer(implementation),refactorer(refactoring) - Evaluators:
code-reviewer/architect/test-strategist/infra-reviewer - Both (investigate and fix):
debugger(bug investigation and fixing)
Beyond these, ~/.claude/teams/ has one team definition (multi-perspective-review) that launches a set of multiple subagents in parallel. Details are covered in subagents and the division of roles.
/debug and the debugger subagent are different thingsThe backbone of this guide is the /debug skill. There is also a debugger subagent with a very similar name, but it is a specialized agent that investigates large amounts of code in isolation in a separate context. /debug is "investigate immediately in the current working environment," while debugger is "investigate thoroughly in an isolated environment" — the roles are split (we will reconfirm this in the next chapter).
The map is now complete
Once the names, locations, and firing conditions of the elements are in your head, the preparation is done. From the next chapter, we trace which parts of this map light up, and in what order, when you run /debug once.
The key points are as follows.
- The harness is composed of
CLAUDE.md/ rules / skills / agents / hooks / MCP / memory / references / docs/adr - There are things that are always in effect (
CLAUDE.mdand 7 rules) and things that take effect conditionally (27 rules, skills, MCP) - A hook is a deterministic mechanism that interrupts from the side at any stage
- Subagents are split into "generators" and "evaluators"
Continuing, in From utterance to skill launch, we trace the execution flow of /debug in chronological order.