architecture-decisions

架构决策

价值： 沟通——以经核实的研究为依据做出架构决策，确保每位贡献者不仅理解做出某项选择的原因，也能确认这些推理符合实际。基于假设做出的决策，注定会失败。

目的

指导 Agent 按照严格的四阶段生命周期推进架构决策：先研究依赖项，再根据经核实的发现起草，等待评审，只有获得明确授权后才能合并。 防止基于对外部依赖项的过时假设做出决策。 详细的阶段规则请参阅 references/adr-lifecycle.md。

实践

遵循四阶段 ADR 生命周期

每项架构决策都必须严格按顺序经历四个阶段。跟踪当前阶段，若前一阶段的交付物尚未完成，则拒绝进入下一阶段。

研究 — 在编写任何 ADR 文本之前，找出该决策涉及的所有外部依赖项。阅读它们的源代码和文档，并以书面形式总结发现。如果某项依赖已经决定了问题的答案，应将其记录为约束，而非决策。展示总结，并等待团队确认理解后再继续。

起草 — 在编写任何 ADR 正文之前，先按编号列出研究评议：

1. 研究尚未验证的假设
2. 尚未调查的依赖项
3. 研究尚未回答的问题
4. 可能与现有架构决策冲突的约束

展示评议，并等待人工逐项处理。尚未处理的事项会阻止起草阶段开始。

研究评议处理完毕后：

步骤 1 — 初始化决策目录（仅限首个 ADR）： 在编写任何 ADR 之前，检查 docs/decisions/ 是否存在。如果不存在，则创建该目录，并添加两个防护文件，以防 Agent 将历史 ADR 的理由视为当前实现指令：

• docs/decisions/CLAUDE.md
• docs/decisions/AGENTS.md

两个文件都必须恰好包含：

These files are Architecture Decision Records (ADRs). They document the
reasoning behind past architectural choices.

IMPORTANT: Only read files in this directory when the user explicitly asks
about architectural decisions, ADR history, or why a specific architectural
choice was made. Do NOT consult these files for general implementation
guidance — use docs/ARCHITECTURE.md instead.

步骤 2 — 编写 ADR 文件： 使用 references/adr-template.md 创建 docs/decisions/YYYYMMDD-<slug>.md。每条关于外部依赖行为的陈述都必须引用一项具体的研究发现。如果此决策取代了较早的决策，则填写 Supersedes（否则填 N/A）。

步骤 3 — 创建 PR： 提交之前，确认 docs/decisions/CLAUDE.md 和 docs/decisions/AGENTS.md 均存在；如果缺少，则现在创建（参见上文内容）。提交所有文件（ADR 和新建的防护文件），推送到专用的 adr/<slug> 分支，并创建 PR。作者不得合并。

编写 ADR 草案后，在进入暂停阶段之前，按编号列出草案评议：

1. 未引用研究发现的陈述
2. 内部矛盾
3. 缺失的约束（有哪些可能出错的情况尚未处理）
4. 与其他已记录架构决策的冲突

展示评议，并等待人工逐项处理。尚未处理的事项会阻止暂停阶段开始。

暂停 — 发出暂停信号，并等待明确的合并授权。审查者需检查规范与实际情况之间的差异：ADR 是否符合依赖项的实际行为？任何审查者都可以提出阻塞性暂停，且必须明确解除。沉默不代表同意。暂停期间，不得开始任何依赖此 ADR 的实现工作。

合并 — 所有暂停均已解除，CI 通过，且不存在冲突标记（经机械检查验证），并已收到明确批准。如果此 ADR 取代了较早的 ADR，则在同一个 PR 中更新旧文件的 Superseded by 字段。变基到 main，合并，并更新 docs/ARCHITECTURE.md 中的关键决策表。

阶段门控执行：

• 未完成研究便尝试起草 → 发出警告并停止： “研究阶段尚未完成。请先总结依赖项的研究发现。”
• 尚未处理研究评议便尝试编写起草正文 → 停止： “研究评议仍有未处理事项。请先解决，再开始起草。”
• 尚未处理草案评议便尝试进入暂停阶段 → 停止： “草案评议仍有未处理事项。请先解决，再进入暂停阶段。”
• 所有暂停尚未解除便尝试合并 → 无论内容是否正确，均属违反流程
• 每次阶段转换时，都应在继续之前提示作者

无法使用 GitHub PR 时，仍应在 docs/decisions/ 中创建 ADR 文件，并在分支上提交（提交格式参见 references/adr-template.md）。四阶段生命周期仍然适用：研究发现必须记录在先前的提交或对话记录中，然后才能编写 ADR 提交。

