doc-diagnostic

doc-diagnostic

诊断与规范技能。负责三件事：

1. 替代方案目录——当用户的想法不应写成 ADR 时该写什么。完整目录：references/alternatives-catalog.md。
2. ADR 规范——模板、状态生命周期、编号、必填字段、不可变规则。（位于此文件中。）
3. 审计流程——/doc-audit 使用的文件夹级 KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR 分类。完整流程：references/audit-procedure.md。

在处理文档请求、选择模板、命名状态或审计现有文档集时使用此技能。起草 / 探索 / 评审技能会使用此处定义的规范，但不会重新定义它。

四问诊断（推荐任何文档前先执行）

规范的四问检查。doc-expert Agent 和此插件中的所有其他技能都会引用本节，而不是重复陈述。在同意编写任何文档之前，先回答全部四个问题。如果任何答案为“否”或“不明确”，就不应立即编写文档。

1. 目的——用一句话说明，对于已经知道系统存在的读者而言，这份文档要回答什么问题。
2. 受众——处于特定情境中的特定读者。（“未来的维护者”不是受众；“凌晨 03:00 遇到 P1 事件的值班工程师”才是。）
3. 负责人——指定一位负责确保内容准确的人。没有负责人 → 几个月内就会偏离实际情况。
4. 更新触发条件——导致文档需要重新审视或被取代的具体事件。没有触发条件 → 注定成为过时文档。

如果四个问题都能回答，请继续使用 doc-expert Agent 正文中的“这是否属于 ADR？”诊断。

架构显著需求（ASR）——规范定义

ADR 记录一项架构决策及其理由。架构决策针对的是架构显著需求——即“对软件和／或硬件系统的架构与质量产生可衡量影响”的 ASR。如果变更不具备架构显著性，ADR 就不是合适的工具——请通过替代方案目录选择其他文档形式。

超越架构——更广义的“决策记录”

同样的形式也适用于产品、业务、政策、安全计划和流程决策——凡是值得记录理由、且难以逆转的选择，都适用此形式。惯例：将 docs/adr/ 重命名为 docs/decisions/，并放宽 ASR 标准，改为“这项决策是否值得记录？”。模板、生命周期、编号、不可变性和 Relationships 镜像规则均保持不变。总览：github.com/joelparkerhenderson/architecture-decision-record；另见 references/adr-template-catalog.md。

替代方案目录（何时不应编写 ADR）

当诊断结果为“不属于 ADR”时，请通过 references/alternatives-catalog.md 选择其他文档形式——它将常见想法映射到正确的文档形式，解释 ADR 为什么不合适，并列出 Diátaxis 四类文档（教程 / 操作指南 / 参考 / 解释）。ADR 不是 Diátaxis 中的解释文档。每当用户讨论“ADR 还是 RFC、设计文档、运行手册或操作指南”，或询问“X 应该记录在哪里？”时，都应加载此目录。

ADR 规范

模板选择

选择能够如实反映决策的最精简模板：

模板	适用情况	不适用情况
Nygard / MADR light	决策简单，备选方案显而易见，三个到五个字段就足够（背景、决策、后果）。	需要按多个标准比较 3 个以上的备选方案。
MADR (full)	需要并列分析多个选项；决策因素很重要；需要确认/验证字段；可追溯性很重要。	决策很简单——完整的 MADR 会显得冗长。
Y-statement	用一句话概括：“在 X 的背景下，面临 Y，我们决定 Z，以实现 W，并接受 V。” 适用于精简的日志条目或执行摘要。	决策需要结构化字段。
arc42 / Tyree-Akerman / Business case	项目已经在使用其中一种。	从头开始——对大多数团队来说都过于繁重。

每个项目只选一种模板；除非明确进行迁移，否则不要在同一个日志中混用模板。

规范状态生命周期

  proposed  ----accepted---->  accepted  ----changed---->  superseded
                                      |
                                      +--no-longer-applies-->  deprecated

Explorer 兼容的状态值为小写的 proposed、accepted、deprecated、superseded。不要将 rfc、rejected、backfilled 或解释性字符串用于 status。

• proposed —— 讨论中，包括用作 RFC 的 ADR（添加 rfc-deadline，不要自行创建 status: rfc）。
• accepted —— 已生效。
• superseded —— 被后续 ADR 取代；新 ADR 的 supersedes 列表会建立关联。
• deprecated —— 已不再适用，且没有新决策取代它；或提案被否决但为了保留其“为何不可行”而留存。请在正文中说明，而不是写入 status。

