助言ではなく、遮断するガードレール。

こんな覚えはありませんか。

実際のリポジトリに AI エージェントを入れたことがあるなら、このうち三つ以上には 心当たりがあるはずです。どれも助言ではなく、このリポジトリの中の何かが答えます。

• 機能を一つ頼んだだけなのに、3 モジュール 14 ファイルに手を入れて main に強制プッシュした。

  これが答えますスコープを持つエージェント、パス単位のルール、そして着地する前に終了コード 2 でプッシュを拒否するフック。

• セッションが圧縮され、三工程まで進めていた計画を忘れた。

  これが答えますタスクボードとセッションログはディスク上にあるので、新しいセッションは前回止まった場所から再開します。

• バグを直すだけと言いながら .env を開いた。

  これが答えますそれらのパスは読み取りが起きる前に拒否されます。そもそも開けなかったものを漏らすことはできません。

• 40 個目の生成ドキュメントが、いつの間にか仕様と矛盾している。

  これが答えますすべての要件に安定した ID が付き、トレーサビリティグラフが乖離した文書を名指しします。

• キットがエージェント 40 個とスキル 100 個を入れたが、うちのプロジェクトにはどれも要らなかった。

  これが答えますロースターは契約と実在するモジュールから導かれます。16 席のうち 7〜15 席で、既定ですべてが埋まることはありません。

• コードが何をしても通るテストを書いた。

  これが答えますテストの期待値は受け入れ基準から取るものであって、コードを実行した結果から取るものではありません。

• スキャンした PDF を「読んで」、拾えた三単語から仕様書を書いた。

  これが答えますすべてのソースが、実際に読めるリーダーへ振り分けられます。1 ページあたり 80文字未満のページはスキャンと判定されて画像認識に回り、どうしても読めないファイルは推測ではなく、名前の付いた未解決事項になります。

• 自分の .claude/ が結局何を強制しているのか、もう分からない。

  これが答えますharness-view がディスクから読み取り、採点し、配線されていない部分をすべて名指しします。

それに答えるもの

二つの Claude Code スキルと一つのビューア。どれか一つだけでも使えます。

• spec-builder

  アイデア、議事録、既存文書の山、あるいは空のリポジトリを、国際規格に沿った一つの契約に変換します。 要件 ID は安定していて、要件を勝手に作ることはありません。書かれていないことは、フラグの立った 未解決事項になります。

• harness-bootstrap

  まずコードを読み、それに合う .claude/ ハーネスを組み立てます。スコープが明示された エージェント、実在するパスに紐づくルール、そして助言ではなく遮断するフック。

• harness-view

  その結果を読み取って描画し、採点し、任意の部分を無効化できるようにします。モデルは介在しないので、 ブラウザと CI の結果が食い違うことはありません。

下限はモデルに依存しません。ガードレールはシェルスクリプトと終了コードなので、全エージェントを Opus から Haiku に替えても安全性の結果はバイト単位で同一です。python eval/guardrail_eval.py がそれを示します。フック形式ごとに 112/112、両形式で 224/224。

全体を一本の動画で

7 本の解説クリップ。すべてキャプション付きで、このページ上でそのまま再生できます。 ダウンロードも音声も不要です。

• 完全なソリューション ~63秒

  プロダクト全体を 1 本のクリップで。4 つの課題、そして spec-builder が契約書を書き、 harness-bootstrap がハーネスを構築し、その内側でデリバリーループが回り、成果に至るまで。 各課題は解決するたびに赤から緑へと目に見えて切り替わります。最後は harness-view が存在意義そのものの 問い - 実際に正しく配線されているとどう分かるか - に答えて締めくくります。

  HTML アニメーションを開く MP4 を開く

導入する

まずプラグイン経路から。更新が実際に機能するのはこちらなので、先に置いています。 リリース zip は、オフラインでバージョンを固定する経路として引き続き正式にサポートされます。 どちらでも、次のセッションからスキルが使えます。

/plugin marketplace add nguyenhx2/agent-harness-bootstrap
/plugin install harness-bootstrap@agent-harness-bootstrap
/plugin install spec-builder@agent-harness-bootstrap

codex plugin marketplace add nguyenhx2/agent-harness-bootstrap

git clone https://github.com/nguyenhx2/agent-harness-bootstrap
cp -r agent-harness-bootstrap/plugins/harness-bootstrap ~/.cursor/plugins/local/

