設計の理由

各節で、課題、採用した方法、参考元、設計上の境界を説明します。すべて既存のエコシステムの実践に基づき、前例のない独自機構は採用しません。

前提は AI 導入後の開発プロセスと検証責任について（HackMD、中国語）にまとめています。AI で成果を作る速度は上がっても、検証の責任は残ります。チームには、作る速さに加えて検証できる量の管理が必要です。

コントラクトをコードで作成し、一度の承認で実行する

課題：作業指示が曖昧だと、モデルが要件を補って解釈し、実装後に認識のずれが判明することがあります。承認の根拠が残っていなければ、誰が何を許可したかも確認できません。

方法：start は作業指示、範囲、予算、テストコマンドを計画として固定し、カードを表示します。承認はその原文と SHA-256 に対するもので、後の編集では変わりません。承認記録は変更できず、欠落、不正、期限切れ（24 時間）、使用済みなら実行しません。コントラクトはカードの前に各ブロックの転記と完了条件の分割で作り、モデルは呼び出しません。その SHA-256 が承認対象を示します。必須内容の不足、不正なリスト項目、未回答の質問があれば、カードの前で項目ごとに説明して停止します。実装中に writer が判断を求めた場合は、作業を止めて結果ファイルに質問を残します。

参考元：Terraform の plan -out → apply <plan> は保存済み計画だけを適用し、後の設定変更を含めません。Bridge の upgrade --plan-out → --plan --approve <sha> も同じ形です。内容とハッシュを結び付ける方式は Git のコミットやタグを参考にしています。

境界：エージェント自身の承認は禁止し、エージェント側ツールの権限確認で制限します。一度の承認を将来の作業にも使う常設の許可は設けず、release_actions_require_human は無効化できません。

reviewer の読み取り専用制限を確認する

課題：プロンプトに読み取り専用と書いても、書き込み権限は制限されません。reviewer が審査対象を編集できると、独立レビューの境界を保てません。

方法：reviewer を独立セッションで起動し、CLI の制限を使います。Codex は exec --sandbox read-only、Claude Code は --permission-mode plan --tools Read,Grep,Glob と --disallowedTools です。

実装前に、Codex は確認用ファイルへの書き込みを試し、OS のサンドボックスが拒否することを確認します。Claude Code では init イベントに 3 つの読み取りツール、Bridge の graph サーバー、policy で許可したサーバーだけがあり、確認用ファイルが存在しないことを確認します。失敗すれば実行しません。証拠の強さは異なるため、分けて説明しています。

参考元：読み取り専用 token で PR 検査を行う CI の方式です。CLI 出力と OS のサンドボックスが制限の証拠を提供します。

境界：プロンプトを権限制限の代わりにせず、独自のサンドボックスも実装しません。

検証は Bridge が実行する

課題：writer がテスト成功と報告しても、実際の結果による裏付けが必要です。エージェント環境の制約で実行できない場合もあります。Windows の Codex サンドボックスで Vitest が spawn EPERM になる例があります。

方法：writer の各ラウンド後、Bridge がサンドボックス外で npm test、cargo test --workspace などの種別別テストコマンドを実行します。成功後にレビューへ進みます。未設定でも作業は実行でき、カード、記録、結果に明記します。

参考元：実際の検査結果で成功を判定する CI の required checks です。

境界：テストコマンドを writer に決めさせず、テスト結果を reviewer の判定の代わりにもしません。

Git から変更の証跡を得る

課題：モデルの変更ファイル一覧は、実際の状態と異なる可能性があります。変更を独立して確認する根拠が必要です。

方法：開始時のコミットを記録し、終了時に Git から変更を取得して自身の記録と照合します。結果は、Git の変更、未照合の writer の報告、開始前の未コミット変更を分けます。履歴の書き換えやブランチ切り替えがあれば比較を停止します。Git がない場合は証跡がないと明記します。

参考元：PR の差分を base commit から計算し、実際の変更をレビューできる方式です。

境界：Bridge はコミット、push、merge、デプロイを行いません。成果を受け入れるかは人が決めます。

記録の正本をデータベースに一本化する

課題：作業ディレクトリの JSON や Markdown に記録が分散すると、プロジェクトをまたぐ検索や統一 UI の提供が難しくなります。

方法：ユーザーごとに PostgreSQL を 1 つ用意し、127.0.0.1 のみで待ち受けます。作業指示、バージョン、計画カード、承認、コントラクト、run、イベント、判定、納品を記録します。

