to-docs

转为文档

将近期工作转化为持久的指导原则，但不要把会话当作变更日志。

适用于多个代码库的流程应归入可复用技能。应将其报告为超出此工作流范围，而不是记录成项目规则。

两个阶段的范围都限定为 docs/adr/ 以外的项目指导。发现、阅读、决策分析和文档变更均须排除该目录及其全部内容，包括协调和交叉引用更新。仅记录在该目录中的指导，不算已覆盖。

阶段 1：提出方案

此阶段不要编辑项目文档。

1. 阅读代码库说明以及可能承载相关指导的现有文档。区分已提交的指导与未提交的文档草稿；不要仅仅因为草稿存在于工作树中，就把它视为已批准的政策。
2. 以对话或用户指定的工作为权威范围。根据讨论、相关代码和聚焦的差异，还原其中的重要决策。纳入因否决其他方案或后续更正而体现的隐含决策。将与范围无关的工作树脏改动视为范围外内容，并将差异用作证据，而不是待记录决策的积压清单。
3. 逐项评估决策，而不只是分类。思考以下问题：
   • 这条指导是否适用于其他资源或页面？
   • 它表达的是预期不变量，还是在描述当前实现？
   • 编码 Agent 知道这条指导后，未来是否会做出实质上更好的选择？
   • 能否清楚说明其范围、例外和失败情形？
   • 它是否有反复使用或充分的设计推理作为依据，而非来自一个偶然示例？
   • 是否已有充分文档说明？
   • 是否与现有指导、lint 规则、测试或共享模块相矛盾？
4. 用反例检验候选规则。若规则脱离原始情境后在语义上不再成立，则应否决或缩小其范围。
5. 将每项重要决策归入以下类别之一：
   • 记录：持久且通用的指导。
   • 完善现有指导：已有相关内容，但不完整、有误导性，或与新决策相矛盾。
   • 已覆盖：无需更改文档。
   • 保留在局部：资源、路由、文案、命名或实现细节。
   • 暂缓：模式看似合理，但证据不足以将其确立为项目规则。
6. 只呈现有意义的结果。对于每项拟议的文档变更，说明：
   • 概括后的规则；
   • 它值得成为全项目指导的原因；
   • 其范围和例外；
   • 应由哪份文档负责；
   • 必须同步更新的矛盾内容或相关强制执行机制。
7. 明确列出不纳入项目文档的重要决策，并说明原因。
8. 最后请求用户批准方案。在用户明确批准之前，不要编辑文档。

如果无法获得决策历史，或无法可靠区分所请求的范围与无关工作，应说明这一限制，并请用户提供缺失的固定依据或决策背景，而不是根据整个工作树推断政策。

优先修改现有权威文档，而不是新建文档。避免在多份文档中重复同一规则；将完整规则放在一份主文档中，并在其他地方用简短的交叉引用指向它。

阶段 2：获批后应用

获得明确批准后：

1. 使用 /writing-for-agents，并在整个阶段贯彻其写作规范。如果无法使用，请停止并请用户通过 npx skills@latest add mattpocock/skills --skill writing-for-agents 安装。
2. 编辑前，重新阅读每份受影响的文档。
3. 仅应用获批的规则，并遵循仓库的术语和语言要求。
4. 协调范围内的文档集：移除过时的指导，解决矛盾，并更新交叉引用。
5. 如果文档中的政策通过机械方式检查（例如 lint 配置、共享模块或测试），则更新相应的强制执行机制。确保文档与强制执行机制保持一致。
6. 保持针对资源的示例仅用于说明；不要将其名称、路由、字段或查询参数变成通用政策。
7. 根据更改的文档和强制执行机制，运行适当的检查。报告未运行的检查。
8. 总结已写入的持久规则、其所属文档，以及仍需在代码中完成的任何已批准后续工作。

质量标准

有用的指南会告诉未来的 Agent 应该如何选择、为什么这样选择、适用范围，以及何时不适用。应拒绝那些只是复述最终代码、未体现项目不变量的个人偏好，或规定了不如语义规则耐久的实现机制的规则。