不可变性与取代

首要原则：“不要更改 ADR 中已有的信息。” 应当修订或取代。

• 一旦接受，正文只能追加：修正拼写错误、添加 superseded by 说明，或在“Amendments”标题下添加带日期的条目。
• 更改决策时，应创建一份新 ADR，并在其中通过 supersedes 指明旧 ADR。旧 ADR 可以添加 superseded by: NNNN 供读者参考，但除此之外应保持原样。新 ADR 的 supersedes 列表才会建立关联；正文中的 superseded-by 说明不会。
• 如果团队倾向采用带日期内联修订的“活文档”，必须在日志的 README.md 中事先说明。

编号、命名与归属

• 编号：严格递增，并以零补齐（0001、0002……）。绝不重复使用。编号即为标识。
• 文件名：以补零后的 ID 加上现在时祈使短语组成，使用小写字母、连字符和 .md（0007-use-postgres-for-primary-store.md）。
• 归属：将 deciders 写成 YAML 数组（负责决策）；也可添加 consulted / informed（MADR RACI）。“团队”不能作为负责人。
• 日期：使用 ISO 8601。在接受时注明日期，而非首次起草时。
• 复审周期：在 ADR 中设置明确的触发条件（“当我们超过 10k QPS 时重新审视”），不要写“每年重新审视”。

必填字段

每篇 ADR 都包含：

1. 标题 -- NNNN. 决策（祈使动词短语）。
2. YAML frontmatter -- 必填。 一个 --- 块，至少包含 title、status、date、deciders。存在关系时，添加 supersedes / amends / relates-to。可选字段：tags、review-by、expires、confidence: high|medium|low、confidence-score、rfc-deadline（当 status: proposed 作为 RFC 时）。Gray-matter 解析器仅读取 frontmatter；缺少它会使节点成为孤立节点。
3. 正文中的关系镜像 -- 只要 frontmatter 中存在关系，就必须填写。 MADR 4.0.0 的 ## More Information → ### Relationships，链接前缀词汇表为（Supersedes、Superseded by、Amends、Amended by、Related to）。扫描正文的解析器仅读取此部分；两个位置必须保持一致。
4. 背景 -- 具有架构重要性的影响因素；让三年后的陌生人也能理解为何必须现在做出这个决定。
5. 决策 -- 以现在时陈述选择，独立成句。
6. 决策驱动因素 （MADR） 或隐含在背景中 （Nygard）。
7. 考虑过的替代方案 -- 抽象层级相同且切实可行的方案，每个方案用一段话说明为何不选。跳过伪替代方案。
8. 后果 -- 优点，因为…… 和 缺点，因为……，并列出后续工作。
9. 确认 / 验证 （MADR 完整版） -- 如何强制确保合规。
10. 重新评估触发条件 -- 应促使新 ADR 取代本 ADR 的具体条件。

存储与可发现性

• 将 ADR 保存在源代码仓库中，并纳入版本控制，与其约束的代码放在一起。
• 便于 Explorer 查找的位置：docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md。选择一个位置，并在日志的 README.md 中注明。
• 在该 README.md 中提供索引，列出每篇 ADR、其状态和一句话摘要。索引用于导航，不是关系图；索引中心的链接不表示关系边。
• 默认采用 MADR 4.0.0 + frontmatter + 正文中的 Relationships 镜像。 frontmatter 中的 supersedes / amends / relates-to 供 gray-matter 解析器使用；正文中的 ### Relationships 供扫描正文的解析器使用；只填写一处会导致关系图显示不完整。如果项目已使用 Nygard、Y-statement、arc42 或 Tyree-Akerman，则遵循现有格式。MADR：adr.github.io/madr/，源码 github.com/adr/madr。
• ### Relationships 之外的 Related ADRs: 行，或 ### Notes 中的 Related docs:，属于便于导航的提示，不构成关系边。
• frontmatter 列表中的 ID 格式： 使用零填充的四位数字字符串（"0008"）。Explorer 解析器通过 /(\d+)/ 提取数字并补零，因此 8、"08"、"0008"、"ADR-0008" 的解析结果相同；但零填充字符串的显示和排序更可预测。
• 在可行时从代码中交叉链接（// See docs/adr/0007-use-postgres-for-primary-store.md）。
• 明确说明关系链接维护的治理规则：如果 Accepted ADR 不可变，则允许仅修改元数据中的关系列表并补充正文中的 Relationships，或要求注明例外。
• 离线规范检查：plugins/doc-master/scripts/validate_adrs.py。完整的逐文件检查清单和 CLI 标志见 plugins/doc-master/scripts/README.md。在 /doc-audit 期间或作为 CI 门禁使用，不能替代四问检查。