状態ディレクトリのイベントファイルはキャッシュです。読み取り時にデータベースの連番と照合し、遅れていれば再構築、先行していれば拒否、不一致ならデータベースを優先します。切断中は終了処理と納品だけを許可します。再接続後の追記ではデータベースが採番し、不一致を拒否します。

参考元：Temporal sticky cache のサーバー採番と差分読み取り、Kafka idempotent producer の client 番号を broker が照合する方式です。実行側の状態管理は GitHub Actions、Prefect、Inngest と比較しています。

境界：別の正本は維持しません。SQLite は WAL の肥大化、IO、並行実行のロックを考慮して採用しませんでした。バックアップは PostgreSQL のファイルレベル方式を使い、独自形式は作りません。

プロジェクトファイルへの変更を限定する

課題：グローバルツールとして、既存の .gitignore、AGENTS.md、CLAUDE.md、.claude/ の無断変更や、実行記録の混入を避ける必要があります。

方法：設定、作業指示、結果のコピーは .review-bridge/ に保存します。* だけの専用 .gitignore でフォルダー全体を Git の対象外にし、後から Git を初期化しても同様です。ユーザー単位の Bridge 専用ファイル（~/.claude/commands/review-bridge.md、~/.agents/skills/review-bridge/SKILL.md）をプロジェクト間で共用し、uninstall で管理します。実行状態とログは OS の標準ディレクトリに保存します。

.vscode/tasks.json への書き込みは任意で、既定では行わず、先にユーザーへ確認します。

参考元：env-paths の data／log 規約。専用フォルダーに * だけの .gitignore を置く pytest の .pytest_cache、ruff の .ruff_cache、uv の .venv。.vscode/ 作成前に確認する create-vue。tasks.json のコメントを維持する VS Code の jsonc-parser です。

境界：任意の VS Code 連携を除き、既存のユーザーファイルは変更しません。AGENTS.md へのマーカーブロック追加も行いません。conda／pnpm／nvm の方式は検討しましたが採用していません。ユーザーが作成した skills も変更しません。

個人用コネクターを分離する

課題：Claude や Codex の個人設定にある Drive、データベース、node_repl などの MCP コネクターがセッションに引き継がれる可能性があります。reviewer に削除ツールが渡ると、役割に必要な権限を超えてしまいます。

方法：Claude Code の全呼び出しに --strict-mcp-config を指定し、Bridge が指定したサーバーだけを読み込みます。プロジェクトの .mcp.json は writer のみ、Bridge の読み取り専用 graph サーバーは両方の役割に渡します。reviewer の権限確認時に init イベントに想定外のツールがあれば、チェックは失敗し、実行しません。

Codex の全呼び出しに --disable apps --disable plugins を指定し、codex mcp list のサーバーを個別に無効化します。リストを読めなければ実行しません。reviewer 用のサーバーは reviewer.mcp_allow に指定します。これらの読み取り専用検証は行わず、カードに明記します。

参考元：両 CLI の既存の分離オプションを、毎回明示的に適用します。

境界：独自の MCP プロキシは作りません。Bridge 自身の graph サーバーを除き、既定ではサーバーを許可しません。

コードで実行上限を適用する

課題：自然言語で effort、予算、ラウンド数を指示するだけでは、モデルが制限を守る保証がありません。

方法：schema に従って読む policy JSON に、ラウンド数、呼び出し時間、トークン量、テスト時間、run 全体の時間上限を定義します。作業指示はその上限を超えられません。

設定の優先順序は CLI フラグ → 作業指示 → priority テーブル → limits です。計画は各値の設定元を記録し、カードに表示します。固定時に設定を読み、同じ入力なら同じ結果を返します。

参考元：Vite の CLI → 設定ファイル → 既定値の優先順序と、GitHub Actions job の timeout-minutes です。

境界：予算はモデルに決めさせません。プロジェクトの上書き設定では reviewer の effort を priority テーブルより下げられません。

アップグレードは Bridge が完結させる

課題：旧サービスの停止、データベース起動の診断、旧ディレクトリの移動をユーザー任せにすると、手順漏れで処理が止まりやすくなります。

方法：upgrade は、旧サービス停止 → バックアップ → 移行 → 整合性確認 → 旧ファイル整理 → 起動 → ヘルスチェックの順に実行します。冪等なので中断後に再実行できます。認識できないファイルは移動・削除せず、その存在を理由に更新を止めません。

参考元：完了済みステップを記録し未適用分だけ処理するデータベース migration と、docker compose down／up、brew services の起動・停止フローです。

境界：旧ディレクトリ構成は維持しません。別の常駐プロセスが必要になるアイドル時の自動停止も設けません。