# 両方のスキル、ダウンロードした版に固定
unzip agent-harness-bootstrap.zip -d ~/.claude/skills/

cargo install --path tools/harness-view   # 自分で構築する場合

新しいバージョンへ移る

更新の対象は二つあり、それぞれ独立しています。手元のスキルと、すでにリポジトリへ 展開済みのハーネス。どちらも、あなたが行った作業を上書きしません。

/plugin update harness-bootstrap@agent-harness-bootstrap
/plugin update spec-builder@agent-harness-bootstrap

/harness-bootstrap:harness-update

動かす

どちらのスキルも、何かを書き出す前に、あなたが書いた言語でヒアリングします。 一画面の計画を承認するまで、何も生成されません。

/spec-builder           # アイデアから始めるなら、まず仕様書を書く
/harness-bootstrap      # このリポジトリの .claude ハーネスを構築(または更新)する

/new-task "短いタイトル"    # マスタープランにタスクを登録する
/implement-fr FR-014       # 要件を一つ、端から端まで計画して実装する
/review-changes            # ブランチ差分全体に対するレビューゲート
/secret-scan               # 検出されたらローテーションまで停止
/task-resume TASK-007      # 圧縮やクラッシュの後、記憶ではなくファイルを信じて再開

ブートストラップ後の調整

ブートストラップが書くのは最終判断ではなく初稿です。出来上がったハーネスを 後から変えるコマンドが八つあり、どれも意図的に狭く作られています。差分を見せ、確認を取り、選ばれた ぶんだけを適用し、理由を docs/context/tool-changelog.md に記録します。そしてどれもが 何かを拒否します。必要になる前に読んでおく価値があるのは、むしろその拒否の側です。

• /harness-tune

  こんなときに安全性の下限がチームの実態に対して厳しすぎる、あるいは 緩すぎる。制御そのものを外すのではなく、つまみを回したいとき。

  確認一回につきつまみは一つです。デプロイコマンドを誰が実行してよいか、force-push・ rm -rf・データベースリセットへの姿勢、spawn 許可リスト、席ごとのターン上限と 試行回数の上限、レビューをどこまで深く回すか、エージェント履歴をどれだけディスクに残すか。 上限を下げるのは無償で、上げるときは増えるコストが提示されます。コードレビューゲートの削除は 拒否されます - それはチューニングではなく別のリポジトリです。制御をまるごと止めるのも チューニングではなく、次のコマンドの仕事です。

• /harness-toggle

  こんなときに特定のルール・コマンド・フック・席が一つ邪魔で、削除せずに 止めたいとき。

  動かすのはスクリプトだけです。ファイルを .claude/disabled/ に退避し、 settings.json の登録を外し、一行の理由を .claude/disabled.json に 書きます。このファイルはコミットされるので、チームで共有され、再スキャフォールドでも尊重されます。 さらにグラフを再生成し、止めた項目がグレー表示になります。保護された制御(シークレット保護、 spawn 保護、レビュー席)は、確認フレーズをバイト単位でそのまま入力しなければ動きません。 有効化に確認は要りません。制御を戻すことは、この段階が存在する理由のリスクではないからです。

• /harness-update

  こんなときにスキルを新しいバージョンに上げた、あるいは以前の形に合わせて 組んだハーネスの下でコードベースが動いたとき。

  まず現状のコードを読み直します。存在しないパスにスコープされた開発エージェントは、何も指して いない席だからです。そのうえで記録済みの回答でスキャフォルダを再実行し、すべてのファイルを ADDED・KEPT・CONFLICT のいずれかとして報告します。CONFLICT は一件ずつ手で解決するものです。 その後トグル状態を再適用するので、意図して止めた制御が更新で復活することはありません。移植先も インテイクが記録した Cursor / Codex だけで、再検出はしません。

• /agent-permissions

  こんなときにある席にツールを一つ足したい - あるいは、より多くの場合、 一つ減らしたいとき。

  一つの席の tools: 行だけを編集します。編集前に、ロースターを安全に保つ不変条件と 突き合わせます。レビュアーが Edit や Write を得ることはありません。編集するゲートは、独立性を 失った開発エージェントだからです。spawn ツールを持つのはオーケストレーターだけ。ワイルドカードの 付与もありません。model: と effort: は権限ではないのでここでは拒否され、 ロースターとコストモデルの話に回されます。剥奪は確認を飛ばします。狭めるのは常に安全だからです。

