ToWow / Flowness 工程进展:从需求到交付

CLAUDE.md 里写的“不要”只是提醒:规则分三档,红线别交给模型自己挑

规则三档:常驻上下文的 CLAUDE.md 只是提醒,按需加载的 Skill 和按路径生效的规则可能没进上下文,只有 hook 和权限规则能硬拦,借了安全工程控制措施分级的思路。读完你会给每条规则标一档,把红线从“等模型自己挑”里拿出来。

那时我们的 Agent 系统每次开工,先由程序挑出这次要守的规则,再给干活的 Agent 生成一份开工说明。8 月 5 日排查才发现,挑中的几条红线没送到它手里,它拿到的只是一个数:激活了几条。这个数一直在,看上去规则都到了。

你在 CLAUDE.md 里写了一句“不要加复述代码的注释”,Claude 写出来的代码里,还是一堆这样的注释。Claude Code 的 GitHub 仓库里,#65961 专门讲这件事,到 10 月中旬,252 个人点了赞。楼主说,CLAUDE.md 里一条清楚、强制的规则压不牢;规则、记忆、hook 叠上三样,还只管用一部分。

两件事是同一个病:规则写下来了,不等于它在起作用。写给 Claude Code 的规则,管用的程度分三档。

常驻档是 CLAUDE.md,每次对话都在上下文(模型这一轮看得到的全部文字)里,可它只是提醒,官方文档的说法是“当作上下文,不是强制配置”。

按需档是 Skill(模型看描述决定用不用的说明包)和按路径生效的规则,带不带由模型或匹配条件决定,没带上也没有人告诉你。

硬拦档是 hook(Claude Code 在固定时机自动跑的、你自己写的脚本)和权限规则,装在工具调用的路上,执行之前由 Claude Code 判,模型说了不算。

所以一条规则不必三档各写一遍。按它违反一次要付的代价标一档:违反了回不去的那几条硬拦;红线不交给模型或匹配条件去挑;其余的照实标“靠抽查”,然后真的去抽。配套仓库里有一套最小可跑的配置:一份标了档的 CLAUDE.md 示例、一个拦“改已提交的迁移文件”的 hook、两条挡 .env 的权限规则,外加一个查规则有没有放错档的小脚本。

一、写得更狠、拆进 Skill,为什么不够

规则不听话,多数人先做的是写得更狠:MUST、NEVER、全大写、加粗,再在 CLAUDE.md 和记忆里各写一遍。这有用。文档承认,指令越含糊、越互相打架,越难被遵守,写具体确实能提高它照做的机会。可写得再狠,它还在常驻档里,还是一段提醒;越叠越长反而更糟,文档建议每份 CLAUDE.md 控制在 200 行以内,越长占的上下文越多,遵守越差。

第二种做法新一些:把规则拆进 Skill,CLAUDE.md 变短,要用的时候再加载。对“怎么做”的说明,这是好主意。可 Skill 用不用由模型读描述决定。Vercel 在 2026 年 1 月测过一组:Agent 能用 Skill 时,56% 的用例里 Skill 一次也没被调用,通过率 53%,和什么文档都不给一样;加一句“去用 Skill”的明确指令,到 79%;把一份 8KB 的文档索引直接放进 AGENTS.md(Codex 等工具读的项目说明文件,作用同 CLAUDE.md),到 100%。文中没写测的是哪个 Agent,只能当类比看:给了,不等于用了。

第三种做法是每条都上 hook。照楼主的说法,连 hook 一起叠上,也只管用一部分。这不奇怪:“这句注释是不是多余”,脚本判不准;判不准的事硬拦,会拦错很多。

常见做法 漏掉什么 怎么补
写得更狠、多写几处 还是提醒,越长越不听 按代价分档
拆进 Skill 模型可能没调用 红线不进按需档
每条都上 hook 判不准的也硬拦 只拦最承重的几条(回不去的)

三种做法各对一半,缺的是同一个问题:这条规则违反一次,要付什么。

