事實強制閘門，會阻擋編輯/寫入/Bash（包括 MultiEdit），並要求在允許操作前進行具體調查（匯入器、資料結構、使用者指示）。與無閘門代理相比，可測量地將輸出品質提升 +2.25 分。
GateGuard — 事實強制操作前閘門
一個 PreToolUse 鉤子，強制 Claude 在編輯前進行調查。它不要求自我評估（「你確定嗎？」），而是要求具體的事實。調查的行為會產生自我評估從未達到的意識。
何時啟用
- 在檔案編輯會影響多個模組的任何程式碼庫上工作
- 專案中有具有特定結構或日期格式的資料檔案
- 團隊要求 AI 生成的程式碼必須符合現有模式
- 任何 Claude 傾向於猜測而非調查的工作流程
核心概念
LLM 的自我評估無效。問「你是否違反了任何政策？」答案永遠是「沒有」。這已通過實驗驗證。
但問「列出所有匯入此模組的檔案」會強制 LLM 執行 Grep 和 Read。調查本身會建立上下文，從而改變輸出。
三階段閘門：
1. 拒絕 — 阻擋第一次編輯/寫入/Bash 嘗試
2. 強制 — 明確告訴模型需要收集哪些事實
3. 允許 — 在呈現事實後允許重試
沒有競爭對手能做到全部三點。大多數只停留在拒絕階段。
證據
兩個獨立的 A/B 測試，相同的代理，相同的任務：
| 任務 | 有閘門 | 無閘門 | 差距 |
|---|---|---|---|
| 分析模組 | 8.0/10 | 6.5/10 | +1.5 |
| Webhook 驗證器 | 10.0/10 | 7.0/10 | +3.0 |
| 平均 | 9.0 | 6.75 | +2.25 |
兩個代理都能產生可執行並通過測試的程式碼。差異在於設計深度。
閘門類型
編輯 / MultiEdit 閘門（每個檔案第一次編輯）
MultiEdit 的處理方式相同 — 批次中的每個檔案都會單獨被閘門檢查。
在編輯 {file_path} 之前，請呈現以下事實：
1. 列出所有匯入/需要此檔案的檔案（搜尋樹狀結構 — 使用 Glob/Grep，或透過 Bash 使用 find/grep）
2. 列出受此變更影響的公開函式/類別
3. 如果此檔案讀取/寫入資料檔案，請顯示欄位名稱、結構和日期格式（使用去識別化或合成值，而非原始生產資料）
4. 逐字引用使用者當前的指示
寫入閘門（第一次建立新檔案）
在建立 {file_path} 之前，請呈現以下事實：
1. 指出將呼叫此新檔案的檔案和行號
2. 確認沒有現有檔案具有相同用途（搜尋樹狀結構 — 使用 Glob/Grep，或透過 Bash 使用 find/grep）
3. 如果此檔案讀取/寫入資料檔案，請顯示欄位名稱、結構和日期格式（使用去識別化或合成值，而非原始生產資料）
4. 逐字引用使用者當前的指示
破壞性 Bash 閘門（每次破壞性命令）
觸發條件：rm -rf、git reset --hard、git push --force、drop table 等。
1. 列出此命令將修改或刪除的所有檔案/資料
2. 寫出一行復原程序
3. 逐字引用使用者當前的指示
常規 Bash 閘門（每個工作階段一次）
1. 用一句話描述目前的使用者請求
2. 此特定命令驗證或產生的內容
快速開始
選項 A：使用 ECC 鉤子（零安裝）
位於 scripts/hooks/gateguard-fact-force.js 的鉤子已包含在此插件中。透過 hooks.json 啟用它。
如果 GateGuard 阻擋了設定或修復工作，請使用 ECC_GATEGUARD=off 啟動工作階段。若要進行鉤子層級的控制，請繼續使用 ECC_DISABLED_HOOKS 搭配 GateGuard 鉤子 ID。
在長時間的工作階段中，只有前 GATEGUARD_FACT_FORCE_FULL_DENIALS 次事實強制拒絕（預設 3 次）會發出完整的四項事實區塊；後續的拒絕會濃縮為單行，攜帶拒絕序號，因此幾乎相同的區塊不會累積在上下文視窗中並放大模型重複迴圈（#2142）。在呈現事實後重試相同檔案或命令永遠不會重新觸發閘門。
選項 B：完整套件含設定
pip install gateguard-ai
gateguard init
這會新增 .gateguard.yml 用於專案層級的設定（自訂訊息、忽略路徑、閘門開關）。
反模式
- 不要使用自我評估代替。「你確定嗎？」總是得到「確定」。這已通過實驗驗證。
- **不要跳過資料結構檢查。**兩個 A/B 測試代理都假設日期為 ISO-8601 格式，但實際資料使用
%Y/%m/%d %H:%M。檢查資料結構（使用去識別化值）可以防止這類錯誤。 - **不要對每個 Bash 命令都設閘門。**常規 Bash 閘門每個工作階段只觸發一次。破壞性 Bash 閘門每次都會觸發。這種平衡可以避免速度變慢，同時捕捉真正的風險。
最佳實踐
- 讓閘門自然觸發。不要試圖預先回答閘門問題 — 調查本身才是提升品質的關鍵。
- 根據你的領域自訂閘門訊息。如果你的專案有特定慣例，請將它們加入閘門提示中。
- 使用
.gateguard.yml忽略像.venv/、node_modules/、.git/這樣的路徑。
相關技能
safety-guard— 執行時期安全檢查（互補，不重疊）code-reviewer— 編輯後審查（GateGuard 是編輯前調查）
