AI Coding 设置全局 Rule 要避开的坑

封面:左侧文件列表窗口列着 6 行规则文件,最下一行被玫红虚线框住;右侧 AI 对话窗口里只有 4 张规则卡片,一条玫红虚线在窗口缺口处断开

今天上午,我用 Qoder 做一个自用工具,公众号配图规范化处理。需求讨论完,让它生成实施计划,计划里写的起始版本是 0.1.0。

我指出这不对。我在 %USERPROFILE%\.qoder\rules\ 里有一份全局规则,写明每个新项目的初始版本号一律从 1.0.0 开始。AI 去查了规则目录,回来告诉我:规则确实存在,7485 字节,frontmatter 里老老实实写着 trigger: always_on,但在这次会话的五轮对话里,它一次都没有出现。

如果只是”这一次没被带上”,把内容重新贴一遍就解决了。麻烦的是第二层:它也没有出现在按需加载的候选清单里——AI 连”有一份我没读到的规则”这个念头都不会产生。我把这条链路查了一遍。

三条结论先行给出,依据见后文。

  1. 标记为 always_on 的规则不保证进入上下文。本次观察中,会话开始时目录内共有 3 个 always_on 文件,实际注入 2 个;改造后重开的会话有 5 个候选,实际注入 4 个,两次缺席的均为体积最大的一份。
  2. 决定是否注入的判据不是文件名顺序,也不是候选数量,而是单份体积与可容纳的总量。由此得到一个反向结果:规则写得越细、覆盖越全,最需要保留的那一份越可能因体积过大而落选。
  3. 该问题无法仅靠提示词本身消除。可行的做法是让同一条约束同时存在于多个载体,并把可机器判定的条款转为构建或测试阶段的校验脚本。

先说清边界。我是这套规则的使用者,不是 Qoder 的开发者,看不到它的注入实现。下面所有关于”为什么”的部分,都是从外部观察归纳出来的模型,不是官方机制说明,也不代表 Qoder 的产品行为。证据只有两批:上午那次会话的五轮记录,和改造完成之后为核对重开的另一次会话。样本就这么点,如果你的实际行为和这里写的不一样,以你的为准。

一、问题的表现

10-project-standards.md 里不只有版本号一条。它要求每个项目根目录必须有 CHANGELOG.md、用户手册.md、部署说明.md、启动.bat 和打包.bat;打包时必须询问是否包含用户数据;删除类操作必须先弹确认;窗口左上角显示版本号和最后修改时间;禁止硬编码绝对路径。

这些要求一起缺席了一次。事后回看那份实施计划,除了起始版本写成 0.1.0,还有四处对不上:版本号被写成”散落多处、升版时全局搜索替换”,而规则要求运行时从版本文件读取;没有窗口标题那一条;用户手册做成了应用内页面,根目录那份 md 没有;CHANGELOG、部署说明和两个 bat 都不存在。

一个错误看起来像笔误,五个错误指向同一处,那就不是笔误了。

更值得记下来的是缺席的方式。它不是”规则写得不够清楚,AI 没照做”,而是这段内容根本没到 AI 眼前:文件躺在磁盘上,AI 按自己的默认常识往下写,写得很顺,做出来的东西看起来完全合理。

还有一层当时的处境:这五处是我在指出 0.1.0 之后才逐条对回规则的。换句话说,如果不是我记得有这条版本号规矩、并且开口质疑了那个看起来无关紧要的小数字,五处错误会一起滑过去,其中四处连”看起来不对”的机会都不会有。

二、解决方案:我改成了什么

按上面的判断,我做了四件事。它们兜的不是同一个环节,所以先说清各自管什么。

一,全局规则目录只留一份短红线。 新建 00-core.md,约一千一百字、3304 字节,只放”违反了就算缺陷”的条款:版本号 1.0.0 起始、五个必备文件、CHANGELOG 与版本号单一来源、窗口标题、删除确认、禁止硬编码路径、计划文档的要求;VBA 和 Python 的专属条目挪回按需加载的规则里。原来的详细版全部改成 model_decision,内容不动,需要时按需取全文。02-software-naming.md 一直没生效,是因为最开头缺那三行 frontmatter,这次补上。

二,每个项目根目录放一份 AGENTS.md。 内容重复那份红线,外加一句”动手前先读 PLAN.md”。它跟着仓库走,不受全局注入策略影响,项目搬家、换机、备份都不会把它落下。

