跳转至

笔记

Claude Code 规则强制化

把全局 CLAUDE.md 里“靠模型自觉”的规则,改成钩子、skill 和只读评审子代理来强制执行的记录(2026-11-20)。原文写给站长本人,文中的“你”指站长。

三句话看懂

  1. 改了什么:能机械判断的规则(比如 shell 里写文件、Python 不带 -X utf8、Git 回滚)做成了钩子,Claude 违反时工具调用直接被拦下并收到中文提示;按场景用的流程做成了 4 个 skill;评审交给一个只读子代理。
  2. 平时要不要管:不用管。被拦的是 Claude 的操作,它会按提示换正确写法重试;你只会偶尔看到它补一条改写后的回复。另有两件事等你自己决定,见第四、五节。
  3. 想关掉怎么办:删掉 ~/.claude/settings.json 里对应的钩子条目,当前会话立刻生效;全部撤销见下文回退方法。

处理思路是按“能不能机械判断”分三类:

  • 能机械判断的:做成钩子,违反时工具调用直接被拦下。
  • 只在特定场景用的流程:做成 skill,按描述自动触发。
  • 评审要求:做成只读的 reviewer 子代理。

另外处理了计划任务会话堆积的问题。改完后做了一次独立评审,评审提出的问题复核后已修正,见文末。

一、钩子(强制执行)

改了哪些文件

文件 作用
~/.claude/hooks/guard_tools.py(新) PreToolUse,匹配 Bash、PowerShell、Read、Grep、Write、EnterPlanMode 六个工具,下表大部分规则在这里;带 --readonly 模式给 reviewer 用
~/.claude/hooks/check_reply_words.py(新) Stop,检查最后一条回复里的禁用表达
~/.claude/hooks/fix_ps1_bom.py(新) PostToolUse(Write/Edit),给含中文的 .ps1 自动补 BOM
~/.claude/hooks/check_long_bash.py(停用) 功能已并入 guard_tools.py,原文件已移出 hooks 目录,备份里留有一份
~/.claude/settings.json 注册上面三个新钩子;原有的上下文大小检查和“验证证据”Stop 检查保留

出错一律放行:

  • 每个钩子命令前面都加了“脚本不存在就退出 0”的判断([ -f 脚本 ] || exit 0),脚本被删或改名时直接放行。没有这一句的话,Python 打不开脚本会返回 2,会被当成“拦截”,所有调用都会被拦。
  • 脚本内部异常、输入格式不对时,也一律退出 0 放行。

被拦时 Claude 会收到一条中文提示,说明原因和正确做法。

强制执行的规则

规则 拦什么 放行什么
Python 一律 -X utf8 本机任何 Python 调用(python、python3、python3.11、带路径的 python.exe,包括 timeout 60 python3 …)没带 -X utf8 ssh 主机 "python3 …" 引号里或 heredoc 里的远端命令
不用 Git 回滚 git reset --hard;git checkout -- 文件、checkout .、checkout -f;git restore;git switch --discard-changes git restore --staged / -S(只取消暂存);git checkout 分支;合并冲突时的 git checkout --ours/--theirs
改文件只用 Edit/Write sed -i、perl -i;cat/echo/printf 重定向写文件(含 cat > 文件 <<EOF、不带空格的 echo x>文件);tee 写到临时目录以外;PowerShell 的 Set-Content/sc、Add-Content/ac、New-Item/ni -Value、'文本' > 文件、here-string 管道给 Set-Content 命令输出重定向(git log > 文件、Out-File),用于“先存到临时目录再过滤”;tee 到 scratchpad 或临时目录;写到 /dev/null、$null;Bash 里的 sc query(那是 sc.exe)
脚本超过二十行先写成文件 超过 20 行的命令;超过 2000 字符且带 heredoc 的命令 —
GBK 文件不在 shell 里直接读、直接跑 type/cat/Get-Content/head/tail/rg/grep/findstr/Select-String 读 .bat/.cmd 文件;带路径运行 .bat/.cmd(.\x.bat、厂商的 …\cli.bat);cmd /c x.bat;Start-Process x.bat;chcp 搜索词里出现 “.bat” 的 rg -n "start.bat" docs/;rg --glob '!*.bat' 这类排除写法;PATH 上的包装脚本 npm.cmd、npx.cmd;通过 gbk-tool.ps1 的 export/run 调用
gbk-tool 的 run 必须用 -Command powershell … -File …gbk-tool.ps1 run … -Command "& '…gbk-tool.ps1' run …";-File … export/check/import
GBK 文件不直接读(扩展到 Read、Grep 工具) Read 读不是 UTF-8 的 .bat/.cmd;Grep 工具的 path 是 .bat/.cmd 或 glob 指向 .bat/.cmd UTF-8 编码的 .bat/.cmd 用 Read 读
大文件只读一段 Read 读超过 30 KB 的文本文件,且没带 limit 或 limit 超过 600 行 带 offset/limit 读一段;图片、PDF、ipynb 不受此限制
codex exec 要关 stdin codex exec … 没带 < /dev/null codex exec --help;PowerShell 里先把 $null 管道给 codex exec
不建 HANDOFF.md Write 新建名为 HANDOFF.md 的文件 已存在的 HANDOFF.md(别人项目里原有的)可以改
不擅自进 plan mode Claude 调用 EnterPlanMode 你自己按 Shift+Tab 进 plan mode 不受影响
禁用表达 回复里出现:不是…而是… 句式;钉死、技术栈;非字面用法的 落地;空泛用法的 对齐(“和某人对齐”“对齐一下”“对齐到…”“对齐目标/口径/标准…”) 代码块、行内代码、引号里的引用;字面用法:字段对齐、缩进对齐、内存对齐、左右对齐、对齐排版、落地页、落地式、落地阴影、落地窗
含中文的 .ps1 带 BOM 不拦截,Write/Edit 之后自动在文件头补 EF BB BF 并告诉 Claude 纯 ASCII 的 .ps1;本来就有 BOM 的;非 UTF-8 的文件不动

