御舆：Claude Code のハーネス構造を読む中国語技術書、その読み方と限界

この本が埋めようとしている穴

Claude Code を使っていると、動作は観察できるが理由は見えない。なぜそのツール呼び出しが拒否されたのか、なぜ会話が途中で圧縮されたのか、なぜある機能が環境によって現れないのか。公開されているのは CLI の挙動と設定ファイルの仕様であって、それを動かしているランタイムの構造ではない。本書はこの隙間を、Agent Harness という語で呼んだ実行時フレームワークの分解で埋めようとする。対象読者は 2 種類いる。Claude Code を日常的に使い、その振る舞いの裏側を把握したい実務者。そして、同じようなエージェント実行基盤を自分で作ろうとしている設計者である。前者には第 4 章の権限パイプラインと第 7 章のコンテキスト管理が直接効く。後者には第 15 章のロードマップと付録 A の依存関係図が効く。読者層を絞っていない点は長所でも短所でもある。15 章すべてを読む必要はなく、README 自身が「初次阅读」として 01 → 02 → 04 → 15 という順路を提示している。

15 章を 4 篇に割る構成と、その分割の意図

構成は基礎篇、核心系統篇、高級模式篇、工程実践篇の 4 つ。基礎篇は会話ループ、ツールシステム、権限パイプラインという 3 つの柱を扱う。核心系統篇は設定、記憶、コンテキスト、フックという横断的サブシステムに移る。高級模式篇はサブエージェント、コーディネータ、スキル、MCP という組み合わせの話。工程実践篇は性能、Plan モード、そして自作ハーネスの構築手順である。この並びは「1 つのループを理解し、次にその周囲の状態管理を理解し、最後に複数エージェントに広げる」という依存順になっている。章の中身は概念説明ではなく機構の記述に寄っている。第 2 章は `while(true)` の非同期ジェネレータ主ループ、5 種の yield イベント、10 種の終了理由、`QueryDeps` による依存注入を扱う。第 3 章は `Tool<I,O,P>` の 5 要素プロトコルと `buildTool` ファクトリ、そしてツールを並行実行する際の貪欲法によるパーティション分割である。第 7 章は有効ウィンドウの計算式と Snip → MicroCompact → Collapse → AutoCompact という 4 段階の漸進圧縮、さらにサーキットブレーカを挙げる。名称と段数が明示されている点で、抽象論より一段踏み込んでいる。

権限パイプラインとフック、拡張点の設計をどう読むか

本書で最も実務に直結するのは第 4 章と第 8 章だろう。第 4 章は権限判定を 4 段階のパイプラインとして説明し、5 種の権限モードのスペクトル、Bash ルールのマッチング、そして推測的分類器を 2 秒の `Promise.race` で打ち切る仕組みを挙げる。タイムアウトで判定を確定させる設計は、安全性と応答性のトレードオフを数値で切った例である。第 8 章はフックを 5 種、ライフサイクルイベントを 26 個、JSON 応答プロトコル、6 層の優先順位、3 層の安全機構として整理する。拡張点がこれだけ多いということは、逆に言えばイベント名と優先順位を誤ると意図したタイミングで発火しないということで、本書の表がそのまま逆引き資料になる。ただし README の「阅读说明」は、記述にはソースから確認できる挙動、アーキテクチャ推論、教学用サンプルの 3 種が混ざると明記している。フックの優先順位のような細部がどの区分に属するかは、本文の記述だけでは判別しにくい。ここは読む側が警戒しておくべき箇所である。

動かすためのコマンドは書籍本体ではなくリポジトリ側にある

本書は読むためのテキストであって、インストールして動かすソフトウェアではない。リポジトリ側で実行が想定されているのは検証スクリプトである。README は投稿前に `python3 scripts/check_book.py` と `python3 -m unittest discover -s tests` を走らせるよう求めている。Mermaid 図の構文検査には Node.js 22 以上が必要で、`npm ci` の後に `npm run check:diagrams` を実行する。つまり Python は本文とテストの検査に、Node.js は図の検査に使われ、主言語の表記が Python であることはエージェント実装の言語を意味しない。本文が扱う技術スタックは第 1 章に Bun + React/Ink + Zod v4 と書かれている。TypeScript 側の話を Python のリポジトリで読む形になるので、言語表記だけで内容を判断すると外す。オンライン版は https://lintsinghua.github.io/ で読める。リポジトリ内の章ファイルは第一部分から第四部分、および付録 A から D というディレクトリ構成で、README の目次からリンクされている。