规范镜像示例

---
title: "Use Postgres for primary store"
status: accepted
date: 2026-05-20
deciders: [Jane Doe]
supersedes: ["0004"]
relates-to:
  - id: "0011"
    reason: "shares the tenancy model decided in 0011"
---

# 0017. Use Postgres for primary store

## More Information

### Relationships

- Supersedes [ADR-0004](0004-use-dynamodb-for-primary-store.md) -- replaced because Q3 reporting needs sub-200ms joins.
- Related to [ADR-0011](0011-tenancy.md) -- shares the tenancy model decided in 0011.

两个位置必须保持一致。### Notes 中多余的 Related ADRs: 行、索引中心条目或 superseded-by 正文注释，都只是便于导航的提示，不构成关系边。

决策日志周边的仓库级基石

决策日志属于更广泛的社区健康文件体系：README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT（opensource.guide 的四文件规范），以及扩展版 GitHub 配置（SECURITY、SUPPORT、CODEOWNERS、FUNDING、CITATION、.github/ 模板）。doc-master 不会自动创建这些文件；四问诊断仍然适用。完整规范见 repo-health 技能——当用户设置社区健康文件、审查仓库初始化文档，或选择许可证／行为准则／贡献指南时，请加载该技能。

ADR 失效模式

十一种规范的失效模式（偏离、ADR 与 PRD 重复、捆绑决策、过早编写 ADR、模板频繁变动、未经团队认可便由 AI 做出决策，以及其他模式）的症状与补救措施：references/failure-modes.md。在审查和 adr-critique 期间加载。

文件夹级审查流程（/doc-audit 使用）

遵循 references/audit-procedure.md 中的八步流程：清点 → ADR 规范性测试 → 四问测试 → 偏离检查 → 重复检查 → 错误分类检查 → 识别可补录候选项（根据已发布变更证据进行 ASR 测试）→ 编号列出 KEEP / MERGE / REWRITE / DELETE / MOVE / BACKFILL-ADR 操作。

BACKFILL-ADR 是候选项，不是草稿——审查会指出它；是否加载 adr-backfill 由架构师决定。证据必须出现在两个相互独立的位置；reconstruction-confidence: low 时，将问题转入 open-questions.md。该流程文件列明了硬性约束（不得编辑 Accepted ADR 的正文、不得批量重新编号、不得自动生成 Owners、未经批准不得删除）以及审批后的流程。

反凑数规则

每份建议编写的文档都必须回答全部四个诊断问题（目的、受众、负责人、更新触发条件）。如果其中一项无法回答，就不应立即创建该文档。此规则同样适用于 ADR、RFC、操作指南、参考文档、说明文档、教程、运行手册、README 和 CONTRIBUTING。文档既有收益，也有成本——合适的文档数量应尽可能少，同时确保系统易于理解、操作和决策。

参考资料

• references/alternatives-catalog.md -- Diátaxis / RFC / 运行手册的适用场景
• references/failure-modes.md -- 十一种 ADR 失效模式及补救措施
• references/audit-procedure.md -- 含硬性约束的文件夹级审查流程
• references/changelog-canon.md -- Keep a Changelog 1.1 + SemVer 2.0.0
• references/runbook-canon.md -- 分页通知事件的运行手册结构（非操作指南）
• references/postmortem-canon.md -- 无责备复盘（PagerDuty + Google SRE）
• references/open-questions-canon.md -- 独立的待解问题登记表
• references/agentic-docs-canon.md -- AI Agent 上下文的 AGENTS.md 约定
• references/adr-template-catalog.md -- 模板索引（Nygard / MADR short / MADR long / Y-statement / Tyree-Akerman / arc42 §9）
• ../_shared/adr-is-not.md -- 规范的“ADR 不是什么”检查清单
• adr-discovery、adr-drafting、adr-critique 技能
• c4-model 技能 -- 规范的 C4 LikeC4 图表
• repo-health 技能 -- 社区健康文件（README / LICENSE / CONTRIBUTING / CODE_OF_CONDUCT / SECURITY / SUPPORT / templates / REUSE-SPDX）