规则提升器 是做什么的?
概述
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。列出每条规则及其所在文件及行号。如果没有规则,则说明并停止。 -
分类 每条规则必须归入以下其中一类:
- 一个引擎类型(见下文)及其具体参数;
口味,附上一行原因;需要输入,附上要问的具体问题(例如“你的测试是用哪个命令运行的?”)。
只有规则中指定了具体的工具、路径、命令或文本模式,并且违规行为可以通过一次工具调用或轮次结束命令的退出状态检测到时,才可强制执行。如果不确定,则标记为
需要输入并询问;切勿猜测模糊规则的模式。切勿发明不存在的规则类型。 -
审查。 显示一个表格:规则、类型、模式或命令、一个示例违规、一个示例通过、以及误报风险。逐字显示每条
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](如果有任何protected_path、blocked_command或banned_content规则,则添加--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规则针对一个临时文件进行测试(例如要求它编辑受保护通配符下的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:禁止编辑匹配的文件。通配符匹配相对于项目的完整路径;对于任何深度的路径,使用 **/name。
{"id": "no-migration-edits", "source": "CLAUDE.md:3", "text": "永远不要编辑 migrations/ 下的任何内容",
"type": "protected_path", "globs": ["**/migrations/**"], "allow_globs": [],
"message": "Migrations 是自动生成的。请创建新的 migration 代替。",
"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": "请使用日志器,而不是 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(selftest 不会运行真实命令)。
{"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”。
- 口味:“偏好小函数”、“写清晰的提交信息”、“保持 UI 可访问”、“喜欢清晰”。没有任何模式可以决定这些。
- 需要输入:“小心数据库”、“确保测试通过”(哪个命令?)、“避免遗留代码”(哪些路径?)。询问;不要猜测。
- 通配符仅支持
*、**和?,相对于项目路径(不支持[ab]、{a,b}、前导./或/);引擎会拒绝其他任何内容。timeout_seconds最多为 280,enabled必须为true或false。 - 优先使用狭窄的模式。针对每条规则说明误报风险(例如
main模式也可能匹配一个名为main-menu的分支),并在必要时添加allow_globs或except_patterns。
语气
简洁且实事求是。这是设置工作,不是关于规则的讲座。
常见错误
- 在用户审查表格之前写入任何文件或设置。
- 未显示差异并获得确认就写入
settings.json。 - 安装用户未在表格行中看到的规则,或悄悄替换用户要求的模式。
- 安装证明未通过的规则。
- 提升口味规则,或为模糊规则猜测模式。
- 发明引擎不存在的规则类型。
- 遗漏误报风险或“护栏而非安全边界”的说明。
- 手动编辑无效的
settings.json而不是停止。 - 声称观察到了你并未实际观察到的端到端阻止。