architecture-decision

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,team.size

已解析如上 — 按原样使用；--review 会覆盖 review_mode。没有区块 → 默认值见 .claude/docs/config-resolution.md。

架构决策

调用此技能时：

0. 解析参数 — 检测 Retrofit / Acceptance 模式

完整检查模式见 .claude/docs/director-gates.md。各个门控定义位于 .claude/docs/director-gates/[gate-id].md — 被启动的 Agent 会读取自己的门控文件；父会话不要读取该文件。

每次 AskUserQuestion 调用都遵循 .claude/docs/automation-modes.md （协作模式始终询问 · 引导模式仅针对重大事项 · 自主模式记录并继续； automation_always_ask 类别始终提示）。

team.size：确定由哪些 Agent 验证此 ADR（与 review_mode/workflow 相互独立）。

• individual（默认）：technical-director（TD-ADR）+ 引擎专家。
• small 和 studio：相同的两个 Agent。此技能不会启动引擎子专家，也不会在任何规模下启动对抗性审查者。

docs.density — 它控制 ADR 文本部分的详略程度，而不是骨架输出哪些部分（这些部分固定不变）。modes.rigor 会与 workflow 一同设置此项；若只想调整 ADR 的详略程度，请显式设置 docs.density： terse（默认值，通过 rigor: minimal 设置）= 决策和备选方案以项目符号列出，每项理由用一行说明； balanced = 每个部分各用一段简要说明理由（rigor: standard）；thorough = 完整阐述，并在 Decision、Alternatives 和 Consequences 中说明权衡和详细理由。将其应用于文本部分；Engine Compatibility、ADR Dependencies 和 GDD Requirements 表格属于结构性内容，在任何详略级别下都应完整保留。

workflow（参见 .claude/docs/workflow-modes.md）：

• full — 必须完成 ADR 列表中要求的所有 ADR。
• standard — 仅处理关键 ADR（Foundation 层系统）。
• minimal — 无需完成。仍可自愿执行。

如果参数以 retrofit 开头，后接文件路径

现在读取 references/0-retrofit.md 并遵循其中的说明 — 此阶段的步骤位于该文件中，而非此处。如果在此阶段对话经过压缩或恢复，请再次读取该文件。

如果参数以 accept 开头，后接 ADR ID

现在读取 references/0-accept.md 并遵循其中的说明 — 此阶段的步骤位于该文件中，而非此处。如果在此阶段对话经过压缩或恢复，请再次读取该文件。

如果不处于 retrofit 或 acceptance 模式，则继续执行下方的步骤 1（正常编写 ADR）。

无参数保护：如果未提供参数（标题为空），请先询问，然后再运行第 0 阶段：

"你要记录哪项技术决策？请提供一个简短标题 （例如：event-system-architecture、physics-engine-choice）。"

使用用户的回复作为标题，然后继续执行步骤 1。

---

1. 加载引擎上下文（始终首先执行）

现在读取 references/1-engine-context.md 并遵循其中的说明 — 此阶段的步骤位于该文件中，而非此处。如果在此阶段对话经过压缩或恢复，请再次读取该文件。

2. 确定下一个 ADR 编号

扫描 docs/architecture/ 中现有的 ADR，确定下一个编号。

---

3. 收集上下文

现在读取 references/3-gather-context.md 并遵循其中的说明 — 此阶段的步骤位于该文件中，而非此处。如果在此阶段对话经过压缩或恢复，请再次读取该文件。

4. 协作引导决策

现在读取 references/4-decide.md 并遵循其中的说明 — 此阶段的步骤位于该文件中，而非此处。如果在此阶段对话经过压缩或恢复，请再次读取该文件。

5. 生成 ADR

现在读取 references/5-generate.md 并遵循其中的说明 — 此阶段的步骤位于该文件中，而非此处。如果在此阶段对话经过压缩或恢复，请再次读取该文件。

6. 收尾后续步骤

写好 ADR（并可选择更新注册表）后，以 AskUserQuestion 收尾。

生成小组件前：

1. 按章节读取 docs/architecture/architecture.md 中的 ## Required ADRs 部分，并列出 docs/architecture/adr-*.md：必需的 ADR 即使没有对应文件，也仍视为未编写。如果没有 architecture.md，则查找 technical-preferences.md 或 systems-index.md 中标记为前置条件的 ADR
2. 检查所有前置 ADR 是否都已编写。如果是，则加入一个“开始编写 GDD”选项。
3. 将所有剩余的优先级 ADR 分别列为选项，不要只列接下来的一两个。

小组件格式：

ADR-[NNNN] written and registry updated. What would you like to do next?
[1] Write [next-priority-adr-name] — [brief description from prerequisites list]
[2] Write [another-priority-adr] — [brief description]  (include ALL remaining ones)
[N] Start writing GDDs — run `/design-system [first-undesigned-system]` (only show if all prerequisite ADRs are written)
[N+1] Stop here for this session

如果没有剩余的优先级 ADR，也没有尚未设计的 GDD 系统，则只提供“到此为止”选项，并建议在新的会话中运行 /architecture-review。

收尾输出中始终包含以下固定提示（不得省略）：

要根据 GDD 验证 ADR 覆盖情况，请打开一个全新的 Claude Code 会话 并运行 /architecture-review。

切勿在与 /architecture-decision 相同的会话中运行 /architecture-review。 审查 Agent 必须独立于编写上下文，才能给出公正的评估。在此处运行该命令会使审查失效。

不要在此处解除故事的阻塞。 此 ADR 的状态为 Proposed——第 5 步已保证这一点，因等待此决策而被阻塞的故事仍在等待此决策。编写 ADR 时解除阻塞，会在防护机制开始发挥作用时将其破坏：流水线看似顺畅运行，实际依赖的却是无人接受的决策。

应告知用户当前有哪些事项正等待接受：

“ADR-NNNN 已编写，状态为 Proposed。仍有 [N] 个故事因等待此 ADR 而处于 Blocked 状态。 决策确定后，请运行 /architecture-decision accept ADR-NNNN——此操作会将它们转为 Ready。”

按路径列出被阻塞的故事，以明确显示保留 Proposed 状态的代价。 （接受决策会产生由许多技能强制执行的后果，而授权记录却只存在于少数几个地方，因此两者之间的流程必须保持明确。）