規則推廣器 是做什麼的?
概述
CLAUDE.md 中的規則是建議:Claude 可以找出理由繞過它們。鉤子則是強制執行。此技能會讀取專案的 CLAUDE.md,挑出鉤子實際能強制執行的規則,將它們寫入由一個小型經過測試的引擎所強制執行的規則檔案,證明每條規則能阻擋違規行為,並在使用者確認後安裝鉤子。它只在使用者要求時執行。鉤子是護欄,不是安全邊界:一個堅定的繞過方式(輔助腳本、sh -c)可以繞過某個模式。請務必說明這點。
檔案(位於此技能的基本目錄,技能載入時顯示)
scripts/rule_hook.py:引擎。將它複製到專案中的.claude/hooks/rule_hook.py。python rule_hook.py selftest證明每一條規則;check是鉤子的進入點。scripts/settings_merge.py:launcher選擇一個可用的 Python 指令;plan顯示設定差異;apply寫入設定。
兩個檔案都使用此機器上可用的 Python 3 指令來執行(嘗試 python3、python、py -3)。請引用路徑。
流程
-
讀取。 在專案中找到
CLAUDE.md、.claude/CLAUDE.md及CLAUDE.local.md。列出每一條規則及其檔案與行號。如果沒有任何規則,請說明並停止。 -
分類 每條規則精確地歸入以下其中一類:
- 一個引擎類型(見下方)並附上具體參數;
taste,附上一行原因;needs input,附上要問的具體問題(例如「哪個指令執行你的測試?」)。
一條規則只有在它指定了具體的工具、路徑、指令或文字模式,且違規行為可透過一次工具呼叫或回合結束指令的退出狀態檢測到時,才算可強制執行。如果不確定,請將其標記為
needs input並提問;絕不要猜測模糊規則的模式。絕不要發明規則類型。 -
審查。 顯示一個表格:規則、類型、模式或指令、一個違規範例、一個通過範例,以及誤報風險。逐字顯示每一個
stop_check指令。請使用者刪除或調整行項目。在獲得確認前不要寫入任何東西。 -
證明。 獲得批准後,建立
.claude/hooks/並將scripts/rule_hook.py複製到該處,寫入.claude/rules.json,然後從專案根目錄執行python .claude/hooks/rule_hook.py selftest。顯示輸出。證明失敗的規則不會被安裝:修正其模式或刪除它,並說明是哪一條。 -
安裝。 執行
settings_merge.py launcher --script .claude/hooks/rule_hook.py,然後執行settings_merge.py plan --settings .claude/settings.json --launcher "<launcher>" [--pretool] [--stop](如果存在任何路徑、指令或內容規則則加上--pretool;如果存在任何 stop_check 規則則加上--stop)。顯示差異並請使用者確認。只有在獲得同意後,才使用apply執行相同的指令。如果它報告無效的設定 JSON 或重複的鍵,請停止並告知使用者;不要手動編輯檔案。輔助程式只會移除它自己的rule_hook.py條目,並保留所有其他鉤子不變。如果下方的端到端檢查顯示鉤子未觸發,但selftest通過且disableAllHooks未設定,則表示某些 Claude Code 版本缺少 exec 形式的args:請使用--shell-form重新執行plan和apply。 -
端到端驗證。 如果你可以在專案中執行
claude -p,請針對一個protected_path或banned_content規則,使用一個一次性檔案進行測試(例如要求它編輯受保護 glob 下的tmp-rule-check.txt),絕對不要使用會實際執行任何程式的blocked_command或stop_check,並在事後復原任何變更。在做出結論前,請檢查專案、本地和使用者設定中的disableAllHooks。確認輸出顯示了Rule <id>:區塊訊息,並顯示它。如果你無法執行巢狀會話,請說明原因,並表示安裝僅透過selftest驗證。 -
報告。 列出已推廣的規則、已跳過的規則及其原因,以及一個限制:Claude 仍可編輯
.claude/rules.json、.claude/hooks/和.claude/settings.json。提議為它們新增一條protected_path規則,並說明這也會阻止重新執行此技能,直到該規則被停用。然後說明如何關閉功能:在.claude/rules.json中將規則的"enabled"設為false,或從.claude/settings.json中刪除rule_hook.py條目。
在使用者審查表格之前,絕不要寫入 rules.json、鉤子檔案或 settings.json。在顯示差異並獲得同意之前,絕不要寫入 settings.json。
如果使用者新增了一條規則或更改了表格後的原模式,或者你因為模式無效或其證明失敗而必須更改模式,請顯示該新行或已更改的行(模式、違規範例、通過範例、風險)並在寫入任何內容之前等待同意。先前給予的批准不涵蓋不同的模式,且絕不要替換使用者未看過的模式。
規則類型
每一條規則都有 id(kebab-case)、source(CLAUDE.md:14)、text(原始規則)、message(當規則被封鎖時顯示給 Claude 的訊息)、type、以下欄位,以及一個包含 violation 和 pass 載體的 proof。
protected_path:不允許編輯匹配的檔案。Glob 模式匹配整個相對於專案的路徑;對於任何深度請使用 **/name。
{"id": "no-migration-edits", "source": "CLAUDE.md:3", "text": "永遠不要編輯 migrations/ 下的任何內容",
"type": "protected_path", "globs": ["**/migrations/**"], "allow_globs": [],
"message": "遷移檔案是自動產生的。請建立一個新的遷移。",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "app/migrations/0001_initial.py", "old_string": "a", "new_string": "b"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "app/models.py", "old_string": "a", "new_string": "b"}}}}
blocked_command:與正規表示式匹配的 Bash 指令,會對複合指令的每個區段進行測試。使用 except_patterns 以允許安全的變體;例外會豁免整個區段,因此請使其具體。
{"id": "no-force-push", "source": "CLAUDE.md:4", "text": "永遠不要執行 git push --force",
"type": "blocked_command", "patterns": ["\\bgit\\s+push\\b.*(?:--force\\b|\\s-[A-Za-z]*f[A-Za-z]*\\b|\\s\\+\\w)"], "except_patterns": ["--force-with-lease"],
"message": "不允許強制推送。",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "git push --force origin main"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "git push origin feature"}}}}
banned_content:正規表示式,其匹配的內容不得出現在正在寫入的新文字中(Edit、Write、MultiEdit、NotebookEdit),可選擇性地透過檔案 globs 限制。舊文字永遠不會被檢查。
{"id": "no-console-log", "source": "CLAUDE.md:5", "text": "src/ 中不可有 console.log(",
"type": "banned_content", "patterns": ["console\\.log\\("], "globs": ["src/**"],
"message": "請使用 logger,不要使用 console.log。",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "src/a.js", "content": "console.log(1)"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "src/a.js", "content": "logger.info(1)"}}}}
stop_check:一個指令,必須成功執行後 Claude 才能停止。當指令退出碼不為零時,它會封鎖停止。when_changed_globs 限制僅在修改了匹配檔案的回合中觸發(僅限未提交的變更:如果 Claude 傾向在停止前先提交,則可省略此項)。證明使用 simulate_exit(自我測試不會執行真實指令)。
{"id": "tests-pass", "source": "CLAUDE.md:6", "text": "在完成前請執行 npm test",
"type": "stop_check", "command": "npm test", "timeout_seconds": 240, "when_changed_globs": ["src/**", "tests/**"],
"message": "測試必須通過才能停止。",
"proof": {"violation": {"hook_event_name": "Stop", "simulate_exit": 1}, "pass": {"hook_event_name": "Stop", "simulate_exit": 0}}}
檔案格式為 {"version": 1, "rules": [ ... ]}。工具載體:Bash 使用 tool_input.command;Edit 使用 file_path、old_string、new_string;Write 使用 file_path、content。
什麼是可強制執行的(分類指南)
- 可強制執行:「永遠不要編輯 X/」、「不要碰 .env」、「永遠不要執行 Y」、「不要在 W 下的檔案中使用 Z」、「在完成前執行 T」。
- Taste:「偏好小型函式」、「撰寫清楚的提交訊息」、「保持 UI 可及性」、「偏好清晰」。沒有任何模式可以決定這些。
- 需要輸入:「小心處理資料庫」、「確保測試通過」(哪個指令?)、「避免使用舊有程式碼」(哪些路徑?)。請提問;不要猜測。
- Glob 模式僅支援
*、**和?,相對於專案(不支援[ab]、{a,b}、前導./或/);引擎會拒絕任何其他內容。timeout_seconds最多為 280,且enabled必須為true或false。 - 偏好狹窄的模式。請說明每條規則的誤報風險(例如
main模式也可能匹配名為main-menu的分支),並在必要時新增allow_globs或except_patterns。
語氣
簡潔且基於事實。這是設定工作,不是關於規則的演講。
常見錯誤
- 在使用者審查表格之前寫入任何檔案或設定。
- 在未顯示差異並獲得同意的情況下寫入
settings.json。 - 安裝使用者未作為表格行查看過的規則,或悄悄替換使用者要求的模式。
- 安裝證明未通過的規則。
- 推廣 taste 規則,或猜測模糊規則的模式。
- 發明引擎不具備的規則類型。
- 遺漏誤報風險,或「護欄,不是安全邊界」的警告。
- 手動編輯無效的
settings.json,而不是停止。 - 聲稱觀察到了實際未發生的端到端封鎖行為。