二、老方法,新补丁:须知和防护罩之间多出一档

CLAUDE.md 像墙上的操作须知,hook 和权限规则像机床的防护罩(这里借的是 NIOSH 控制措施分级的思路,前一种叫行政控制,后一种叫工程控制);可防护罩罩住的是危险部位本身,hook 只管它挂上的那几个工具,挂在改文件的 Edit 和 Write 上,Agent 写一段 Python 脚本自己打开文件,就从旁边绕过去了。所以每道硬拦都得写明它看不见什么。

Agent 多出来的那一档是按需档,只在“看上去相关”时才亮的须知。工厂里没有这种须知,工人不会自己决定今天看不看墙。按需档省上下文,代价是它亮没亮,没有人告诉你。

我们自己的规矩是:承重的约束必须有一个物理落点,落点比如一个 hook、一条权限规则,不合规的动作要么做不了,要么机器查得出;没有落点的,照实标“靠抽查”,相应少信它一点;而且只给最承重的几条造落点,免得为管十个东西建三十道门。

三、给每条规则标一档

标档先问两个问题:违反一次,回得去吗?机器判得准吗?

违反一次 机器判得准 机器判不准
回不去 硬拦,如改已在生产库跑过的迁移、把 .env 里的密钥读出来贴进对话 常驻档,标 [抽查: 合并前看 diff],如“别把用户数据打进日志”
回得去 常驻档,标抽查;总抽出毛病,再改硬拦(第六节) 常驻档,标抽查,写清怎么查,如“别改公共接口的含义”

回不去又判不准的最难办:把它写在 CLAUDE.md 最前面,除了标签,还要让改动生效的那一步(合并、上线)留给你自己,做之前看一遍 diff。

剩下是“怎么做”的说明,迁移文件怎么命名、测试用什么命令跑,可以挪去按需档:漏带一次,多半是格式不对,改回来就是。

标法很简单:挪去按需档的做法不用标;留在 CLAUDE.md 的每条“必须/不要”,末尾写上 [硬拦: 靠什么拦] 或 [抽查: 怎么查]。写硬拦,就得说出是哪个 hook、哪条权限规则;说不出来,它就是抽查。仓库里的 check-tiers.sh 会列出三样:没标档的规则,标了硬拦却在设置里找不到落点的,按需档里写着“红线”或标了硬拦的条目。

9 月我们拆过一次自己的 CLAUDE.md,思路和这里一样。拆前近 2 万字符,129 行操作说明原样挪进另一份文档,要用时再读;留下的有行为约束、哪些事要先问人、安全红线,剩 1 万字符出头。挪走的多是“怎么做”,留下的多是“不许做”和“先问谁”。

做法挪去按需档没事,漏一次改回来就是。红线为什么不能也挪过去?

四、红线不交给模型挑

按需档的规则,有三种情况会没到。

Skill 由模型读描述决定用不用;文档写明,装的 Skill 多了,Claude Code 会从最少用的那些开始砍掉描述,好塞进列表的字数预算,模型就更难认出该用它。第一节 Vercel 那组数,说的也是这件事。

按路径生效的规则(.claude/rules/ 里带 paths 的文件),只在 Claude 碰到匹配的文件时才加载,附在那次工具调用的结果后面送进来。我们在 macOS 上用 Claude Code 2.1.302 的后台 Agent 拿一条这样的规则测过,内容是“migrations/ 下每个新文件,第一行写一句暗号”,看文件里有没有暗号,就知道 Agent 写的时候看没看到规则。几种碰法,加上压缩(对话太长时,Claude Code 把前文总结成摘要):

怎么碰的文件 规则来没来 什么时候来 Agent 照没照做
先读后改 来 读完、改之前 没测
不读,用写文件的工具新建 来 第一份文件写完以后 回头重写,三次都是
在 shell 里用 printf … > 新建 三次都没来 不来 写的时候看不到
接着用 cat 看一个旧迁移 来 附在输出后面 三次里两次没照做:说它来路可疑,也不在这次的任务里
压缩以后 照文档,被总结掉 再碰一次匹配的文件 没测

