cold-read

冷读

每份文档最终都会被某个人——人或 Agent——读到，而这个人并未参与编写文档的任何对话。为这样的读者写作：说明当前状态，让内容不言自明，不写其他内容。

动笔前，先模拟这样的读者：他们需要什么才能采取行动？哪些事情他们根本不可能知道？哪一行会让他们不得不开口询问？凡是不符合模拟要求的句子，都要改写成独立完整的内容，或直接删除。

规则

• 只写当前状态。 过去的情况、迁移或弃用的内容、不再使用的内容——都不应出现在文档中。只有拿来与过去对比才有意义的事实，也没有意义。
• 不引用需要了解历史才能理解的内容。 如果一个名称、代号或决定只有过去的对话才能解释，就把它改成读者可自行应用的通用规则，否则删掉。如果要概括成通用规则，就必须依赖没人记录过的事实，那就删掉这一行并提醒负责人——绝不要编造理由。
• 不写显而易见的内容。 没有读者会违反的警告就是噪声；应通过机械方式强制执行（如 .gitignore、lint、CI），而不是写出来。
• 不写元评论。 不要提及文档的编写方式或编写过程中达成的共识——直接陈述规则本身。
• 在使用处解释内容。 变量、密钥或常量应在使用它的技能、模块或配置中说明；中心文档只说明这些内容来自哪里以及如何获取。
• 使用英文，字面数据除外——外部实体的名称（数据库、属性、页面）应保持其原有拼写。

对于技能：

• 描述是触发条件，不是操作手册：说明技能的作用以及何时触发。实现细节放在正文中，仅在使用时加载。
• 技能绝不列在 AGENTS.md / CLAUDE.md 中——它们通过自身的描述来说明用途。

通过实证进行验证

作者无法看到自己的盲点——对已经了解背景的人来说，每一行都显而易见。冷读者几分钟内就能发现缺漏。因此，要按照文档的实际使用方式测试文档：启动一个全新的子 Agent，让它只阅读文档，然后：

1. 提出场景问题（“你需要完成 X——说说你会怎么做”），检查它能否采取正确行动；
2. 询问它有什么不理解、需要但找不到的内容，以及读到但用不上的内容。

修正它误解的内容，然后让另一个全新的读者重新测试这些修正。如果没有可用的子 Agent，就退而求其次进行自查：重读文档，并列出陌生读者无法从文档本身获取的每一项事实。