三,把红线塞进项目记忆。 上午那五轮里,记忆和知识卡每轮都在场,稳定性明显高于规则块。同一条约束多一个位置。

四,把能机器判定的条款做成脚本。 这是四层里唯一不依赖”AI 有没有看到”的一层:漏了就报错,报错就看得见。

对照关系如下。

条款能否自动校验方式
版本号从 1.0.0 起始能读版本文件断言
版本号单一来源能在源码里搜版本号字面量,命中即失败
CHANGELOG.md 存在能检查文件存在
用户手册.md 存在能检查文件存在
部署说明.md 存在能检查文件存在
启动.bat、打包.bat 存在且命名固定能检查文件存在与名称
禁止硬编码绝对路径能搜 C:\Users\ 之类模式
应用内手册与根目录手册一致能比对文件哈希
删除类操作必须先确认半能搜删除调用是否包在确认逻辑里,其余靠人看
窗口左上角显示版本号与最后修改时间半能断言标题字符串同时含版本号和日期
计划文档含原始需求与分阶段测试不能只能靠 review

前八条能从记性里拿掉了:漏了就报错,报错就看得见。剩下的三条,才交给前面三层去提醒。

红线开头我特意加了一句自检——”规则可能因注入名额未进入上下文,开始新项目前先列一遍规则目录”。这句话本身也是在赌:赌它排在文档首句,比夹在中间的条款更可能被读到。

三、注意事项:照做之前要知道的五件事

一,把文件挪进备份目录,不等于它不在候选里。 我做完上面第一条,把 00、01、10、11 移进 backup-20261103\ 子目录,以为那是”收起来”。几个小时之后重开会话核对,注入的 4 份 always_on 里有 3 份来自那个目录,合计 9474 字节——我的”只留一份”实际上变成了”一份新的加三份旧的”,离装不下的边界已经很近。注入会递归读子目录,判断”在不在候选里”的只有文件开头的 trigger:换文件名、换目录都不算数,要真的退役,得去掉 frontmatter 或改掉 trigger。

二,同一段会话里没有补救通道。 会话开始算完那次集合之后,只有新建或被修改的文件会单独补推一次;已经在场的不重复推送,落选的也不会因为你的操作回来。我在上午那次会话里反复说过那份规则重要,10-project-standards.md 从头到尾没有出现过。所以配置类改动,一律新开一段会话再验,不要在旧会话里反复自证。

三,新项目第一次会话是空档。 那一刻 AGENTS.md 还不存在,项目记忆是空的,只剩全局规则这一层——而版本号 1.0.0、CHANGELOG、启动.bat 这些约束,全是在项目初始化那一刻定下的。最容易出错的时刻,恰好是冗余最少、只剩一层的时刻。缓解办法只有一个:把”开工先建 AGENTS.md 和校验脚本”本身写进那份红线。

四,环境会漂移,而且不会通知你。 规则在 C 盘用户目录,不在项目仓库里。换电脑、重装、Qoder 升级改了注入策略,这套约束都会静默变化。跟着项目走、能一起备份的,只有 AGENTS.md。

五,规则不报警,只能靠人问。 一层没进来,AI 不会想”我是不是该去看一眼规则目录”,它会按常识往下写,写得很顺。所以保留一个便宜的动作:每次让 AI 做完一组改动,问一句它这次引用了哪几条规则;新会话开头再问一句现在加载了哪些规则。答案要么对得上,要么露出一段空白。

四、排查过程

1. 五轮对话的原始记录

规则注入是以文本块形式出现在对话上下文里的,AI 那边能直接看到内容,所以”这一轮到底进来了什么”可以逐轮核对。下面是那五轮的实际记录,包括同轮一起注入的记忆和知识卡。

轮次我在做什么同轮注入的记忆/知识卡本轮新增的规则块
1讨论需求1 条用户记忆(很短)00 + 01,共 3903 字节
2生成 PLAN.md1 条用户记忆无(00 + 01 仍在历史里)
3指出版本号等三个问题1 条用户记忆无
4讨论规则问题与命名3 张知识卡 + 1 段选中内容只有 11,2267 字节
5写这篇文章1 张知识卡无

这张表有个容易读错的地方,我自己当初就读错了:“本轮新增”一栏为空,不等于这一轮没有规则。轮 1、轮 2 注入进去的 00 和 01,之后一直留在对话历史里,AI 随时看得见。所以轮 3、轮 5 的真实状态是”没有重复推送”,不是”规则为零”。这一点直接决定了后面怎么解释数据,我在第 3 小节里栽过一次。

