エージェントが読めるリポジトリと、抜け出せないハーネスを。
二つのスキルと一つのビューア。一つは手元にあるものを一つの契約に変換します。一つはリポジトリを読み、それが必要とする .claude/ ハーネスを組み立てます。目的に応じた席、実在するパスに紐づくルール、助言ではなく拒否するフック。ビューアはそのすべてをディスクから読み戻して採点します。
コード、調査、戦略、ドキュメントのどのリポジトリにも。安全性の下限はシェルスクリプトと終了コードなので、モデルを入れ替えても動きません。
考え方を一本の動画で
-
Agent Harness Bootstrap の概要 ~193秒
エージェントを実務に使うチームが繰り返し尋ねる問いと、それぞれに答える仕組み。日本語のナレーションと字幕付きです。
こんな覚えはありませんか。
どれもプロンプトの助言ではなく、ハーネスの中のファイルが答えます。
-
機能を一つ頼んだだけなのに、3 モジュール 14 ファイルに手を入れて
mainに強制プッシュした。これが答えますスコープを持つ席、パス単位のルール、そして着地する前に終了コード 2 でプッシュを拒否するフック。
-
セッションが圧縮され、三工程まで進めていた計画を忘れた。
これが答えますタスクの状態は短いチェックポイントと一緒にディスク上にあります。新しいセッションはそれを読んで続きから進めます。
-
バグを直すだけと言いながら
.envを開いた。これが答えますそれらのパスは読み取りが起きる前に拒否されます。開けなかったものを漏らすことはできません。
-
調査ノートのリポジトリなのに、キットはテストランナーとデータベース担当を入れてきた。
これが答えます最初の質問はリポジトリの目的です。調査・戦略・ドキュメントのリポジトリには、開発の席ではなく調査役・戦略役・執筆役と検証役が付きます。
-
README の誤字を直したあと、全テストとレビュアー三人を走らせた。
これが答えますスクリプトが差分を読んで検証を計画します。ドキュメントだけの変更にレビュアーの席は付かず、秘密情報の走査だけは常に走ります。
-
40 個目の生成ドキュメントが、いつの間にか仕様と矛盾している。
これが答えますすべての要件に安定した ID が付き、トレーサビリティグラフが乖離した文書を名指しします。
-
コードが何をしても通るテストを書いた。
これが答えますテストの期待値は受け入れ基準から取ります。コードを実行した結果からではありません。
-
自分の
.claude/が結局何を強制しているのか、もう分からない。これが答えますharness-view がディスクから読み取り、採点し、配線されていない部分をすべて名指しします。
それに答えるもの
-
spec-builder
アイデア、議事録、既存文書の山を、安定した要件 ID を持つ一つの契約に変換します。要件を勝手に作ることはなく、書かれていないことはフラグの立った未解決事項になります。
-
harness-bootstrap
リポジトリの目的を尋ね、中身を読み、それに合う
.claude/ハーネスを組み立てます。目的に応じた席、実在するパスに紐づくルール、遮断するフック。 -
harness-view
その結果を読み取って描画し、採点し、任意の部分を無効化できるようにします。モデルは介在しないので、ブラウザと CI の結果が食い違うことはありません。
受け渡しは四つ。ネットを順にたどると、各段階が通電する経路と、ディスクに書き出すものを示します。
デリバリーネット N1 金色は通電中の信号
段階 IN 入力素材
手元にあるものを、手元にある形のまま。
- 一行のアイデア、議事録、既存文書、既存のリポジトリ、空のリポジトリ
- PDF / Office ソースは、読めないファイルを見分けるルーターを通る
書き出し まだ何も - これは素材の段階
段階 S1 /spec-builder
あなたと AI の双方が読む、一つの契約。
- 安定した要件 ID により、後のすべての変更が発端まで遡れる
- ISO/IEC/IEEE 29148、ISO 25010、BABOK v3、C4、arc42 に沿って記述
書き出し docs/specs/ - FR-014、NFR-003、BR-002
段階 S2 /harness-bootstrap
まず目的、次にコードベース、そのうえで契約の周りにハーネスを組み立てます。
- 18 のエージェントから目的と証拠で席を選び、それぞれに完全なフロントマター - model、effort、tools、disallowedTools、ターン上限、memory、isolation、事前読み込みのスキル、席固有のフック
- 17 のルール、うち 10 は対象パスでのみ読み込み
- 27 のフックと 23 のコマンド。より厳格なフックは任意で有効化
書き出し .claude/ - エージェント、ルール、フック、コマンド、スクリプト、設定
段階 S3 デリバリーループ
計画、実装、検証、マージ - ハーネスが許す範囲の内側で。
- 手順の重さは変更の大きさで決まり、作業はメインセッションが行い、階層は確認の厚さを決める
- 検証は習慣で繰り返すのではなく、差分から計画される
- 終了コード 2 のフックは、実行前にツール呼び出しを止める
書き出し コードや文書と、再開の起点になるタスクボード
段階 S4 harness-view
ディスク上のハーネスを読み取って描画します。モデルは介在しません。
- すべての配線を示すフロー表示とグラフ表示。どのノードも開けるファイル
- 決定的な採点と、名指しされた検出結果
書き出し スコアと、問題ごとに名指しされた検出結果
手順の重さは変更の大きさで決まる
何かを割り当てる前に、その変更を四つの階層のどれかに置き、階層が確認の厚さを決めます。どの階層でもメインセッションが作業し、オーケストレーターは任意です。
ルーティング階層 N4 割り当ての前に階層が決まる
階層 Inline
質問、調べもの、あるいは一、二ファイルで全体が見える小さな編集。
- メインセッション自身が行う - サブエージェントもタスクファイルもなし
- 変えた箇所を一度だけ確認する
結果 セッション内で完了し、ブランチはやはりレビュー済み MR を通って着地する
階層 Direct
1 モジュール、巻き戻し可能、契約・スキーマ・認可・決済・インフラのいずれにも触れない。
- メインセッション自身が行う - サブエージェントなし
- 各受け入れ基準を自分で証明し、その方法を述べる
結果 割り当てもタスクファイルもなく、レビュー済み MR が一つ
階層 Standard
1 ドメイン、複数ファイル、あるいは背後に機能要件がある変更。
- ここでもメインセッションが、1 ドメインの中で行う
- 圧縮されたセッションを越える必要があるならタスクファイルを登録する
- テストは全件ではなく、変更箇所に対して
結果 ボード上のタスクと、レビュー済み MR
階層 Guarded
スキーマ・認可・金銭・公開契約・マイグレーション・デプロイ・個人データに触れる。
- メインセッションが作業し、その後に独立した読み取り専用のレビュアーが読む - 必須で、省略できない
- 新しい FR では、実装の前に
spec-guardianがスコープを固定する /implement-fr FR-NNがその一連の流れ- オーケストレーターは任意: 頼んだときだけ、複数のドメインやリポジトリにまたがるミッションに使う
結果 テストと独立レビュー、そのどれも省略できない
-
検証は差分から計画される
.claude/scripts/verify-plan.pyが変更の触れるパスを読み、どのテストとレビューが要るか、省いたゲートはなぜ省いたかを示します。秘密情報の走査は常に走ります。セキュリティレビューは危険なパスだけ。E2E は名前の付いたフローのパスが変わったときだけ。ドキュメントだけの変更にレビュアーの席は付きません。同じ内容ですでに通ったレビューやテストは起動フックが拒否し、やり直しを求められるのは人間だけです。 -
委任には上限がある
委任するのはオーケストレーターだけで、どこまで深く、どこまで広く展開できるかは
settings.jsonのCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHとCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで決まります。プロンプト任せにはしません。 -
タスクの状態はコマンド一つで動く
.claude/scripts/task.pyがファイル、フォルダ、ボードの行をまとめて動かし、行を読み直して確かめます。ボードの手編集はフックが拒否します。各タスクは短いチェックポイント - 次の一手、最後にグリーンだったコミット、未解決の質問 - を持つので、再開時に読むのはログ全体ではなく三行です。古いログ行はアーカイブに畳まれます。
ロースターは目的に合わせて決まる
コード、調査、戦略、ドキュメント、あるいはその組み合わせ。目的が土台を決め、契約と実在するモジュールが残りを決めます。リポジトリを選ぶと、ロースターが確定します。
テーラー N2 証拠が入り、ロースターが出る
- orchestrator
- checker
- writer
- researcher
- strategist
- spec-guardian
- ba-analyst
- code-reviewer
- security-reviewer
- debugger
- devops
- qa-test
- data-modeler
- db-engineer
- db-seeder
- history-tracker
- merge-manager
- reviewer
18 席のうち 3 席を導入 15 席は空のまま
理由 ドキュメントの目的には執筆役と読み取り専用の検証役が付く。コードがないので開発・テスト・コードレビューの席はない
18 席のうち 4 席を導入 14 席は空のまま
理由 戦略には計画の二席と、提言をあえて攻撃する検証役が付く
18 席のうち 7 席を導入 11 席は空のまま
理由 契約にもツリーにもデータベースやテストの席を正当化するものがない。実在モジュールごとに開発エージェントが一つ付く
18 席のうち 9 席を導入 9 席は空のまま
理由 データベースがデータモデラーを呼び込み、テストを選んだので qa-test が入る
18 席のうち 15 席を導入 3 席は空のまま
理由 長期の作業が計画の二席と履歴係を、並行する PR がマージ管理役を正当化する
-
キットはすべてを導入する
リポジトリを一行も読まないうちに全席。全席分のコンテキストを払い、持ち主のいない席は一般論の助言になります。
-
実行が導入するのは 18 席のうち 3〜17 席
ルールは実在するパスにスコープされるため、ルール本文の 75% が既定セッションの外に出ます。
scripts/check_numbers.pyとbenchmark/benchmark.py --jsonによる算出
要求が遮断される様子を見る
エージェントとリポジトリの間には五つの層があります。要求を経路に流して、どの層が拒否するかを確かめてください。
制御経路 N3 珊瑚色は拒否
層 1 で停止 拒否リスト
git push --force origin main
結果 権限拒否 - 呼び出しはシェルに届かない
層 2 で停止 遮断フック、終了コード 2
cat .env
結果 exit 2 - フックが拒否し、その理由がモデルに返る
層 3 で停止 生成境界
サブエージェントが別のサブエージェントを起動しようとする。
結果 却下 - 委任するのはオーケストレーターだけ、それも上限の内側で
五層すべてを通過 レビュー保留
edit src/payments/charge.ts
結果 パスが実在するので決済ルールが読み込まれ、ゲートがセキュリティレビューを計画する
五層すべてを通過 許可
npm test
結果 実行される - 下限は普段の作業の邪魔をしない
-
1 - 拒否リスト
settings.jsonに宣言します。エージェントの推論が始まる前に、クライアント自身が呼び出しを拒否します。 -
2 - フック
終了コード 2 のフックは呼び出しを止めて理由を返すので、モデルは何をしてはいけないかを知ります。任意で有効化するフックはさらに広く守ります。取り消せないシェルコマンド、未知のネットワーク宛先、履歴に入る巨大ファイル、レビューを経ない依存関係の変更、既定ブランチにあるマイグレーションの編集、そして証拠のない「完了」。
-
3 - 生成境界
誰が誰を起動できるかはプロンプトではなくトポロジーで固定され、設定で上限が付きます。
-
4 - パススコープのルール
ルールは対象パスでのみ読み込まれるので、背景ノイズになりません。
-
5 - レビューゲート
レビューはフロー上の一工程で、差分に合わせて規模が決まり、対象を編集できない席が担います。
モデルには一切問い合わせません。ガードレールはシェルスクリプトと終了コードなので、結果がモデルに左右されることはありません。安いモデルで変わるのは作業の質とレビューの深さ、すなわち上限であり、この評価はそれを測っていません。
厳格・長期セッション・データベースのフックを有効にしたハーネスで、フック形式ごとに 314/314 - py -3.13 eval/guardrail_eval.py で自分で再実行できます
harness-view が読み戻す
ディスク上のハーネスを読み、実際にどう配線されているかを見せる小さな Rust バイナリです。モデルもネットワークも判断も介在しません。
ビューア経路 N5 ディスクから読み、同じ道で書き戻す
ここにモデルの意見はありません。scan はバイト単位で安定したグラフ - ソート済み、タイムスタンプなし - を書き出し、その下の三つのコマンドは同じファイルの三通りの読み方です。
Assess タブと CI の harness-view assess は同じエンジンです。
ページが加える変更は、すべて一つの狭い扉から戻ります。サーバーは 127.0.0.1 にのみバインドし、変更を伴うリクエストは same-origin でなければなりません。
-
コードのリポジトリに限らない
テストもコードグラフもない調査・執筆のハーネスも同じ基準で読み取り、採点します。 orchestrator-kit の導入 - ボード、ガードフック、起動許可リスト - も読みます。
-
すべてのフィールド、すべてのイベント
文書化されたサブエージェントのフロントマターはすべて。
settings.jsonと席自身のhooks:から、あらゆるイベントのフック。skills:の事前読み込みとAgent(a, b)の許可はエッジとして描きます。 -
ボードの食い違いを名指し
フォルダ、状態、ボードの行が食い違うタスクはグラフ上で
DRIFTと表示され、ボード健全性の減点になります。
コマンド
harness-view # 現在のフォルダを配信し、ブラウザを開く
harness-view scan [path] # .claude/state/harness-graph.json を書き出す
harness-view serve [path] [--port 7420] # ローカル UI
harness-view watch [path] # .claude/・docs/・.agent-base/ の変更で再構築
harness-view assess [path] [--json] # 採点し、high があれば exit 1安全性モデルと全エンドポイントを含む詳細は tools/harness-view/README.md にあります。
このスコアが測っていないもの。ルールが有用なことを言っているか、フックが主張どおりに遮断するかは判断しません。クリーンな結果は、エンジン内のすべてのルールを通過したという意味であって、ハーネスが良いという意味ではありません。
導入する
更新が実際に機能するプラグイン経路を先に置いています。リリース zip は、オフラインでバージョンを固定する経路です。
Claude Code
プラグイン経路
/plugin marketplace add nguyenhx2/agent-harness-bootstrap
/plugin install harness-bootstrap@agent-harness-bootstrap
/plugin install spec-builder@agent-harness-bootstrap片方だけでも、両方でも導入できます。追加の設定は不要です。
Codex
プラグイン経路
codex plugin marketplace add nguyenhx2/agent-harness-bootstrapそのうえで Codex CLI の /plugins を開き、どちらか、または両方のスキルを導入します。
Cursor、および Agent Plugins 対応クライアント
プラグイン経路
git clone https://github.com/nguyenhx2/agent-harness-bootstrap
cp -r agent-harness-bootstrap/plugins/harness-bootstrap ~/.cursor/plugins/local/その後ウィンドウを再読み込みします。VS Code、Copilot、Kiro も同じディレクトリを読みます。どのクライアントで何を検証したかは docs/PLUGIN.md にあります。
または リリース zip
オフライン・固定
# 両方のスキル、ダウンロードした版に固定
unzip agent-harness-bootstrap.zip -d ~/.claude/skills/Python 3 が必要です。各リリースにはアーカイブ検証用の SHA256SUMS が添付されます。
ビューア
任意
各リリースには Windows・macOS・Linux 向けの単体実行ファイルが添付され、Web UI も埋め込まれています。 Windows ではリポジトリに置いてダブルクリックするだけです。ハーネス側がこれを必要とすることはありません。
cargo install --path tools/harness-view # 自分で構築する場合動かす
どちらのスキルも、まずあなたが書いた言語でヒアリングします。一画面の計画を承認するまで、何も書き出されません。
最初の実行
/spec-builder # アイデアから始めるなら、まず契約を書く
/harness-bootstrap # このリポジトリの .claude ハーネスを構築(または更新)する最初の質問は、リポジトリが何のためにあるかです。すでにコードがあれば分析が残りを埋めておくので、ゼロから入力するのではなく検出結果を訂正する作業になります。決して推測しないのはガバナンスの質問だけ - モデル主権、データ所在地、ライセンス、ゲートされる操作。急いでいるならそう伝えれば、安全な既定値のない質問だけになります。
日々の運用
/new-task "短いタイトル" # task.py を通してタスクを登録する
/implement-fr FR-014 # Guarded の流れを端から端まで
/review-changes # verify-plan.py が規模を決めるブランチゲート
/secret-scan # 検出されたらローテーションまで停止
/task-resume TASK-007 # ログ全体ではなくチェックポイントを読む新しいバージョンへ移る
照合であって、上書きではない
/plugin update harness-bootstrap@agent-harness-bootstrap # スキル
/harness-bootstrap:harness-update # このリポジトリのハーネス更新はコードを読み直し、記録済みの回答でスキャフォルダを再実行し、すべてのファイルを三つの状態のいずれかとして報告します。
- ADDED
- 新しいスキル版で増えたもの。書き込まれます。
- KEPT
- 両側で同一。そのまま残ります。
- CONFLICT
- あなたが編集したもの。そのまま残り、一件ずつ解消するキューに載ります。
無効化した制御は無効のまま残り、エージェントのスコープや coding-standards.md などの執筆済みの内容には、そのキューを通してしか触れません。
ハーネスを狭く変える
ブートストラップが書くのは初稿です。どのコマンドも差分を見せ、確認したものだけを適用し、理由を docs/context/tool-changelog.md に記録します。
-
/harness-tune
実際に起きたこと - 実行アーカイブ、拒否、リトライ上限、verify-plan のログ - を読み、ダイヤル一つにつき最大四つまでの変更を順位付きで提案する。デプロイ権限、強制プッシュの扱い、起動許可リスト、上限、レビューの深さ。適用後は一つずつ確認する。
-
/harness-toggle
ルール・コマンド・フック・席を、削除せずに一つだけ無効化する。保護された制御には確認フレーズの入力が必要で、有効化はゲートされない。
-
/agent-permissions
一つの席にツールを一つ足す、あるいは減らす。レビュアーが書き込み権限を得ることはなく、減らす方向は検査を省く。
-
/new-skill
繰り返す作業がそもそもスキルであるべきかを判断する。そうなら、テンプレートから雛形を作り、六種類のトリガーケースを書き、
skill-check.pyで検査する。 -
/skill-wire
導入済みのスキルを、必要とする席の
skills:事前読み込みに配線する。配線の前にスキルの全ファイルを読み直す。 -
/board-audit
誰も進めていないタスク、食い違う状態、どのタスクも参照しないブランチを、読み取り専用で洗い出す。
-
/code-graph
コミットされるモジュール境界マップ。どのモジュールがどれを import してよいか、モジュールごとの担当つき。モジュールをまたぐ新しい import は、それを加えた編集の時点で指摘される。
-
/docs-graph
すべての要件 ID と、その定義場所・参照元。表示される孤立 ID は、誰も予定していない作業か、どこも指していない参照。
どのコマンドも、レビュアーに書き込み権限を与えること、オーケストレーター以外の席に起動を許すこと、レビューゲートを外すことはしません。