agent-doc-discipline

Agent 文档规范

在创建或编辑 Agent 会读取并据此采取行动的任何文档时，使用此规范：五个文档面（CLAUDE.md、GLOSSARY.md、docs/standards/、design-system/、.omc/skills/）、规格说明、工单和技能文件。文档必须通过以下测试：全新的 Agent 会话只需阅读文档，就能据此采取行动。

以下情况必须使用：drydock 生成文档面种子时，launch C5 沉积检查将经验写入某个槽位时。其他所有编辑均可选择使用此规范——但任何面向 Agent 的文档都应符合这些规则。

何时不使用

仅为人类撰写的文档：docs/business/ 中的叙述、ADR 决策记录、面向人类入门的 README。只要不费什么功夫，它们也可以遵循这些规则，但不受此规范约束。

规范

为没有聊天记录的读者撰写。 文档应自成一体：不能依赖“如前所述”、之前的会话，或存在于某人脑中的知识。测试： 全新的 Agent 会话只需阅读文档，就能据此采取行动。

每条规则都应可检查，并说明原因。 不要写“保持整洁”——应写明可观察到的条件及其原因。测试： Agent 只看文本就能判定通过或不通过，且规则旁边写明了原因。

一个含义，一个归属处。 每条规则或定义都应有唯一的权威出处；重复内容只会逐渐偏离。测试： 更改一项行为只需修改一处。

绝不重述环境中已有的信息。 软件包脚本、目录布局、--help 输出都可查阅，而非文档——复制进去的信息会过时。只记录无法通过查阅找到的内容：未写明的惯例、选择背后的原因、容易踩的坑。测试： 每一行都经得起“这能在别处查到吗？”的检验。

步骤优先，参考内容随后，少见内容放在指针之后。 先在开头列出按顺序执行的操作；下面再列按需查阅的规则；低频内容则放在指针之后，并在指针文字中说明哪些情况应触发查阅。测试： 读者能在首屏找到下一步操作。

每个步骤都以完成标准收尾。 必须能区分已完成和未完成——模糊的界限会导致过早结束。测试： 对于每个步骤，“我怎么知道这一步已经完成？”在文本中都有答案。

超过两步的流程必须编号。 编号是稳定的引用标记：读者可以指明第 3 步，按顺序执行，并直接跳转，无需重新阅读。步骤很多却不编号的流程，会迫使读者把顺序记在脑中。测试： 每个包含三步或更多步骤的流程都带有编号。

列表长度应控制在读者一眼能看完的范围内。 列表一旦超出读者的把握范围，就会失去作用——其中的内容将难以查找。较长的枚举应转化为结构（表格、小节），或拆分。本规则约束的是文档写作；绝不适用于门禁机制或批量决策的运作方式，这些属于方法论，而非文字表述。测试： 文档中的每个列表都能一眼看完，任何较长的枚举都已转化为结构。

延期和计划中的工作必须注明时间。 如果文档将工作推迟到后续步骤、会话或版本，必须在所推迟的工作旁注明时间——读者需要知道“何时”才能采取行动，而未注明的延期看起来就像尚未开始。时间只在文字中注明；绝不重新绑定方法论有意推迟的检查点。测试： 文档中的每项延期都注明了何时处理。

结尾应指向读者现在就能开始的下一步。 报告、工单或会话结束指引的结尾不应是总结，而应是读者能在两分钟内开始执行的唯一下一步——目标位置、指针或命令。只做总结的结尾会让读者不得不重新推导该先做什么。测试： 无需向上滚动，读者就能从最后一行得知“接下来该做什么？” 每当读者重新加入时，重新陈述当前状态。 在读者中途接触到的文档（一份长规范、一份运行报告、一个地图 Notes 部分）中，新内容开头应先说明当前进展——步骤、阶段或决策计数——然后再补充任何新内容。测试： 一个毫无背景的读者能在最新章节的前两行内定位到当前状态。

以正面方式提示。 陈述目标行为；禁止性表述仅保留给硬性护栏，并且始终与正面目标配对。测试： 文档中的每一条禁止性表述都指明了应改为去做的事。

写入时刮除藤壶。 当文档包含过时或冗余的内容时，在同一次编辑中将其移除；当没有时，只添加所需内容，不要凭空编造删除。模型默认已经遵守的句子白白承担负担——把整句删除。测试： 每一行重新读过的文字都经得起“与默认行为相比，这能改变行为吗？”的检验，并且编辑过程中发现的任何过时或冗余内容都已被清除。

验证

在报告文档修改完成之前，确认：

• 一个全新的会话可以据此行动，而无需向人类询问任何事
• 每条规则都可检查并说明其理由；没有规则只是复述一份查阅表
• 含义只存在于一处；指针指明其触发分支
• 编辑过程中发现的过时或冗余内容已被移除，而有效的无关内容得以保留
• 结尾落在读者现在就能开始的下一步行动上；重新加入的读者在接触新内容之前先看到当前状态的陈述
• 三步或以上的流程要编号；列表一眼可览；每次延后都说明其时机