Claude Code ハーネスエンジニアリング入門
Claude Code を使っていると、/debug と打っただけで MCP が立ち上がり、ルールが読み込まれ、応答の最後には「平文で質問しないで」と自己修正まで走ります。こうした一連の動きが裏で起きています。このガイドは、その裏側の連携を、1 つのコマンドのフローを追って理解することを目的にします。
題材にするのは筆者の ~/.claude/ 環境です。設定ファイルやスクリプトの実物を引用しながら、skill → rule → MCP → hook → memory がどの順番で、何をきっかけに動くのかを追っていきます。
進め方の指針は次の 3 つです。
- 1 コマンドを軸に追う: 主役の
/debugを例に、エラー発生から修正・検証・再発防止までの流れでハーネスの各要素を見る - 概念より実況: 抽象的な説明は最小限にし、「いま何が発火したか」を実ファイルで確認しながら進める
- 足りない部分は寄り道で補う:
/debugに出てこない仕組み（複数エージェントの並列起動や Guide と Sensor の対）は、/reviewと/grill-meへの寄り道で補う
想定読者
- Claude Code を触ったことはあるが、
settings.jsonやrules/、hooks をまだ自分で組んでいない人 - 「なんとなく賢く動いている」状態から、「どの設定が何をしているか説明できる」状態に進みたい人
AI エージェントや LLM の基礎知識は前提にしません。出てくる用語はその場で説明します。
自作と標準の境界（凡例）
このガイドにはたくさんの仕掛けが登場しますが、すべてを筆者が作ったわけではありません。Claude Code が用意するのはレール（hook のイベント体系、rule のロード機構、ツールの仕様）で、筆者が作るのはレールに載せる中身（スクリプト、規範、手順）です。この境界が見えると、「自分の環境で何を作ればよいか」が判断できるようになります。
そこで以降の章では、初出の要素に次のバッジを付けます。
| バッジ | 意味 | 例 |
|---|---|---|
| 🔧 自作 | 筆者が書いたスクリプト・規範・手順・定義 | hook スクリプト、rule、skill、subagent 定義 |
| 📦 標準 | Claude Code 本体が提供する機構 | hook のイベント体系、paths: ロード機構、ToolSearch、AskUserQuestion |
| 🌐 外部 | 外部リポジトリ由来の skill（出典・license を管理ファイルで追跡） | docx / pdf / test-driven-development |
表記は控えめにします。インラインのバッジは同一ページ内の初出にだけ付け、表では「区分」列のセルに記号だけを入れます。図（Mermaid）の中には入れません。
📦 のレールはあなたの環境にも同じものがあります。つまり、📦 の機構を理解すれば、🔧 の中身は自分の失敗に合わせて自作できます。このガイドの 🔧 は「答え」ではなく「作例」として読んでください。
このガイドは「1 コマンドの流れで仕組みを体感する」実践寄りの内容です。ハーネスエンジニアリングという考え方そのものの概観は、ブログの ハーネスエンジニアリング入門 でも扱っています。あわせて読むと、概念と実装の両面から理解できます。
このガイドの構造
| まとまり | 何を学ぶか | キーワード |
|---|---|---|
| ハーネスとは | ハーネスという考え方の土台 | Agent = Model + Harness / Guides・Sensors の十字分類 / 構成要素の地図 |
| /debug のライフサイクル | /debug を 1 回実行したときの発火順 | 発話トリガー / MCP の on-demand ロード / rule 自動ロード / 検証ループ / Stop hook |
| 各レイヤの仕組み | 各レイヤの仕組みを単体で掘り下げ | rule のロード機構 / hook のイベント登録（この環境では 8 イベント） / MCP の 2 段ロード / memory の 3 層 |
| 学びを仕組みに変える | 学びを恒久化して育てる流れ | Ratchet / Generator-Evaluator 分離 / Guide+Sensor のペア |
読み進め方
/debug のライフサイクルがこのガイドの背骨です。急ぐならそこから読み、用語でつまずいたらハーネスとはに戻り、仕組みを深掘りしたくなったら各レイヤの仕組みへ進む、という読み方でも問題ありません。学びを仕組みに変えるは「自分のハーネスを育てたい」と思ったときに効いてきます。
それでは、まず「ハーネスとは何か」から始めます。