• /board-audit

  こんなときにステータスを信じて次へ進む直前、あるいはボードの知らない どこかで作業が進んでいる気配があるとき。

  まずボード自身のフロントマターと依存関係の連鎖を検証します。以降のすべての走査が、整形式の タスクファイルを前提にしているからです。そのうえで、誰も進めていない Active タスク、誰も回収して いない完了済みエージェント実行、マスタープランと食い違うステータス、上限を超えてなお Active な 試行回数、どのタスクも参照していないワークツリーとブランチ、解除条件も担当者も書かれていない Blocked タスク、そして古くなったコードグラフを探します。読み取り専用です。報告はしますが、 直すのはあなたかオーケストレーターです。

• /code-graph

  こんなときに変更がモジュール境界をまたぐとき、あるいは陳腐化ログが空で なくなった瞬間。

  ファイルを一つ読んでも答えられない問い - このモジュールを変えたら何が壊れるか - に答えます。 モジュール、ファイル、参照回数付きの import エッジ、そしてロースターのスコープから割り出した モジュールごとの担当。オーケストレーターは割り当て前に対象の被参照数を確認し、多ければ依存側を 指示に明記させます。限界も正直に。組み込みの抽出は静的なので、エッジが無いことは孤立の証拠では なく、証拠が無いだけです。

• /docs-graph

  こんなときに仕様を変更した後、あるいはどの要件も求めていないものが 作られている疑いがあるとき。

  コードグラフの対になるトレーサビリティ側で、どちらも他方の代わりにはなりません。すべての ID - FR、NFR、BR、ADR、TASK - と、それを定義する文書、参照するすべての文書、そしてネットワーク不要で ブラウザから開ける自己完結のインタラクティブグラフ。spec-guardian は差分が名乗る ID を これと突き合わせます。グラフが知らない要件を名乗る実装は、でっち上げた要件を実装しています。 孤立した ID は未着手の作業か、死んだ参照のどちらかで、報告はどちらなのかを述べます。

• /skill-wire

  こんなときにスキルを入れたのに何も使っていないとき。スキルは、どの席が それを使うのか指示されるまで誰の役にも立ちません。

  導入時のレビューを信用せず、配線時にスキルの全ファイルを読み直します。更新で本文が書き換わって いる可能性があるからです。プラグイン経由で入ったものなら束ごと読みます。プラグインのフックや MCP サーバーは、どのスキルを配線したかに関係なく動くからです。.claude/・ settings.json・フックを編集させるスキルは拒否します。レビュアーには読み取り専用の スキルだけを配線します。書き込みを促す指示は、ツール付与に関係なく従われてしまうからです。 配線解除はいつでも可能で、どちらの向きも記録されます。

八つとも、ブートストラップがリポジトリに書き込むと同時に、プラグインにも /harness-bootstrap:harness-tune のような形で同梱されます。だから他の誰かが用意した プロジェクトでも動きます。何を承認しても決して起きないことが三つ。レビュアーが書き込み権限を 得ることはなく、起動するのはオーケストレーターだけで、コードレビューゲートは削除できません - 範囲を変えられるだけです。

ロースターは導入するものではなく、決まるもの

契約と、実在するモジュールが、誰の席を用意するかを決めます。 プロジェクトの形を選ぶと、ロースターが確定します。

要求が遮断される様子を見る

エージェントとリポジトリの間には五つの層があります。要求を経路に流して、 どの層が拒否し、エージェントに何が返されるかを確かめてください。

• 1 - 拒否リスト

  settings.json に宣言します。エージェントの推論が始まる前に、クライアント自身が 呼び出しを拒否します。

• 2 - 遮断フック

  10 の遮断フック。終了コード 2 のフックはツール呼び出しを止めて理由を返すので、 モデルは「気をつけて」ではなく、何をしてはいけないかを知ります。

• 3 - 生成境界

  誰が誰を起動できるかはプロンプトではなくトポロジーで固定されます。委任するのは オーケストレーターだけで、サブエージェントは第二波を起こせません。

• 4 - パススコープのルール

  ルールは対象パスでのみ読み込まれます。だからルール本文の 62% が既定セッションの外に出て、 ルールが背景ノイズにならずに済みます。

• 5 - レビューゲート

  レビュー、セキュリティレビュー、マージ管理はそれぞれ予算を持つ席です。ブランチゲートは プロンプト内の提案ではなく、フロー上の一工程です。