按路径的规则可能不来,来了也常晚一步,还可能被当成可疑内容。

开头那件事也是这样:挑中了,没送到,看上去一切正常。红线漏一次就回不去,所以它至少要待在常驻档,每次都在场;机器判得准的,再加硬拦。

想知道按需的规则到底来没来,可以让 Claude Code 每加载一份规则就记一行(仓库 settings.json 里 InstructionsLoaded 那段),翻一下 .claude/loaded.log,就知道是哪个文件把它带进来的。

红线留在常驻档,也还只是提醒。回不去的那几条,要拦在执行之前。

五、最承重的几条才上硬拦

原生权限规则(settings.json 里 permissions 下的 allow、deny)能做的,先用原生的。挡 .env 两条就够:Read(./.env) 和 Edit(./.env)。我们试了三种碰法:用读文件的工具读、在 Bash 里 cat、用写文件的工具整个覆盖,两轮六次全被挡下。它的边界也要知道:照文档,这两条权限规则管得到 cat、sed 和重定向,管不到 Python 脚本自己打开文件(cat 我们测过)。

原生做不到的,才写 hook。迁移文件是一例:已经提交、可能已经在生产库跑过的旧迁移不许改,新迁移照常加。权限规则只认路径,分不出新旧,一挡连新的也写不了;hook 能先问 git,这个文件在不在上一次提交里,在就以退出码 2 拦下,把原因交给 Agent。

CLAUDE.md 里也写着这条时,Agent 先把 hook 脚本翻出来看了一遍,没去试就停了;只有 hook 时,它试了一次,被拦,停下来。这是我们让 Agent 去改一个已提交的迁移、两种情况各跑两次看到的。拦下时那句话要写清楚,仓库里的 hook 写的是:“已经提交过,只许新增,不许改。别换办法改它;要改,停下来问人。”四次都给出了“新建一个迁移”和“你确认后放行”这两条路,没有换 sed 或 Python 去绕。我们看到的只是这些:hook 里写了让它停下来问人,它这几次照做了。它要是真用 sed 去改,hook 看不见,第七节的表里写着。

hook 自己也会坏。照文档,脚本路径写错、忘了给执行权限,Claude Code 都当成非阻断错误,动作照做。我们把脚本的执行权限去掉试过两次:已提交的迁移被改掉了,Agent 回报说“没有被拦,也没有报错”;两次它都接着提了一句,CLAUDE.md 里这条标着硬拦,这次却没拦住。在这条 hook 上加一行 "onFailure": "block"(照文档,这个键要 Claude Code 2.1.295 以上),同样的坏脚本,改动被拦下。这是失败安全默认(拿不准时默认不放行)的老规矩,搬到 hook 上,要自己写出来。

硬拦也有成本:每道 hook 都要人维护,误拦了要人来放。所以只给回不去的那几条造。

剩下那些标了“抽查”的,怎么办?

六、其余的照实标“靠抽查”,然后真去抽

标了抽查,就要写清谁、在什么时候、用什么查。最省事的是提交前看一眼 diff,一条命令就能粗数出这次新加了几行注释。抽查会漏,所以它只配那些漏一次改得回来的规则。

抽查的结果也是一份读数。同一条规则总被抽出毛病,说明它的代价比你以为的高:机器判得准的,往上挪一档,改成硬拦;判不准的,就在 CLAUDE.md 里把它写得更短、更具体,挪到前面。

七、照着搭

配套仓库 04-rule-tiers 目录里的五份,放进 Agent 干活的那个仓库,CLAUDE.md 和 settings.json 并进你现有的:

你的仓库/
├── CLAUDE.md             每条规则末尾标一档
├── .claude/
│   ├── settings.json     挡 .env;挂两个 hook
│   ├── hooks/
│   │   └── append-only.sh  已提交的迁移只许新增
│   └── rules/
│       └── migrations.md   按需档:只放写迁移的做法
└── scripts/
    └── check-tiers.sh    查规则有没有放错档