两点副作用:

  • Stop 钩子拦下时,原回复已经显示给你了,Claude 会在后面补一条只含改写句子的回复。
  • fix_ps1_bom.py 改了文件头以后,Claude 下次 Edit 那个文件时,可能要先重新读一遍。

没做成钩子的规则(仍然靠 CLAUDE.md)

  • 要理解语义才能判断:简体中文回复、授人以渔、先查再问、疑问句只回答不改动、只做被要求的内容、不用 mock 让测试通过。
  • 凭据不写进上下文和报告:钩子不知道哪些字符串是凭据,要判断就得读取存放凭据的明文,风险比收益大。
  • 同一张图只看一次:第一版做过,评审后撤掉了。原因是上下文压缩后、读图失败后、你要求“再看一次”时都会被误拦,而且没有手动放行的办法。
  • rg 搜目录时排除 .bat/.cmd、git diff 避开 .bat:目录里有没有 GBK 文件,命令本身看不出来;强制每条 rg 都带排除参数又太吵。已写进 skill gbk-files。
  • “python 脚本批量改文件”:脚本内容在文件里或 -c 字符串里,命令行上看不出意图。reviewer 的只读钩子也因此拦不住 python -c "open(...,'w')"。
  • 不画 ASCII 图、用两字以上完整词:没有可靠的判断方法。

怎么临时关掉或放宽

  • 关掉某个钩子:把 settings.json 里对应的条目删掉。改完当前会话立刻生效,已实测。
  • 只放宽某条规则:改 guard_tools.py 里对应的 check_* 函数;顶部常量 MAX_SCRIPT_LINES、BIG_FILE_BYTES、MAX_READ_LINES 可以直接调。

二、Skills(按场景自动触发)

以前 CLAUDE.md 写的是“涉及对应场景时先读某某文件”,读不读全看模型记不记得。skill 的 description 常驻在上下文里,Claude 看到匹配的场景会自动加载全文。

skill 位置 触发场景 内容来源
todo ~/.claude/skills/todo/SKILL.md 待办、任务清单、“加一条”“记一下”“划掉”(写明代码里的 TODO 注释不算) 原待办说明文档全文搬入
gbk-files ~/.claude/skills/gbk-files/SKILL.md .bat/.cmd、GBK、乱码、cp936、写含中文的 .ps1 原护栏文档的 GBK 和 PowerShell 两节搬入
security-docs ~/.claude/skills/security-docs/SKILL.md 安全产品和安全设备问题,主机合规、基线、资产比对 CLAUDE.md 的“安全产品问题先查本地资料”一行,加上本地资料目录里的查找方法
codex-image ~/.claude/skills/codex-image/SKILL.md 要新画图片(配图、插画、海报、封面、图标) CLAUDE.md 的“创作图片交给 Codex”一行。已有专门脚本生成的图片,description 里写明不走这里

