Zc Documentation And Adrs

文档与 ADR

这是 command:start 判型后进入的专项 skill：当任务核心是沉淀决策、修正文档 drift、补齐长期说明时，进入这里，而不是继续把工作只理解成“写代码”。

何时使用

• 做了重要架构或公共接口决策时
• 发布会影响用户行为的新功能时
• 需要把“为什么这样做”留下来时
• 反复出现同一类解释，适合沉淀成长期文档时
• 实现或发布已经完成，需要判断长期文档是否发生 drift 时

输入前提

• 已有值得记录的决策、约束或经验
• 目标是说明为什么，而不是复述代码
• 愿意把文档当作工程产物持续维护

执行步骤

1. 判断是否需要 ADR、README 更新、接口文档或注释
2. 先选文档类型：教程、操作指南、参考手册、解释说明或 ADR；不要把这些目的混进同一份文档
3. 记录背景、约束、候选方案、决策和后果
4. 对公共 API 或关键流程补充可消费文档
5. 对源码中的非显而易见陷阱补充“为什么”类注释
6. 检查发布或实现是否让以下长期文档产生 drift：
   • README 和 quick start
   • 架构说明、ADR、迁移或兼容性说明
   • 公共 API、CLI、配置项、安装说明
   • 关键行为变更、默认值变化、已知限制
7. 满足以下任一触发条件时，把文档同步视为显式收尾项，而不是可选备注：
   • 用户首条成功路径变了
   • 安装、升级、回滚步骤变了
   • 默认行为、配置语义或兼容性边界变了
   • 运维、支持或后续开发会因为旧文档而误判
8. 如果文档包含图、表、截图或生成资产，保留可编辑源并确认离线可渲染
9. 把文档与代码一起进入版本控制；如果代码已发布，再补一次发布后同步核对

文档资产规则

• 图表必须保留可编辑源，例如 Mermaid、PlantUML、draw.io source 或生成脚本；不要只提交不可追溯的图片。
• 文档构建和预览必须能离线运行；不要依赖 CDN、远端字体或外部图片才能理解核心内容。
• CI 或发布检查应对缺失图片、坏链接、无法渲染的图表源失败，而不是静默跳过。
• 截图和示意图要有替代文本、标题或附近说明，避免只有视觉信息。
• 敏感截图必须先脱敏；无法脱敏时用最小复现图或结构化表格替代。

成功标准

• 重要决策有书面理由，不依赖口头记忆
• 文档说明的是“为什么”和“怎么验证”，不是重复代码
• 后续工程师或代理能直接消费这些记录
• 文档类型清楚，不把教程、参考和 ADR 写成一锅粥
• 文档与当前实现保持同步
• 文档 drift 被显式识别，而不是在发布后被动暴露
• 图表、截图和生成资产可追溯、可离线验证、可被 CI 发现损坏

相关原则

• 文档记录决策，不记录显而易见的代码
• ADR 解决的是可逆成本高的长期决策
• 最有价值的文档是帮助后人少走弯路
• “代码完成”不等于“知识完成”，发布后 drift 也算未收尾

回到主流程

• 如果发现文档问题其实来自需求或方案不清：回到 spec-driven-development
• 如果文档 drift 暴露实现缺口：回到 incremental-implementation
• 发布前后的同步收尾：继续接 shipping-and-launch 或 release-documentation-sync
• 规格、计划和实现完成后，可回到这里做最终沉淀