要管住的事 这套配置
用 Edit、Write 改已提交的迁移 hook 拦
新建迁移、改刚建的 放行
读、cat、整个覆盖 .env 权限规则挡
hook 脚本自己坏了 拦
用 Bash、Python 改迁移 看不见
Python 脚本读 .env 看不见
没标档、按需档里写着红线 脚本报
档标得对不对 不管
按需的规则来没来 记一行

搭完要故意犯一次。第一次别在干活的仓库里做:新建一个小仓库,提交一个假迁移,放一个只写假值的 .env,再装那五份。然后让 Agent 改那个已经提交的迁移,看 hook 拦不拦;让它新建一个,看放不放;让它读 .env;再往一个测试用的 Skill 里写一行红线,跑 check-tiers.sh,看它报不报。步骤在配套仓库的 README 末尾。

八、代价与不适用

误拦是有意的:旧迁移真有错,而且确定还没在任何库跑过,也得人来改,或者人临时关掉 hook。回不去的事交给人,这是这套配置的立场。hook 坏了的时候,onFailure 会把所有 Edit、Write 都拦下,连新建也不行,修好脚本之前 Agent 用这两个工具什么也写不了。这比坏着放行强,但要知道它会这样。

每次改文件都多跑一次脚本,最多两条 git 命令。check-tiers.sh 只查形状:标没标、落点在不在、按需档里有没有写着“红线”或标了硬拦的条目;标得对不对它不管,按需档里没写“红线”二字的禁令,它也认不出。规则对应的东西会变,标签也会过时,过几个月要人通读一遍。

不需要它的:一次性脚本、原型、没有回不去的操作的仓库,全标抽查就够,不必写 hook。可以拆的时候:hook 守的东西没了,比如项目不再用迁移,hook 跟着删。一道硬拦几个月一次没拦过,别因为它安静就拆,回不去的事本来就少。

回到那条注释规则

楼主那条“别写复述代码的注释”,违反一次改得回来,脚本也判不准哪句注释多余,所以它属于常驻加抽查:留在 CLAUDE.md 里,写短、写具体,提交前粗数一下这次新加了几行注释:

git diff --cached -U0 | grep -cE '^\+[[:space:]]*(#|//)'

它只认 # 和 // 开头的行,Markdown 标题和 #! 那行也会算进去,行尾注释不算。

给它上 hook,换来的是一堆误拦;管不住百分之百,就承认它靠抽查,这比叠上三样又只管用一部分省心。我们那几条红线正好相反:回不去,却放在由程序挑的那一档,挑中了还没送到干活的 Agent 手里。8 月 5 日当天改的是送达,让挑中的红线原文跟着开工说明一起送到;换到你的仓库,照这篇的分法要再往前一步:红线不放按需档,放进每次都带的常驻档。

今天能做的第一步:在仓库里跑一次下面这条命令,把 CLAUDE.md 里的“必须/不要”列出来,挨条标一档,说明性的行不用标。

grep -niE '必须|不要|不许|禁止|never|always|must' CLAUDE.md

标不出靠什么拦的,就写抽查。一条规则管不管用,不看它写得多严,看它违反的时候有没有东西挡在工具调用前面;挡不住的,别让“写过了”冒充“管住了”。

配置、故意犯一次的步骤和实测条件,都在 github.com/Towow-ai/harness-patterns 的 04-rule-tiers 目录。


Flowness 是我们自己做的自运转 Harness,也就是让很多个 Agent 节点共用一份事件记录(按时间记下每个决定和结果)、一起完成复杂任务的那套系统。这个系列里的模式,整理自这样一个烧了粗略估计 1400 亿 Claude token,持续运行超过六个月并真实使用在生产交付的系统中所遇到的问题。

下一步

如果你的团队正在把 agent 放进真实业务,想了解 Flowness,或想聊企业 AI 落地怎么做,请在“联系我们”页写下行业和想解决的问题,我们按这些内容回复。 联系我们