2. 先排除几个解释

排查从把目录整个读一遍开始。版本号这件事之后,我用 Get-ChildItem 列了目录,逐个读每个文件的前几行,看 frontmatter 到底怎么写的。当时一共 12 个文件,含一个 .bak-mp 备份残留。

文件字节frontmatter 里的 trigger那次会话是否出现过
00-personal-preferences.md1457always_on轮 1、轮 2
01-ambitious-thinking.md2446always_on轮 1、轮 2
02-software-naming.md1127无 frontmatter从未
10-project-standards.md7485always_on从未
11-plan-doc-standards.md2267always_on轮 4(本会话新建)
20-web-design.md6259model_decision在候选清单里
21-cross-platform-rose-violet.md14979model_decision在候选清单里
25-interaction-pitfalls.md3532model_decision在候选清单里,两次被主动取全文
30-article-style.md20175model_decision在候选清单里,轮 5 取全文
30-article-style.md.bak-mp19684model_decision备份残留,未被引用
python-rules.md1828glob未触发(那次会话没有 .py 文件)
vba-rules.md3021model_decision在候选清单里

这是改造前的快照,字节数与在场情况都对应今天上午。几个小时之后,这份快照就不再成立了,原因见第三节第一条。

10-project-standards.md 的开头四行我核对过,格式没有任何问题:

---
trigger: always_on
description: 个人项目必须遵守的工程规范(版本管理、用户手册、部署迁移、启动与打包、窗口布局)
---

格式没问题而内容整段缺席,说明问题不在”写错了”,在”没轮到”。于是把几种容易想到的说法逐个试一遍。

frontmatter 写错了。 不是。上面贴过,10 的三行格式与后来确实生效的 11 完全一致。

内容太长被截断。 也不是。截断会留下前半段,而 10 是整份缺席,一个字都没有;同轮的 00、01 都是完整全文。

它被降级成按需加载了。 这是最需要具体证据的地方。按需加载的规则在上下文里以另一种形式出现:一份清单,每条写明文件名和 description,AI 需要时主动取全文。轮 1、轮 2 的这份清单里有 vba-rules、25-interaction-pitfalls、20-web-design、21-cross-platform-rose-violet、30-article-style。10 不在里面,02 也不在。

这个区别在实践上是致命的。30-article-style.md 有 20175 字节,是目录里最大的一份,约等于 10 的 2.7 倍,它照样以清单形式在场,一句话就能取到全文。所以”体积”在候选清单那条通道上不是障碍——但这条结论不能顺手推到”每次都注入”那条通道上,这是我后来才分清的。

只有 always_on 会被裁。 这条看着像解释,其实是同义反复:那次观察里所有缺席的文件都是 always_on,但我没法排除”它只是太大了”。后来的复测把这一点补上了,见第 4 小节。

3. 我第一个解释,错在哪

排查到轮 4 时我给过一个解释,写在这里,因为推翻它的过程比结论更有用。

我说的是:规则、记忆、知识卡共用一个上下文预算,谁需要得多谁先被砍,规则排在最后。当时支持它的只有一条——轮 4 有三张知识卡加一段选中内容,规则只剩一份;对比轮 1、轮 2 只有一条短记忆,规则进来两份。看着像反比。

问题有两层。第一层是口径:我拿”轮 3 新增为零”当反证,但轮 3 的零是”没有重新推送”,不是”规则不在场”——00 和 01 从头到尾都在历史里。用它来检验”预算松紧有没有影响”,论据本身就站不住。更可能的解释是:注入集合在会话开始时就算完了,之后的轮次根本不重新挑,逐轮轻重当然影响不到它。

第二层是方向。真正需要解释的是”会话开始时为什么没选 10″,而轮 1 恰恰是记忆和知识卡占用最少的一轮。按挤压说,它最该装得下。

我犯的错不是某个数字记错了,是三个:口径不清、样本只有四轮、以及先找到一个能解释部分现象的原因,就当作解释了整个现象。轮 4 的数据当时看起来完全支持”预算说”,我没有先去检查剩下两轮有没有反证。

4. 现在的模型:按体积装,不是按名字排

改造完成之后,我为了核对,重新开了一次会话,问了一句”当前加载了哪些规则”。这一次的注入块给出了上午拿不到的信息。

当时目录里已经是改造后的样子:根目录只保留新的 00-core.md,原来的 00、01、10、11 都改成了 model_decision,旧文件整体移进了 backup-20261103\ 子目录。