ライセンスと保守コストの実態

ライセンスは注意が必要である。リポジトリのメタデータ上は unknown としか取れないが、README は本文の文字が CC BY-NC-SA 4.0 だと明記している。条件は 3 つ。表示、非商業利用、そして改変物を同じ条件で共有すること。社内研修資料に転載する場合や、商用製品のドキュメントに引用する場合は、この非商業条件が効いてくる。README はさらに、本書のライセンスは第三者ソースコードを覆わないと述べ、Claude Code は Anthropic の製品であり本書は独立した技術分析であって公式出版物ではないと明示している。法的助言ではないが、引用範囲と商用利用の可否は各自で確認する必要がある。保守の観点では、書籍はソースコードと違い上流の変更で自動的に壊れない。代わりに記述が古くなる。README の「阅读说明」が、機能フラグとツールの可用性はビルドと実行時設定に依存し、数値や所要時間の例は現行リリースの約束ではないと断っているのは、この陳腐化を先回りした記述である。付録 C は 89 個のフラグを 13 分類し、コンパイル時と実行時の種別、依存関係グラフまで載せる。上流の変更を追うコストを下げる工夫だが、追跡自体は読者側の作業として残る。

向かない場面と、代わりに何を読むか

本書が向かないのは、動くコードが欲しい場合である。教学用サンプルは含まれるが、リポジトリの主言語が Python と表記されている一方で本文のスタックは Bun と React/Ink であり、そのまま import して使える実装が揃っているわけではない。第 15 章は 6 ステップの実装ロードマップ、循環依存の解消、4 層の可観測性、安全脅威モデルを示すが、これは手順の提示であって完成品ではない。別の選択肢として、エージェントループを SDK として提供するフレームワークを使う道がある。違いは抽象度の方向である。SDK はループとツール呼び出しを関数として包み、利用者はその内部を知らずに組める。本書は逆に、ループの中身を開いて `while(true)` と yield イベントのレベルまで降りる。前者は速く動くものが要る場合、後者はなぜその設計なのかを判断したい場合に向く。両者は排他ではないが、本書を読んでも SDK の代替にはならないし、SDK を触っても権限パイプラインの 4 段階は見えてこない。

読む順番の実際

最初に付録 B と付録 C を開く。付録 B は 50 以上のツールを 12 分類し、readOnly、destructive、concurrencySafe の属性を付ける。付録 C は 89 個のフラグを 13 分類する。この 2 つで自分の関心がどの層にあるかを決めてから本文に入ると、15 章を頭から読むより速い。Claude Code を運用で使っているだけなら第 4 章と第 7 章、拡張したいなら第 8 章と第 11 章、複数エージェントを組むなら第 9 章と第 10 章、自作するなら第 15 章と付録 A の 16 モジュール依存ツリーという具合に分かれる。通読するなら README の推奨どおり 01 → 02 → 04 → 15 の順で骨格をつかみ、必要に応じて第 2 篇と第 3 篇に戻る。第 5 章の 6 層設定優先順位チェーンと第 6 章の MEMORY.md インデックスは、単独で読むと唐突に見えるので、基礎篇のあとに置くほうが理解しやすい。付録 D の 100 条の用語集は中英対照で章への相互参照が付いており、英語の Issue や PR を追うときの辞書として使える。

編集部の結論

Claude Code の内部構造を設計判断のレベルで理解したいエンジニア、とくに自前の Agent Harness を組もうとしている人には読む価値がある。逆に、動くコードやライブラリとして再利用できる実装を期待する人、商用製品に組み込む前提で読む人には向かない。読み始める前に確認すべきは 3 点。リポジトリのライセンス表記が不明で本文は CC BY-NC-SA 4.0 と README にあること、記述は「ソースから確認できる挙動」「アーキテクチャ推論」「教学用サンプル」の 3 種が混在し README 自身がその区別を求めていること、そして機能フラグとツールの可用性はビルドと実行時設定に依存するため本文の記述がそのまま現行版に当てはまるとは限らないこと。付録 C の機能フラグ表と付録 B のツール一覧を先に開き、自分の関心がどの章に落ちるかを決めてから 01 → 02 → 04 → 15 の順に読むのが現実的である。

公式情報源

1. Issues
2. lintsinghua/claude-code-book on GitHub
3. Project website
4. README