Opus を Haiku に入れ替えても、評価結果はバイト単位で同一です。 それがこの設計の要点で、下限はシェルスクリプトと終了コードによって強制されるため、どのモデルが 動かしているかに依存しません。安いモデルで変わるのは、書かれるコードの質とレビューの深さ、 すなわち上限であり、この評価はそれを測っていません。

フック形式ごとに 112/112 - ブロック必須 40 件、許可必須 67 件。 py -3.13 eval/guardrail_eval.py で自分で再実行できます

harness-view - ネイティブビューア

スキルが書き出すのと同じ .claude/state/harness-graph.json 契約を読み、 実際にどう配線されているかを見せる小さな Rust バイナリです。ファイルを読んで関係を報告するだけで、 モデルもネットワークも判断も介在しません。ブラウザと CI が同じリポジトリについて食い違うことはありません。

今回のリリースで新しくなったもの

• ロースターエディタ

  エージェントを選ぶと Edit roster が現れ、席の model・effort・tools・description を フロントマターの手編集ではなくピッカーで変更できます。書き込みは変更されたキーだけに触れ、 触れていないキーは位置もコメントも空行もそのまま、CRLF は CRLF のままです。名前の変更は無視ではなく 拒否されます。それはフィールドの編集ではなく、ルーティングテーブルの変更だからです。

• 編集できるリファレンス

  ピッカーの裏にあるカタログです。4 つのベンダー - Claude Code、OpenAI Codex、Gemini CLI、Z.AI GLM - のモデルとツールが、それぞれ verified フラグと用途のメモを持ちます。一次情報で確認できな かったものは、ピッカーの中を含め、現れる場所すべてで unverified と表示されます。カタログはあなたのもので、 編集はリポジトリごとに .claude/state/references.json に保存され、同梱シードの上に マージされるため、スキルを更新しても残ります。オーバーライドでラベルは訂正できますが、 unverified なモデルを verified に昇格させることはできません。

• 編集できるコマンドステップ

  コマンドの番号付きステップがカードの連なりとして描かれ、ドラッグで並べ替え、任意の位置に挿入、 その場で無効化、タイトル変更ができます。保存はまとめて一度、Revert はすべて破棄。保存が書き換えるのは ステップが占める行範囲だけで、フロントマター、見出し、グループ間の文章はバイト単位でそのまま通過します。 編集していないステップは届いたバイトのまま書き戻され、それは主張ではなくテストです。

• メンションとマークダウン描画

  ステップに入力すると、参照しようとしている名前 - エージェント席、ルールファイル、フック名、 リポジトリ内の実在パス - が候補として出ます。表・リスト・コードブロックであるステップはそのまま 描画されるので、ステップ 4 のルーティングテーブルは表として読めます。開いて編集すればマークダウン ソースに戻ります。リポジトリ由来のテキストは createElement と textContent だけを通り、リンクは http(s) に限られます。

• 独自ダイアログ

  確認や編集はブラウザのプロンプトではなくビューア自身のダイアログなので、中身に合わせた大きさにでき、 合わないときはリサイズできます。

• 二段階の実行時トグル

  ルール、コマンド、フック、ロースター席は詳細パネルから無効化でき、契約は /harness-toggle と同じです。HARD 保護の制御は確認フレーズを一字一句そのまま入力する必要が あり、トリムも大文字小文字の吸収もしません。SOFT 保護のものと、すべてのエージェント席は明示的な了承を 求めます。有効化はゲートされません。制御を戻すことは、この段階分けが防ごうとしているリスクではないからです。 記録は .claude/disabled.json。コミットされ、ソートされ、日付は入りません。

harness-view                              # 現在のフォルダを配信し、ブラウザを開く
harness-view scan   [path]                # .claude/state/harness-graph.json を書き出す
harness-view serve  [path] [--port 7420]  # ローカル UI
harness-view watch  [path]                # .claude/ や docs/ の変更に応じてグラフを再構築
harness-view assess [path] [--json]       # 採点し、high があれば exit 1

このスコアが測っていないもの。ルールがあなたのコードベースにとって有用なことを言っているか、 エージェントのスコープがコードの実際の構成と合っているか、存在するフックが主張どおりに遮断するか - いずれも測っていません。クリーンな結果は、エンジン内のすべてのルールを通過したという意味であって、 ハーネスが良いという意味ではありません。