Introduction to Claude Code Harness Engineering
When you use Claude Code, simply typing /debug spins up MCP, loads rules, and even runs a self-correction at the end of the response that says "don't ask in plain prose." This whole chain of actions happens behind the scenes. The goal of this guide is to understand that behind-the-scenes coordination by following the flow of a single command.
The subject is the author's own ~/.claude/ environment. Quoting the actual configuration files and scripts, we will trace in what order, and triggered by what, skill → rule → MCP → hook → memory come into play.
There are three guiding principles for how we proceed.
- Follow a single command: using
/debugas the lead example, we look at each element of the harness through the flow from error to fix, verification, and prevention of recurrence. - Live commentary over concepts: we keep abstract explanation to a minimum and proceed while confirming "what just fired" in real files.
- Fill gaps with detours: mechanisms that do not appear in
/debug(parallel launching of multiple agents, or the Guide-and-Sensor pair) are filled in via detours to/reviewand/grill-me.
Intended readers
- People who have used Claude Code but have not yet built their own
settings.json,rules/, or hooks - People who want to move from "it somehow works cleverly" to "I can explain which setting does what"
No prior knowledge of AI agents or LLMs is assumed. Terms are explained as they come up.
The line between custom and built-in (legend)
This guide introduces many mechanisms, but the author did not build all of them. What Claude Code provides are the rails (the hook event system, the rule loading mechanism, the tool specifications); what the author builds is the content that rides on those rails (scripts, standards, procedures). Once you see this boundary, you can judge "what I need to build in my own environment."
So in the chapters that follow, the following badges are attached to elements on first appearance.
| Badge | Meaning | Examples |
|---|---|---|
| 🔧 Custom | Scripts, standards, procedures, and definitions written by the author | hook scripts, rules, skills, subagent definitions |
| 📦 Built-in | Mechanisms provided by Claude Code itself | the hook event system, the paths: loading mechanism, ToolSearch, AskUserQuestion |
| 🌐 External | Skills derived from external repositories (sources and licenses tracked in a management file) | docx / pdf / test-driven-development |
The notation is kept understated. Inline badges are attached only to the first appearance within a page, and in tables only the symbol goes in the "Category" column cell. They are not placed inside the diagrams (Mermaid).
The 📦 rails exist in your environment too. In other words, once you understand the 📦 mechanisms, you can build the 🔧 content yourself, tailored to your own failures. Read the 🔧 examples in this guide not as "the answer" but as "sample work."
This guide is hands-on content that lets you experience the mechanisms through the flow of a single command. An overview of the idea of harness engineering itself is also covered in the blog post Introduction to Harness Engineering. Reading both gives you understanding from both the conceptual and the implementation sides.
The structure of this guide
| Cluster | What you learn | Keywords |
|---|---|---|
| What is a harness | The foundation of the harness idea | Agent = Model + Harness / the Guides-and-Sensors cross-classification / a map of the components |
| The lifecycle of /debug | The firing order of a single run of /debug | utterance triggers / on-demand loading of MCP / automatic rule loading / the verification loop / the Stop hook |
| How each layer works | A standalone deep dive into each layer | the rule loading mechanism / hook event registration (8 events in this environment) / the two-stage loading of MCP / the three layers of memory |
| Turning lessons into mechanisms | The flow of making lessons permanent and growing them | Ratchet / Generator-Evaluator separation / the Guide+Sensor pair |
How to read on
The lifecycle of /debug is the backbone of this guide. If you are in a hurry, start there; if you stumble on a term, go back to What is a harness; and when you want to dig into the mechanisms, move on to How each layer works. Turning lessons into mechanisms becomes valuable once you start thinking "I want to grow my own harness."
So let us begin with "what a harness is."