原文件怎么处理的(一份内容只放一处):

  • 原待办说明文档:只留一行指向 skill 文件。
  • 原护栏文档:GBK 和 PowerShell 两节换成指向 skill 的一段,“大文件和图片”“Python 输出”两节保留,因为 Codex 没有这些钩子,仍要读它。

Codex 的入口是 AGENTS.md,它指向 CLAUDE.md,CLAUDE.md 里写了各 skill 的完整路径,Codex 照样能读到。

为什么行为规则和上下文规则不做成 skill:它们是随时都要遵守的规则,不属于某个场景,做成 skill 反而要等触发才加载。其中能机械判断的部分已经做成上面的钩子。

全局 CLAUDE.md 改了 5 行:待办、安全产品、护栏、评审、画图这几行,都改成指向对应的 skill、子代理或说明文档。改后 4900 字节(原 4982)。

三、reviewer 子代理(只读评审)

  • 文件:~/.claude/agents/reviewer.md。
  • 评审要点(查需求有没有漏、步骤和结论有没有错、风险和回滚、验证够不够、写出实际运行的命令)原来写在 CLAUDE.md 里,每次要主会话复述一遍。现在写进子代理定义,CLAUDE.md 只留“什么时候用、提示里给它哪三样东西”。
  • 只读由两层保证:
    • 工具清单里没有 Edit/Write,它改不了文件。
    • 它自带一个只在自己运行时生效的钩子(guard_tools.py --readonly)。会拦:
      • 文件改动:rm/mv/cp/mkdir,Remove-Item/Move-Item/Copy-Item/New-Item。
      • git 改动:git add/commit/push/checkout/reset/stash/新建 tag/新建 branch/config 写值。
      • 安装:npm install、pip install。
      • 写到 scratchpad 和临时目录以外:输出重定向、Out-File、tee、curl -o。
    • 会放行:git tag、git stash list、git worktree list、git branch --list 这类只读查看。
  • 用法不变:合并或交付前用收尾按钮问你,你同意了,主会话才调用它。

四、计划任务会话堆积

  • 现状:3 个定时跑的计划任务(两个每天、一个每周),运行会话都没归档,一直留在侧边栏。
  • 查到的情况:
    • 桌面版没有“计划任务跑完自动归档”的开关。
    • 能用的是 Archive inactive sessions:会话闲置多少天、并且你没打开看过,就自动归档。当前是 30 天。这个设置对所有本地会话生效,归档后可以从 Archived 列表找回。
  • 这一项需要你手动改:Claude 尝试把它改成 7 天,被自动模式的安全检查拦下了,没有绕过。要改的话在 Settings → Claude Code → Archive inactive sessions 选 7 天。
  • 已经堆着的运行会话:可以等这个设置自动处理;也可以你明确同意后,让 Claude 用 archive_session 逐个归档。每个都会弹确认,这次没做。
  • 没选“每个任务跑完把自己归档”:日报类任务的结果里常有“某几条证据不够,等你判断”这类留言,跑完就归档会让你看不到。

五、发现的问题:Python 那条规则的前提已经过时

全局 CLAUDE.md 和本机环境说明 ~/.Codex/ENVIRONMENT.md 都写着“PATH 上的 python.exe 是占位符”,但实测(2026-11-20):

  • ~/.local/bin/ 下的 python.exe、python3.exe 是 11 月 12 日新建的,指向 uv 的 3.11.15。
  • Git Bash 和 PowerShell 里,它们都排在 WindowsApps 占位符前面,所以裸写 python 现在能正常运行。

因此钩子没有禁止裸写 python,只强制 -X utf8。这两个文件没改,要不要更新由你决定。

六、回退方法(全部撤销)

备份目录:~/.claude/backups/2026-11-20-规则强制化/

  1. 用备份的 settings.json 覆盖 ~/.claude/settings.json。
  2. 同时把备份里的 check_long_bash.py 复制回 ~/.claude/hooks/。旧 settings 引用它;不放回的话,Python 打不开脚本会返回 2,所有 Bash 调用都会被拦。
  3. 用备份的 CLAUDE.md 覆盖 ~/.claude/CLAUDE.md。
  4. 用备份 codex-docs/ 里的 todo.md、guards.md 覆盖 ~/.Codex/docs/ 下的同名文件。
  5. 删除新增的文件:
    • ~/.claude/hooks/ 下的 guard_tools.py、check_reply_words.py、fix_ps1_bom.py
    • ~/.claude/skills/ 下的 todo、gbk-files、security-docs、codex-image 四个目录
    • ~/.claude/agents/reviewer.md
    • 本机的说明文档 ~/.claude/docs/规则强制化说明.md

