Communitygithub.com

规则提升器

将 CLAUDE.md 中的规则转换为由小型引擎强制执行的 Git 钩子,防止 Claude 绕过规则。

规则提升器 是什么?

规则提升器是一项技能,旨在将 CLAUDE.md 中的软性规则(即建议)提升为硬性钩子(即强制规则)。它能读取项目中的 CLAUDE.md 文件,识别出可被引擎强制执行的规则(例如禁止编辑特定路径、禁止运行特定命令、禁止内容中特定模式等),并将它们转换为 JSON 规则文件。该技能会通过自检证明每个规则的有效性,并通过设置合并脚本将钩子安装到 `.claude/hooks/` 和 `.claude/settings.json` 中。它支持多种规则类型,包括 `protected_path`、`blocked_command`、`banned_content` 和 `stop_check`,且在工作流程中强制要求用户批准生成规则表格,避免误判。该技能强调这是一个护栏而非安全边界,并会提示其局限性。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NarenDawar/narens-claude-skills/tree/HEAD/plugins/rule-promoter/skills/rule-promoter

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

规则提升器 是做什么的?

概述

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)。路径请加引号。

流程

  1. 读取。 在项目中查找 CLAUDE.md、.claude/CLAUDE.md 和 CLAUDE.local.md。列出每条规则及其所在文件及行号。如果没有规则,则说明并停止。

  2. 分类 每条规则必须归入以下其中一类:

    • 一个引擎类型(见下文)及其具体参数;
    • 口味,附上一行原因;
    • 需要输入,附上要问的具体问题(例如“你的测试是用哪个命令运行的?”)。

    只有规则中指定了具体的工具、路径、命令或文本模式,并且违规行为可以通过一次工具调用或轮次结束命令的退出状态检测到时,才可强制执行。如果不确定,则标记为 需要输入 并询问;切勿猜测模糊规则的模式。切勿发明不存在的规则类型。

  3. 审查。 显示一个表格:规则、类型、模式或命令、一个示例违规、一个示例通过、以及误报风险。逐字显示每条 stop_check 命令。请用户删除或调整行。在此之前不要写入任何文件。

  4. 证明。 获得批准后,创建 .claude/hooks/ 并将 scripts/rule_hook.py 复制到那里,写入 .claude/rules.json,然后在项目根目录下运行 python .claude/hooks/rule_hook.py selftest。显示输出。证明失败的规则不会被安装:修正其模式或删除它,并说明哪一条。

  5. 安装。 运行 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。

  6. 端到端验证。 如果你能在项目中运行 claude -p,则使用 protected_path 或 banned_content 规则针对一个临时文件进行测试(例如要求它编辑受保护通配符下的 tmp-rule-check.txt),切勿使用会实际运行命令的 blocked_command 或 stop_check,并在测试后撤销所有更改。在得出任何结论之前,请检查项目、本地和用户设置中的 disableAllHooks。确认输出显示了 Rule <id>: 块消息,并显示它。如果你无法运行嵌套会话,请说明,并说明安装仅由 selftest 验证。

  7. 报告。 列出已提升的规则、跳过的规则及原因,以及一个限制: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 而不是停止。
  • 声称观察到了你并未实际观察到的端到端阻止。

相关技能