本編を書き終えて、しばらくしてから、とても重要なことに気づきました。
何もしなくてよくなって、私は満足していました。ですが、これは本です。本来の目的を、私はすっかり忘れてしまっていました。どうやら私は、忘れるのが得意なようです。
当初は、読者が何もしなくてよくなることを目指していました。ところが、私が何もしなくてよくなった時点で、考えるのをやめてしまっていました。
本編で省略してしまった、読者に届かなかった背景技術を、ここから伝えていきます。
この付録は誰に向けて書くか
本編を読み終えた、上級の技術者に向けて書きます。本編は「置くのは 1 つ」で通しましたが、置いたものの下で何が動いているかは、ほとんど説明していません。hook の exit code が 2 だとなぜ AI に届くのか。指示ファイルは system prompt なのか、そうではないのか。サブエージェントには何が渡っていて、何が渡っていないのか。本編はそれらを前提として使い、説明を省きました。付録は、その前提を並べ直します。
技術用語は、噛み砕かずにそのまま使います。system prompt、prefix cache、tool_result、JSONL。本編で「コンテキスト」「機構」「中央」と呼んできたものには、対応する技術名称を付録 J の用語集に置きます。
書き方の約束
付録の各章は、同じ形で書きます。
- 先に結論 —— 技術書なので、結論を冒頭に置きます。本編とは逆です
- 仕組み —— なぜその挙動が起きるかを、図と表で。言葉で足りないところは mermaid の図にします
- 出典 —— 公式ドキュメントの URL と、私が確認した日。他人の研究を引くときは帰属を人が検証してから載せます
- 本編との対応 —— 本編が「置いたもの」と、その下にある仕組みの対応
- 本編が言っていない注意 —— 本編の技術を適用したときに、別の場所で何が変わるか。バージョン依存、環境依存、私の手元でしか確かめていないこと
- 検証手順 —— 走らせるコード付きで。止まるべきものが止まり、通るべきものが通ることを、両方向で確かめます
本編 37 本は、この付録を書く前に 1 本ずつ読み直し、「なぜその挙動が起きるか」「適用したら他に何が波及するか」「説明していない技術は何か」を回ごとに洗い出しました。その整理が、各章の「本編との対応」と「本編が言っていない注意」の元です。
Claude Code は毎週のように変わります。付録の数字と挙動は、2026-09-05 に Claude Code 2.1.260 で確認したものです。あなたが読む時点で変わっている可能性があるので、各章の末尾に検証手順を置きます。本編と同じで、書いてあることを信じる前に、手元で壊して確かめてください。
一つ、線を引いておきます。Claude Code の system prompt の全文は、公式には公開されていません。付録では、公式ドキュメントが書いている範囲と、あなたの手元で観測できる範囲で仕組みを説明します。内部プロンプトの文面を書き写すことはしません。
付録の構成
| 章 | 主題 | 本編で置いたもの |
|---|---|---|
| A | 1 ターンの解剖 —— リクエストに何が載っているか | 指示ファイル・メモリの索引・hook の出力が「どこに」届くか |
| B | コンテキストの寿命 —— 圧縮・キャッシュ・サブエージェント | 引き継ぎ・口を挟まない・サブエージェントの入出力 |
| C | hook の契約 —— イベント・exit code・JSON | 入口の hook・宣言のガードレール・方針の差し込み・数字の行の照合 |
| D | 指示ファイル・ルール・メモリ・スキルの読み込み時点 | 足すほど薄まる・索引だけが読まれる・スキルを使わない |
| E | サブエージェントの機構と測定法 | 用途カタログ・入力だけは確かめろ・出力だけは細かく指示しろ・3 作の probe |
| F | 自動テストの 8 つの型 | 走査テスト・ラチェット・メタテスト・変異注入 |
| G | git とプロセスの機構 | pre-commit hook・worktree・ロック・PID・採番 |
| H | 画面と本番の検証のはしご | スクリーンショットを撮らない・スモークテスト・不具合報告の器 |
| I | AI の性質の出典 | 追従・過剰指示・幻覚のガードレール |
| J | 用語集 | 連載の造語と技術名称の対応 |
| 結び | 依存はどこにあるか | 31 個の仕組みを、AI に依存するものとしないものに分ける。5 か月の git log |
順に読む必要はありません。本編で気になった仕組みの章から開いてください。