只想关掉钩子、保留 skill 和子代理的话,只做第 1、2 步。

七、验证结果

实际跑过的:

  1. 样例测试:105 个构造的调用,覆盖每条拦截规则和放行情况。包括评审里实测出问题的全部命令、坏输入、Stop 防死循环、只读模式。全部符合预期。
  2. 历史命令回放:最近 150 个会话里的 10010 条 Bash/PowerShell 命令,新规则会拦 781 条(约 7.8%):

    • shell 写文件 422 条。
    • Python 没带 -X utf8 193 条。
    • 超长内联脚本 155 条。
    • Git 回滚 5 条。
    • 直接运行 .bat 4 条,直接读 .bat 1 条。
    • codex exec 没关 stdin 1 条。

    各类都抽样核对过,都确实违反规则。回放中发现并修掉的误拦有:rg --glob '!*.bat'、git checkout --ours、codex exec --help、“python 是占位符”的前提。

  3. 历史回复回放:5519 条回复里有 8 条会被禁用表达检查拦下,逐条看过,都是空泛用法或 不是…而是… 句式。

  4. 会话内实测:
    • 改完 settings.json 后当前会话立刻生效。
    • 加上“脚本不存在就放行”的命令格式后,sed -i 仍被实际拦下,Write 新建 HANDOFF.md 也被实际拦下。
    • 在 bash 里模拟:脚本不存在时退出 0(放行),脚本存在时照常拦截。
  5. skills 已加载:4 个 skill 都出现在当前会话的技能列表里;改了 description 以后,列表里也随即更新。

没验证的:

  • reviewer 子代理:当前会话的子代理列表是启动时定下的,新子代理要到新会话才出现,所以没在真实子代理里跑过它的只读钩子。--readonly 模式的拦截逻辑在样例测试里覆盖了 22 种情况。新会话里第一次用它时,可以让它试跑一条 rm 确认会被拦。
  • EnterPlanMode 拦截:官方钩子文档没列出这个工具名,只验证了脚本逻辑,没在真实会话里触发过。
  • Stop 禁用表达检查:没在真实会话里触发过。
  • 自动归档设置:没改成,见第四节。

八、独立评审记录

评审由只读子代理做:工具里没有 Edit/Write,按 reviewer.md 的要点评审。

子代理查过、复核后采纳并已修正的:

问题 怎么复核的 处理
钩子脚本不存在时 Python 返回 2,会拦住所有调用;回退步骤会触发这个问题 用 -X utf8 运行一个不存在的脚本,退出码 2 所有钩子命令加“脚本不存在就放行”;回退步骤加“放回 check_long_bash.py”
误拦 npm.cmd、npx.cmd 实跑,返回 2 只拦带路径的 .bat/.cmd
搜索词里有 “.bat” 就被拦 实跑 rg -n "start.bat" docs/,返回 2 搜索工具的第一个位置参数按搜索词处理
误拦 git restore -S 实跑,返回 2 -S 当作 --staged
只读模式误拦 git tag、git stash list 等,漏拦 curl -o、tee、git config 写值 加进样例测试 已修
shell 写文件漏拦:here-string、不带空格的重定向、tee、sc/ni 别名、'文本' > 文件、PowerShell 路径反斜杠、引号里的 << 加进样例测试,修之前都返回 0 已修
“对齐”字面用法被误拦 加进样例测试 改成只拦空泛用法
同一张图只看一次会误拦 读代码确认:记录写在读图之前,也没有放行办法 撤掉这条规则
漏了 codex exec 关 stdin、gbk-tool 要用 -Command、不建 HANDOFF.md、Grep 工具搜 .bat — 都已做成钩子
第四节漏写了一个计划任务;回退只写了 settings.json — 已补
todo skill 的 description 含 “TODO”,可能被代码注释误触发 — 已改

没采纳的:

  • py -3.11 漏拦:本机没有 py 启动器,命令本身会失败,不需要拦。
  • 只读模式拦不住 python -c "open(...,'w')":命令行上看不出写入意图,已写进“没做成钩子的规则”。