為什麼這麼設計
本頁依序說明各項設計要解決的問題、採用的做法、參考依據與設計邊界。每項做法都須有既有生態的參考依據，不採用缺乏對照的自創機制。
這一頁的前提寫在這篇：AI 導入後，工程團隊真正要管理的是交付鏈路與驗證責任（HackMD）——AI 加快的是產出，沒有拿走驗證的責任；團隊要管的是驗證的量能，不只是產出的速度。
合約由程式抄出，確認一次就開工
問題：工單若有歧義，模型可能自行推定需求，直到完成後才發現理解有誤。若未保留授權依據，事後也難以查明由誰核准、核准了哪些內容。
做法：start 先將工單、範圍、預算與驗證指令封存成計畫，再顯示授權卡片。確認僅適用於卡片上的原文與 SHA-256，之後修改檔案不會變更已授權內容。授權記錄在資料庫中，建立後不可變更；若授權缺失、損壞、過期（24 小時）或已使用，一律拒絕執行。合約在卡片之前由程式產生：照工單區塊原文抄錄，驗收清單的每一項切成一條條件，不呼叫模型，卡片上的合約 SHA-256 就是你確認的內容。工單缺必填內容、驗收清單有不是清單項目的行、或還有待決問題時，start 在卡片前停下，逐項指出；writer 做工途中判斷需要人決定時，會停下並把問題寫進結果檔。
參考依據：Terraform 的 plan -out → apply <plan> 流程，僅套用儲存的計畫，不採用計畫產生後的設定修改。Bridge 的 upgrade --plan-out → --plan --approve <sha> 採用相同模式。以雜湊綁定內容的方式，則參考 Git 的 commit 與 tag。
設計邊界：代理不得自行授權，須由代理工具的權限提示機制限制。不提供一次確認後持續有效的常駐授權，release_actions_require_human 也不得關閉。
驗證 reviewer 的唯讀限制
問題：提示詞中的唯讀要求無法限制實際寫入權限。若 reviewer 能修改受審內容，就無法維持獨立審查的邊界。
做法：Bridge 會為 reviewer 啟動獨立工作階段，並使用 CLI 提供的唯讀設定：Codex 使用 exec --sandbox read-only；Claude Code 使用 --permission-mode plan --tools Read,Grep,Glob 與 --disallowedTools。
執行前，Codex 會嘗試寫入哨兵檔，確認作業系統沙箱阻擋寫入；Claude Code 則檢查 init 事件中的工具清單，確認除了三項讀取工具，只有 Bridge 的 graph 伺服器與 policy 放行的伺服器，且哨兵檔未建立。檢查未通過便不執行。兩種檢查的證據強度不同，文件會分別說明。
參考依據：參考 CI 使用唯讀 token 執行 PR 檢查的方式，以 CLI 輸出與作業系統沙箱提供的證據確認限制。
設計邊界：不以提示詞取代權限限制，也不自行實作沙箱。
由 Bridge 執行驗證
問題：writer 回報測試通過，仍需有實際執行結果可供核對。代理的環境也可能限制測試，例如 Windows 上 Codex 的沙箱可能使 Vitest 回報 spawn EPERM。
做法：每輪 writer 完成修改後，由 Bridge 在代理沙箱外執行專案類型對應的測試指令，例如 npm test 或 cargo test --workspace。測試通過後才進入審查。未設定測試指令的專案仍可執行工單，卡片、紀錄與結果檔都會標示此情況。
參考依據：CI 的 required checks，以實際執行的檢查結果作為通過依據。
設計邊界：測試指令不由 writer 自行決定，測試結果也不能取代 reviewer 的審查判定。
工作證明來自 Git，不是模型自述
問題：模型回報的修改清單可能與實際狀態不同，需要能獨立查核改動內容。
做法：對於使用 Git 的專案，Bridge 會記錄執行開始時的 commit，結束時從 Git 讀取改動，並與自身紀錄核對。結果檔分列三份清單：Git 取得的改動、writer 回報但未經 Git 核對的內容，以及執行前已存在的未提交改動。若執行期間有人改寫 Git 歷史或切換分支，Bridge 會停止，不繼續比對。專案未使用 Git 時，則明確標示無法提供工作證明。
參考依據：PR 以 base commit 計算差異，讓審查者核對實際改動。
設計邊界：Bridge 不執行 commit、push、merge 或部署；是否接受修改，仍由人工決定。
以資料庫為紀錄的唯一來源
問題：若執行紀錄分散在各工作目錄的 JSON 與 Markdown 檔案中，就難以跨專案查詢，也不利於建立統一的操作介面。
做法：Bridge 為每位使用者提供一份 PostgreSQL，僅監聽 127.0.0.1。工單、版本、計畫卡片、授權、合約、執行、事件、判定與交付都會記錄在資料庫中。
執行狀態目錄中的事件檔僅作為快取。每次讀取時，先核對資料庫序號：快取落後便重建，超前則拒絕讀取，內容分歧時以資料庫為準。資料庫斷線後僅允許結束工作與交付；恢復連線後補寫資料時，由資料庫指派序號，核對不符便拒絕補寫。
參考依據：參考 Temporal sticky cache 的伺服器序號與增量讀取方式，以及 Kafka idempotent producer 由 client 提供序號、broker 核對的做法。執行端狀態管理則以 GitHub Actions、Prefect、Inngest 為對照。
設計邊界：不維護第二份權威狀態。選型時考量 WAL 膨脹、IO 與並行執行所需的鎖定機制，因此未採用 SQLite。備份使用 PostgreSQL 的檔案層級備份方式，不另訂格式。
限制對專案檔案的修改
問題：Bridge 是全域工具，應避免擅自修改專案既有的 .gitignore、AGENTS.md、CLAUDE.md、.claude/，也不應讓執行紀錄混入專案內容。
做法：設定、工單與結果副本放在專案的 .review-bridge/，資料夾裡放一個只有 * 的 .gitignore，整個資料夾不進 Git，之後才 git init 也一樣。代理入口安裝在使用者層級的 Bridge 專用檔案（~/.claude/commands/review-bridge.md、~/.agents/skills/review-bridge/SKILL.md），供所有專案共用，並由 uninstall 管理移除。執行狀態與日誌存放於作業系統的資料與日誌目錄。
另可選擇寫入 .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 設定的 MCP 連接器，可能被工作階段繼承，例如 Drive、資料庫或 node_repl。若 reviewer 的工作階段因此取得刪檔工具，就會超出所需權限。
做法：Claude Code 每次呼叫都使用 --strict-mcp-config，只載入 Bridge 指定的伺服器：專案的 .mcp.json 僅提供給 writer，Bridge 自己的唯讀 graph 伺服器提供給兩個角色。reviewer 唯讀檢查的 init 事件出現其他工具時，檢查失敗，工作不開始。
Codex 每次呼叫都使用 --disable apps --disable plugins，並逐一停用 codex mcp list 列出的伺服器；清單無法讀取時，便不開始執行。要讓 reviewer 使用特定伺服器，須將其名稱加入 policy 的 reviewer.mcp_allow。這些伺服器未經唯讀驗證，卡片會明確標示。
參考依據：使用兩種 CLI 既有的隔離選項，並在每次呼叫時明確套用。
設計邊界：不另行實作 MCP 代理層；除了 Bridge 自己的 graph 伺服器，預設不放行任何伺服器。
以程式規則限制執行
問題：若僅以自然語言在工單或 skill 中指定 effort、預算與執行輪數，就無法確保模型遵守限制。
做法：上限定義在 policy 的 JSON 中，並依 schema 解析，涵蓋執行輪數、單次呼叫時間、token 用量、測試時間與整次執行時間。工單設定不得超過上限。
各項設定依固定優先順序解析：終端機旗標 → 工單 → priority 表 → limits。計畫會記錄每個值的來源，並顯示在授權卡片上。設定於封存時載入，相同輸入會得到相同結果。
參考依據：Vite 的設定優先順序：CLI 旗標高於設定檔，設定檔高於預設值；執行時間上限則參考 GitHub Actions job 的 timeout-minutes。
設計邊界：預算不由模型決定；專案層覆寫不得將 reviewer 的 effort 降至 priority 表設定以下。
由 Bridge 完成升級流程
問題：若升級需要使用者手動停止舊服務、排查資料庫啟動問題或搬移舊目錄，就容易因遺漏步驟而中斷。
做法：upgrade 依固定順序執行：停止舊服務 → 備份 → 遷移 → 完整性檢查 → 清理舊檔 → 啟動 → 健康檢查。流程具備冪等性，中斷後可重新執行。無法辨識的檔案會保留原狀，不搬移、不刪除，也不因此阻止升級。
參考依據：資料庫遷移工具記錄各步驟、僅執行尚未完成的遷移；服務管理則參考 docker compose down／up 與 brew services 的停止、啟動流程。
設計邊界：不保留舊版的目錄配置，也不加入需要額外常駐程序的閒置自動關閉機制。