harness-books を読む前に: Claude Code と Codex の「制約の置き場所」をどう比較するか

このリポジトリが解こうとしている問題は「モデルの正しさ」ではない

README の Core Claims は、問いの立て方をはっきり示している。コードを書くモデルを端末、リポジトリ、権限系、チームのワークフローの中に置いたとき、システム全体を「bounded, continuous, accountable for consequences」に保つものは何か、という問いである。ここで扱われる危険は、モデルが時々間違えることではなく、結果を処理する構造がシステムに存在しないことだと README は書く。つまり対象読者は、プロンプトの書き方を改善したい人ではなく、エージェントをチームの工程に組み込もうとしている設計者やテックリードである。プロンプトエンジニアリングの延長ではなく、制約構造が実行をどう組織するかという別の層を扱う、というのが著者の立場だ。

2冊は同じ題材を扱うが、観察対象の粒度が違う

Book 1 は Claude Code を観察対象に据え、ランタイム構造に集中する。制御プレーン、クエリループ、ツール権限、コンテキスト管理、復旧経路、マルチエージェント検証、チームルールといった要素が、なぜシステムに必要になるのかを追う構成である。Book 2 は Claude Code と Codex を並べ、それぞれが秩序をどこに置いているかを問う。README の表現では、一方はランタイムの規律から出発し、もう一方はより構造化された制御層から出発する。両方とも成立しうるが、権限の配分が異なる、というのが比較の軸になる。同じツールを2冊で扱うため重複を想像しがちだが、Book 1 は単一システムの内部構造、Book 2 は2システム間の設計判断の差、という別の問いを立てている。

章立ては「器官」という比喩で一貫している

Book 1 の目次は、序文、Chapter 1 から Chapter 9、付録 A から C という構成である。Chapter 2 はプロンプトを制御プレーンとして扱い、Chapter 3 はクエリループをエージェントシステムの心拍と位置づけ、Chapter 4 はツール、権限、割り込みを扱う。Chapter 5 はメモリ、CLAUDE.md、compact を予算管理の仕組みとして論じ、Chapter 6 は障害後の継続、Chapter 7 はマルチエージェントと検証、Chapter 8 はチーム導入、Chapter 9 は10の原則で締める。付録 C は「Source Map」として、各章がどのファイルに根拠を置くかを示す。README は「not meant to walk line by line through the source code」と明言しており、行単位のコード解説ではない。ただし付録 C がある以上、主張と実装の対応を読者が自分で確認できる経路は用意されている。

読み始める位置は目的で分かれる

README は3つの読み方を提示している。全体像を先に欲しい場合は Book 1 から Book 2 へ進む。コーディングエージェントのツールに既に慣れており、アーキテクチャの分岐点を直接知りたい場合は Book 2 から入る。結論だけ欲しい場合は Book 1 Chapter 9 と Book 2 Chapter 7 を読む、とされている。この3番目の経路は、評価のためにまず全体を斜め読みしたい場合に実用的である。逆に、Book 2 の目次は README 上では「The Harness Design Philosophies of Clau」で切れており、Book 1 のように章単位の一覧は確認できない。Book 2 の中身を事前に把握したいなら、オンライン版かリポジトリ内の該当ディレクトリを直接見る必要がある。

実行するものではなく、読むものとして配布されている

このリポジトリの Primary language は Python と表示されているが、README が示す成果物は書籍である。オンライン版は harness-books.agentway.dev で英語版と中国語版の両方が公開され、PDF も exported ディレクトリ配下に置かれている。Book 1 の本文は book1-claude-code/locales/en/ 以下に Markdown として並び、ファイル名は chapter-01-why-harness-engineering.md のように章番号と主題を組み合わせた形式である。つまり Python という表示は、リポジトリ内のビルドや変換スクリプト類に由来すると推測されるが、README にはその実行手順も依存関係も書かれていない。ローカルでビルドする用途を想定した文書ではなく、読むための文書だと考えるのが素直である。

向かない用途と、確認できない部分

第一に、動くコードやライブラリを探している人には向かない。README は設計思想の書であり、ソースコードの逐行解説ではないと明記している。第二に、特定バージョンの挙動を正確に知りたい場合、書籍はスナップショットであり、Claude Code や Codex の更新に追従する保証は README からは読み取れない。第三に、ライセンスが不明である。リポジトリ情報では License が unknown とされており、README にも本文の再配布条件やコード部分の扱いは書かれていない。社内資料へ引用・翻訳・再配布する場合は、リポジトリ直下の LICENSE ファイルの有無と、agentway.dev 側の表記を自分で確認する必要がある。ここは法務判断ではなく、事実確認の話である。

比較対象として何を読むか

同じ領域の公開資料として、Anthropic のエンジニアリングブログや Claude Code の公式ドキュメントがある。違いは粒度と視点である。公式ドキュメントは特定ツールの機能と設定を記述する。harness-books は、なぜその機能群が必要になるのか、制約をどの層に置くかという設計判断を扱う。たとえば権限モデル一つをとっても、公式ドキュメントは許可設定の書き方を示すが、本書はそれを制御プレーンの一部として位置づける。逆に、具体的な設定キーやコマンドの正確な一覧は公式ドキュメントに軍配が上がる。両者は競合せず、設計の言語化を本書、実装の詳細を公式ドキュメント、という分担になる。

メンテナンスと更新のコスト

リポジトリは Archived ではなく、最終 push は 2026-04-19 と記録されている。ただし Releases は取得されておらず、バージョン番号付きの配布は確認できない。書籍という性質上、更新は章の改訂として行われる可能性が高いが、README に変更履歴や互換性の説明はない。読む側のコストは、特定バージョンに固定されないぶん、記述が現在のツール挙動と一致するかを自分で照合する手間である。逆に、設計原則として書かれた部分は、ツールの細部が変わっても参照し続けられる。コストを見積もるなら、機能仕様として読むか設計論として読むかで、必要な検証作業の量が変わる。

編集部の結論

自作ハーネスの設計判断に行き詰まっている人、特にクエリループや権限モデルの層で何を決めるべきか言語化したい人には向く。逆に、動くコードやライブラリとしての機能を期待する人、PDFやオンライン版だけ読めば済む人には不要である。採用前に確認すべきは、リポジトリ直下に LICENSE ファイルが見当たらない点と、Book 2 の目次が README 上では途中で切れている点の2つ。判断材料としては、Book 1 Chapter 9 と Book 2 Chapter 7 を先に読み、そこで扱われる論点が自分の設計課題と一致するかを確かめるのが最も早い。

公式情報源

1. Issues
2. Project website
3. README
4. wquguru/harness-books on GitHub