指令文件要分层：为什么“一次说清”反而更差
我早期做过一件很自然的事：把关于项目的所有要求、约定、注意事项，全部写进一个常驻的指令文件。文件长到两百多行，我以为这样最省事——结果是一次交付事故：文件里第 200 行写着“交付前必须导出整页截图看过”，而那一轮我恰好跳过了这一步，被忽略的原因恰恰是它在第 200 行。
先说结论
- 常驻指令不是越全越好：规则一多，每条的实际权重被摊平，具体任务上最该被想起的那一条反而最不显眼；
- 正确的做法是分层：常驻层只放“不可违反的硬约束”，流程性内容放进按需加载的任务层，细节放进被链接才读的参考层；
- 判断一条信息该放哪层，只问一个问题：这件事如果没被提醒，会不会出事？
一、现象：塞得越满，遵守得越差
那次事故之后我回看了几轮工作记录，规律很清楚：
| 常驻文件长度 | 观察到的行为 |
|---|---|
| 30 行以内 | 约束基本都被遵守，偶有疏漏也能追溯到表述不具体 |
| 80 行左右 | 开始出现“选择性执行”：格式类要求照做，流程类要求时做时不做 |
| 200 行以上 | 中间部分的条款事实上失效；同时改动文件时不敢删任何一条，文件只增不减 |
第三条最要命：文件只会变长。每踩一个坑就补一条，因为“补进去”比“判断该放哪层”便宜，于是几十轮之后，常驻文件成了一份没人完整读过的文档——包括加载它的模型。
二、为什么会这样
两个原因，都跟模型聪明不聪明无关：
一是注意力被摊平。 常驻内容在每次任务开始时就占满了预算，规则条数越多，单条获得的“相对权重”越低。当一条约束和当前任务没有直接关系时，它几乎不会被主动回忆。
二是约束之间会互相干扰。 一次性的实验要求（“这轮先固定随机种子”）和长期的项目约定（“脚本要能重复执行”）写在同一层，模型无法判断哪条该覆盖哪条——它只能平均对待，于是两条都做得半吊子。
三、分成三层
我现在固定分三层：
| 层次 | 放什么 | 体量 | 加载时机 | 判断标准 |
|---|---|---|---|---|
| 常驻层（项目指令文件） | 不可违反的硬约束：禁止事项、必须跑的检查、环境里不能用的命令 | 30–60 行 | 每次任务开始 | 违反了会直接出事 |
| 任务层（技能 / 流程说明） | 某类任务的步骤与边界：怎么写、怎么验、什么时候不该用 | 每份 100 行内 | 该类型任务被触发时 | 只在做这类任务时才有意义 |
| 参考层（笔记 / 排查手册 / 决策记录） | 具体案例、报错对照、参数细节、历史决策 | 不限 | 被链接到时才读 | 需要时查得到即可 |
判据只有一条：这件事如果没被提醒，会不会出事？ 会出事 → 常驻层；只在特定任务里会出事 → 任务层；事后查得到就行 → 参考层。
四、渐进披露是怎么落地的
关键动作是把触发条件当成第一等公民：任务层的每一份文件，开头先写清楚“什么时候该用它、什么时候不该用”，这段极短，可以常驻；正文才按需加载。目录大致长这样：
project/
├─ AGENTS.md # 常驻：硬约束（30–60 行）
├─ skills/
│ ├─ experiment/SKILL.md # 任务层：触发条件 + 步骤 + 边界
│ └─ delivery/SKILL.md
├─ docs/
│ ├─ troubleshooting.md # 参考层：症状 → 根因 → 修复
│ └─ decisions.md # 参考层：为什么这么定
└─ scripts/check.sh # 机器可判的检查，不靠人记这样安排之后，常驻部分能稳定被读完；任务层的文件只在真的要做那类任务时才进入上下文；参考层平时完全不占预算。
性价比最高的一步
把“能自动检查的约束”从指令里挪到脚本里。 一条“交付前必须跑三项检查”写在指令里，靠的是模型的自觉；写成 check.sh 并让流程固定调用，靠的是机器。指令只负责说明“为什么要有这个检查”。
五、一个反直觉的取舍
分层不是“少写”，而是把信息放到它被需要的那一层。几个我实际做过的搬迁：
- “某个路径在这个 shell 里会被改写、要用另一种写法” → 从常驻层搬到参考层的环境排障手册：它是环境相关的一次性知识，不是每次任务都要提醒的约束；
- “实验必须先写判定门槛再跑” → 从规则文件搬到实验流程的任务层：它只在跑实验时适用，写在常驻层反而稀释了别的约束；
- “界面的每个可点击元素都要被审计” → 从指令搬到交付脚本：这件事可以自动判断，交给机器比写给人看更可靠。
搬迁之后常驻文件从两百多行回到五十行以内，而遵守率反而上升了——这是最早让我确信“分层”不是形式主义的一次变化。
稍加注意
不要用“文档已经写了”来替代“流程里已经做了”。写在参考层的规则，默认是不会被执行的；只有放进常驻层或自动化脚本里的约束，才算真的生效。
六、自检清单
- 常驻文件是否在 60 行以内，且每一条都是“违反了会出事”的硬约束？
- 每条约束是否可验证（能写成一条检查），不能验证的说明它该被改写或者搬走？
- 每份任务层文件开头是否写清了触发条件与“什么时候不该用”？
- 参考层的文件是否真的只被链接、不再常驻？
- 上一次踩的坑，我补在了哪一层——是补对了，还是只是补进了最顺手的那个文件？
- 有没有哪条约束其实早就可以交给脚本，却还留在指令里靠人记？