adr-critique

adr-critique

针对遗留／外部／既有 ADR 的逐行审查工具。用于发现违反共享的“ADR 不是什么”规则、缺少理由说明、与相邻 ADR 不一致，以及与 LikeC4 模型存在偏差的问题。只修改架构师批准的行。

何时使用此技能

• 早于 adr-drafting 的 ADR（遗留文档集）
• 从其他团队导入的 ADR
• 由通用 LLM 工具生成、未经质疑的 ADR
• 定期对整个文档集进行质量检查

何时不使用此技能

• 已由 adr-drafting（第 6 阶段）自我审查过的 ADR——它们已通过筛选。
• 想要从头重写的 ADR——请改用 adr-drafting，并取代原 ADR。

风格规则

• 逐字引用有问题的行。 绝不转述 ADR 的内容。架构师必须看到受到批评的原文。
• 指出具体违反的规则。 引用 ../_shared/adr-is-not.md 中的章节（例如，“规则 5——泛泛引用最佳实践”）。
• 改写必须短于原文。 如果改写更长，那就是重新起草，而非审查——请转交给 adr-drafting。
• 每条消息只标记一个问题。 绝不批量列出违规之处。必须逐行获得架构师批准。
• 不作肯定评价。 不说“总体而言 ADR 很棒，只是有几个小问题”。不说“这是一个可靠的决策”。审查要么发现问题，要么没有。

术语

• 组件——C4 容器（可部署单元），而非代码类。
• 架构特征——要优化的非功能质量（延迟、成本、可维护性等）。
• 冲突——两个 ADR 彼此冲突，且都没有取代另一个；必须明确指出。
• 缺少理由说明——决策部分的论证依赖“最佳实践”或“行业标准”，而没有将业务关切与架构特征对应起来。
• 偏差——ADR 与 LikeC4 模型对现有组件或组件间关系的描述不一致。

六个阶段

阶段 1——阅读

加载目标 ADR。然后通过 supersedes、amends 和 relates-to 链接查找相邻 ADR，并逐一阅读。审查需要了解关联图的上下文。

如果 ADR 引用了 LikeC4 文件，则查找 **/*.c4 并阅读所引用的模型。

阶段 2——逐行标记

从上到下检查 ADR。每遇到一行违反规则，就使用此模板发出一条标记：

Original: <verbatim line from ADR>
Violates: <rule number and name from adr-is-not.md, OR "missing-why" / "drift" / "tension">
Rewrite:  <shorter, stricter replacement -- or "delete">
Apply?    (yes / no / adjust)

等待架构师回复。只有在对方回复后，才能继续处理下一条标记。

如果架构师选择 adjust，则接受其改写（但仍须满足短于原文的要求）。

阶段 3——检查理由是否缺失

重点检查决策部分。有效论证会将业务关切与架构特征联系起来。无效论证包括：

• “这是行业标准。”
• “这是微服务的最佳实践。”
• “大多数团队都这么做。”
• “这是推荐的方法。”

对于每一行无效内容，都用 Violates: missing-why 标记。改写时要补上缺失的联系（“由于合规要求数据驻留在 EU，此数据库支持按区域配置副本”），或者删除该行。

完整的理由缺失审查请参阅 references/audit-checklist.md。

阶段 4 — 一致性检查

检查 ADR 及其图邻居，查找以下问题：

• 冲突 — 两份 ADR 声称采用互不兼容的决策，且没有一份取代另一份。标记两份 ADR，并询问哪份取代另一份。
• 缺失的关系（frontmatter） — 后续决策声称取代 0004，但其 frontmatter 中没有 supersedes: ["0004"]；related/amended 链接不是有效的 YAML 列表；或者关系的唯一证据存在于正文行（例如 Related ADRs: [ADR-0004](0004-foo.md)）或决策日志 README.md 索引中。Gray-matter 风格的解析器只读取 frontmatter——仅存在于正文或索引中的链接不会为这类解析器生成图边。标记所有仅以正文描述的关系，并将其提升至 frontmatter（supersedes / amends / relates-to），使用补零到四位的字符串 ID。
• Frontmatter / 正文镜像不匹配 — doc-master 要求两处内容一致。标记以下各项：
  • Frontmatter 填写了 supersedes、amends 或 relates-to，但正文没有包含 ### Relationships 子章节的 ## More Information 章节来镜像这些关系，并使用 doc-master 的链接前缀词汇（Supersedes、Superseded by、Amends、Amended by、Related to）。这些 ADR 对正文扫描解析器（ADR Manager 等）不可见。
  • 正文有 ### Relationships 章节列出 ADR 之间的链接，但对应的 frontmatter 关系键为空或缺失。这些 ADR 对 gray-matter 风格的解析器（ADR Explorer 等）不可见。
  • 两处内容的关系集合不一致（例如，frontmatter 中为 supersedes: ["0004"]，但正文写着 Supersedes [ADR-0005]）。标记差异，并询问哪一处正确。
• 重复的权威声明 — 两份 ADR 声称对同一组件或决策具有权威性。其中一份必须让步。

有关一致性检查项，请参见 references/audit-checklist.md。

阶段 5 — LikeC4 漂移检查

对 **/*.c4 和任何 likec4.config.* 进行 Glob 匹配。将 ADR 中提及的组件名称与 LikeC4 模型进行比较：

• ADR 提及了 C4 模型中不存在的组件 → 指出存在漂移，并询问哪个来源为准。
• C4 模型中有 ADR 与之矛盾的组件 → 指出存在漂移。

不要自动更新任何一方。由架构师决定哪一方是事实来源。

阶段 6 — 应用已批准的更改

解决所有标记的问题后，在一次编辑中应用架构师批准的修改：

• 只修改已批准的行。
• 不要在文件中添加审核标记、[reviewed] 戳记或注释。
• 保留 frontmatter 和结构章节。
• 如果 ADR 的状态为 accepted，不要编辑正文，而应起草一份取代它的新 ADR。审核可以建议取代，但不能在未说明的情况下执行。

输出规范

• 绝不批量编辑。 逐行批准是确保审核有用的准则。
• 绝不编辑 Accepted ADR 的正文。 允许对 Accepted ADR 进行的修改：修正拼写错误、修正与图兼容的标题、仅修改元数据中的关系链接（且须得到项目治理规则的明确许可）、在标题中添加易于理解的 superseded by 注释，或在底部通过明确的标题添加带日期的“Amendments”注释。其他任何修改都应作为新 ADR 处理。
• 指出问题，不做决定。 标记冲突、漂移和缺少理由的问题，由架构师决定如何解决。
• 最后汇报。 应用修改后，输出一行摘要：“已审核 NNNN-title.md。提出 项标记，应用 项。尚有 项待处理：<列表>。”

参考资料

• references/audit-checklist.md — 阶段 3–5 使用的完整分章节检查项
• ../_shared/adr-is-not.md — Violates: 字段所引用的规范规则集
• adr-drafting skill — 用于全新起草的 ADR，而非审核 ADR
• c4-model skill — 用于解决阶段 5 中发现的 LikeC4 漂移