而这一次注入的 always_on 规则,是下面四份。

注入顺序文件字节
1backup-20261103\00-personal-preferences.md1457
2backup-20261103\11-plan-doc-standards.md2267
3backup-20261103\01-ambitious-thinking.md2446
400-core.md3304

四份合计 9474 字节。仔细看这个顺序:它不是文件名字母序(00 之后本该是 01,实际来了 11),也不是创建时间序,但四份的字节数严格递增。而同一批候选里唯一缺席的,是体积最大的 10-project-standards.md(7485 字节)——把它加进去,总量会从 9474 跳到 16959。

上午那次会话的数据放回来,是同一个形状:00(1457)在前,01(2446)在后,同样升序;轮到 10(7485)时,3903 + 7485 = 11388,超出。

所以我目前最认可的说法是:会话开始时算一次,在一个固定的总量预算内按体积从小到大装,装不下的跳过;已装进去的不再重复推送,新建或被修改的文件单独补推一次。 预算大约在一万字节这个量级,具体是多少我测不出来。

这个模型比上午我写下的”按文件名排序取前几个”更能对上两批数据,而且它预测的不是”哪份排名靠前”,而是”你最大那份会不会因为太大而装不进去”。这个预测我验证了两轮,都成立。它同时解释了轮 4 为什么只有 11:11 是新建文件,走的是补推,和预算无关。

它有三处我区分不了,也不假装区分得了。

一是预算到底按字节算还是按别的量算。9474 和 16959 之间的差距够大,但”约一万字节”这个数是我反过来从数据里凑的,不是测出来的。

二是”按体积从小到大”还是”按别的顺序、遇到装不下就跳过”。这两种在只有两批样本时表现一样,都要求样本里体积和顺序恰好同向——而我手上这四次,恰好都同向。

三是轮 2 到轮 5 的注入块为什么整段不出现。可以是”已在场不重复推”,也可以是”只在有增量时才发”,我分不出。

5. 还没做完的验证

下面几个实验每个只需要动一个文件,成本是几次”重新加载窗口 + 新建会话”。预期结果写清楚,方便对照,也方便证伪我自己。

实验一:新建一个很小的 always_on(正文一行)和一个很大的 always_on(约 9000 字节),同一次会话里看谁进得来。 如果小的进、大的不进,体积说的方向就成立。

实验二:把现有最大的那份拆成两半,都用 always_on,看是不是两份都能进。 如果能,说明限制在单份大小;如果只能进一份,限制在总量。

实验三:把总预算压满再压,直到某一份被挤出。 这一条能估出预算的量级,但需要反复重开会话,我还没做。

原计划的两个实验可以删了。我本来打算把 10 改名为 00b 去测排序、新建一个 99-minimal-test.md 去测条数上限——这两条已经被改造后那次复测回答:排序不是关键(顺序是 00、11、01),条数也不是上限(进了 4 份)。

有一条必须记住:都要在新会话里测。已开场会话的入选集合早就定下来了,在里面改文件、改名字,只会影响到下一段会话,不会改变这一段已经发生的注入。

结尾:规则生效的条件,不是我写了

回到开头那个问题。

一条规则真的进入 AI 上下文,需要同时满足几个我不完全掌握的条件:文件有 frontmatter,trigger 属于它此刻愿意加载的那一类,并且在那道会话开始时的入选计算里装得下。三件事任何一件不成立,文件就在磁盘上静静躺着,写得再准确也不产生作用,而 AI 会拿着自己那套默认常识继续做,做出来的东西看起来完全合理。

这次查下来,最有用的一条不是”名额有限”,而是它有限的方式:不是”前面几个”,是”装得下的几个”。前者会让人去争排名,后者只说明一件事——把你最要紧的那份写短。

所以判断可以收成三句:always_on 这个名字的含义是”优先考虑”,不是”保证注入”;写规则的收益不取决于写得多详细,而取决于它在几个独立位置同时存在、以及有多少条能被代码当场拦住;剩下那些只能靠提醒的条款,必须用一个便宜的验证动作兜底——新会话开头花五秒问一句”现在加载了哪些规则”。

这个验证方法在规则目录那份 README 里写了很久。我装完规则没执行过,直到一个版本号错了才回头查;改造完又漏执行了一次。这是整件事里最省事、也最容易被跳过的部分。

0 0 投票数
文章评分
订阅评论
提醒
0 评论
最旧
最新 最多投票
0
希望看到您的想法,请您发表评论x