dsh-doc

1# 维护有用的工程文档
2 
3阅读[项目上下文](references/project-context.md)和[文档写作](references/prose.md)。创建文档前，先找到现有负责维护相关事实的位置。
4 
51. 明确读者、任务和实际源码行为。涉及默认值、输入输出、失败恢复及兼容性时，阅读实现和真实示例。
62. 选择下面与任务有关的流程，只组合请求需要的部分。
73. 优先修改事实的现有维护文档，更新导航和指向它的链接，并在任务范围内清理矛盾的重复说明。沿用项目的文档约定和语言。
84. 验证示例、路径和链接，对照代码检查语义。格式检查不能证明事实正确或内容完整。适用时执行项目必需检查。
9 
10## 当前行为文档
11 
12说明前置条件、受支持用法、代表性示例、重要限制和失败行为。注释解释行为约定或不明显的选择，不记录修改过程。公开行为变化时，在同一次改动中更新读者实际使用的入口文档。
13 
14## 决策和事故记录
15 
16沿用项目已有记录结构。长期选择的理由若会丢失，应记录下来；普通局部修改不需要决策记录。重大漏检缺陷、重复故障或用户明确要求时编写事故记录，不要求每次修复都做复盘。
17 
18- 决策使用[决策模板](templates/decision-record.md)：问题、选定行为、真实备选方案及落选理由、影响、证据和状态。同时记录收益与代价。移除功能时保留原始需求、失去的能力和重新考虑的条件。历史缺失时不编造备选方案，新增建议与历史决定分开标注。
19- 事故使用[复盘模板](templates/postmortem.md)：实际影响、已知经过、原因、现有检查为何漏检、修正和防复发措施。每项防护对应到它能检出的故障、已知的实际负责人，以及代码或测试证据；区分拟议、已实现和已验证。缺失的日期、负责人、链接或测试结果保持未知，不补造。
20 
21区分假设与已经核实的事实。当前指南不保留会话推理过程，但保留解释长期约束的理由。
22 
23## 已实施提案与归档
24 
25将提案标为已交付前，验证实际实现。核对名称、路径和机制与现状一致，同时保留历史决策。只有状态适合归档时才归档，修复指向它的链接，并注明当前维护位置或后继文档。不得悄悄删除仍有效的需求，或将历史改写为当前行为。
26 
27## 产品迁移指南
28 
29说明受影响版本和用户、新旧行为、前置条件、可执行步骤、兼容期、验证方式及回退限制。涉及持久化数据时，明确格式负责方、备份策略和迁移中断后的行为。用代表性的旧数据走真实迁移入口。不要将产品迁移与 DSH Engineering Skill 安装包更新混淆。
30 
31报告改动的维护文档、已验证行为和未解决的事实问题。翻译与发布仍是需要明确提出的独立任务。