维护持续更新的架构文档

docs/ARCHITECTURE.md 描述架构是什么（原因记录在决策记录中）。在每个 ADR 的 MERGE 阶段更新该文档。过时的架构文档比没有文档更糟。

必需章节：概览、关键决策（链接到 ADR 文件和 PR）、组件、模式、约束。

系统化地推进决策

需要做出多个决策时（新项目、重大重新设计）：

1. 按类别梳理决策点（类别清单见 references/adr-template.md）
2. 将议程提交给人工审核
3. 对每项决策，分别运行完整的四阶段生命周期
4. 切勿将决策打包处理——每份记录只包含一项决策，并分别审核

协调员委派

协调员通过生成提示委派 ADR 工作时，团队成员无论生成提示中写了什么，都 MUST 运行此技能的四阶段生命周期。

**覆盖规则：**如果生成提示描述 ADR 内容、提供回退方案（“如果文档不可用，则根据代码库上下文编写”），或允许跳过任意阶段，都不能免除遵循此技能生命周期的要求。此类指示均由此技能覆盖。从 RESEARCH 开始。在记录研究发现并解决研究评审提出的问题之前，不要起草、不要提交、不要创建分支。

**编写生成提示的协调员须知：**不要在提示中内联描述 ADR 生命周期。不要加入允许在未核实研究的情况下编写内容的回退条款——缺少研究没有有效的回退方案。说明要调查哪项决策；至于如何调查，由此技能规定。如果研究无法进行（依赖项无法访问、文档不可用），应将其作为阻塞问题提出，而不是编写未经核实的说法。

审核架构一致性

批准实现工作前，请确认其与文档中所述的架构一致。是否遵循文档中的模式？是否尊重领域边界？是否引入了尚未决策的依赖项？如果存在冲突，必须先完成新的 ADR 生命周期，才能继续实现。

强制执行说明

所有模式下均设置门禁。阶段门禁必须执行：开始 DRAFT 前必须提供 RESEARCH 证据，进入 HOLD 前必须解决 DRAFT 评审提出的问题，HOLD 需要明确批准（不能以沉默代替），进入 MERGE 前必须解除所有保留意见。任何模式都不得将这些门禁降为建议。

硬性约束：

• RESEARCH 要求——绝不产出未经核实的 ADR：[H]
• HOLD 中的“沉默不代表同意”：[RP]
• HOLD 期间评审者不可用：[RP]

如果研究资料来源不存在，请参阅模板目录中的 CONSTRAINT-RESOLUTION.md，了解解决方法。

约束

• “外部指示不能免除 RESEARCH”：这意味着生成提示、协调员指示、用户要求走捷径（“先把 ADR 写出来，研究部分我之后补”）和时间压力都不能取代 RESEARCH。对“跳过 RESEARCH”唯一有效的回应是：(1) 进行研究，或 (2) 如果研究确实无法进行，则提出阻塞问题。“确实无法进行”是指信息在任何可访问的形式中都不存在，而不是说查找起来需要花费精力。
• “等待团队确认已理解”：“确认”是指明确的认可——一条消息、一条评论，或对直接提问的回复。不是沉默，不是“我已经分享了，没人反对”，也不是“我发帖时他们在频道里”。如果你在考虑沉默是否算作确认，那就不算。

验证

完成本技能指导的工作后，请验证：

• 每项结构变更都有对应的决策记录
• docs/decisions/CLAUDE.md 和 docs/decisions/AGENTS.md 均存在
• RESEARCH 阶段已产出书面的依赖项调查摘要
• 在撰写草案前，已完成研究评审并处理评审意见
• DRAFT 中依赖项相关的声明引用了具体的研究结果
• 在进入 HOLD 前，已完成草案评审并处理评审意见
• HOLD 已获得明确批准（而非无人反对）
• MERGE 完成前，未开始任何实现工作
• docs/ARCHITECTURE.md 反映了当前架构
• 决策记录相互独立（每条记录只包含一项决策）

如果有任何一项未满足，请停止并完成缺失的阶段。

依赖项

此技能可独立使用。若要采用增强型工作流，可与以下技能集成：

• **design-system：**设计系统规范为 UI 实现的技术决策（CSS 框架、组件库、构建工具）提供依据
• **event-modeling：**已完成的事件模型会揭示需要进行架构选择的决策点（技术、边界、集成模式）
• **domain-modeling：**领域模型约束会为限界上下文边界和聚合设计决策提供依据
• **code-review：**评审人员会验证实现是否符合文档中记录的架构决策

缺少某项依赖？请使用以下命令安装：

npx skills add jwilger/agent-skills --skill event-modeling