# Zc Documentation And Adrs

> 文档与 ADR

- Skill: `zmice/zc-documentation-and-adrs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zmice/zc-documentation-and-adrs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zmice/zc-documentation-and-adrs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zmice (https://skillmd.com/u/zmice)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zmice/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`
- 规格、计划和实现完成后，可回到这里做最终沉淀