# 架构决策（Architecture Decision）

本 reference 是通用最小架构决策模板，覆盖任意方案取舍场景（架构方案/模块拆分/实现取舍）。与 `tech-selection`（技术栈级选型）和 `spec-driven-development`（Spec 级）互补，不重复定义决策流程。

## 输入要求

1. **决策点**（必填）：需要做出取舍的问题，一句话表述
2. **候选方案**（必填）：至少 2 个真实可选方案（禁止只列 1 个凑数）
3. **约束条件**（可选）：性能 / SLA / 团队能力 / 兼容性 / 成本等硬约束
4. **上下文**（可选）：模块边界、调用方、数据规模、现状代码

## 执行流程

### 第一步：识别决策点

- 明确"要决策什么"，把多个决策点拆开，逐个走本流程
- 判定是否命中复杂度门槛（见下）

### 第二步：列出候选方案

- 至少 2 个真实方案；方案间必须是**不同策略**，而非同策略参数微调
- 单一合理实现（低复杂度改动）→ 可豁免，标注"单一合理实现，跳过反选论证"

### 第三步：逐方案 trade-off

对每个候选方案：

| 维度 | 内容 |
| - | - |
| 优势 | 核心卖点 / 在约束下的匹配度 |
| 劣势 | 代价 / 风险 / 局限 |
| 适用场景 | 什么情况下它是最优 |
| 不适用场景 | 明确排除的情况 |

### 第四步：选择与反选论证

- **选择**：首选方案 + 选型理由（基于需求匹配度与约束）
- **反选论证（必填）**：逐条说明「为何不选备选方案」——备选方案的 trade-off 为何在本项目约束下不可接受。只给"首选+理由"视为不完整；反选论证须说明「为何不选 B」，而非仅罗列「为何选 A」（对齐 `tech-selection.md` 反选论证）
- **接受的代价**：首选方案已知的技术债与限制

### 第五步：撤销条件与验证

- **撤销条件**：什么情况下重新评估此决策（数据规模/团队/技术环境变化的触发点）
- **验证**：选择落地后，须按方案执行验证（benchmark / EXPLAIN / 边界用例 / 实测），与 `performance-benchmark.md`、`mysql-database.md` 的验证闭环衔接

### 第六步：留痕沉淀

- 决策记录写入「决策记录」节（见下）
- 经 `project-memory-management` 的 Decision Record 模式沉淀到项目记忆，撤销条件随记录保存

## 复杂度门槛

| 条件 | 动作 |
| - | - |
| 多候选方案 / 跨模块影响 / 高影响决策 | 强制走完整流程并输出决策记录 |
| 单一合理实现 / 低复杂度改动（单文件小功能） | 豁免，输出说明"单一合理实现，无候选方案" |

## 输出格式

```
## 架构决策记录（Architecture Decision Record）

- **决策点**：[一句话]
- **候选方案**：A / B / [C]
- **选择**：[方案]
- **选择理由**：[基于需求与约束]
- **反选论证**：[为何不选 B/C，逐条 trade-off]
- **接受的代价**：[已知技术债 / 限制]
- **撤销条件**：[什么情况下重新评估]
- **验证**：[验证方式 + 预期结果]
```

## 决策记录模板（沉淀到项目记忆用）

```
## Decision Record: [决策名称]

**日期**: [YYYY-MM-DD]
**问题**: [要解决的技术问题]

### 选项分析
| 选项 | 优势 | 劣势 | 适用场景 |
| - | - | - | - |
| [选项A] | ... | ... | ... |
| [选项B] | ... | ... | ... |

### 决策
**选择**: [最终选项]
**理由**: [核心原因]
**Trade-offs**: [接受的代价]

### 撤销条件
[什么情况下重新评估]
```

## 失败回退机制

| 步骤 | 失败条件 | 回退目标 | 最大重试 | 不可恢复时升级路径 |
| - | - | - | - | - |
| 第二步：列候选方案 | 只能想到 1 个方案 | 标注"单一合理实现"，豁免本流程 | 0 | 直接进入实现，交付时说明无候选 |
| 第四步：反选论证 | 备选与首选 trade-off 接近难以取舍 | 输出决策矩阵，标注推荐项与依据 | 2 | 建议 POC 验证后由用户拍板 |
| 第五步：验证 | 验证手段不可用（无环境/无工具） | 标注"验证受限" + 最小可执行验证路径 | 1 | 输出限制说明，交用户决定是否继续 |

## 质量标准

- 决策必须基于实际约束（需求/规模/团队/兼容性），不能泛泛而谈
- 反选论证必须具体：说清"为什么不是 B"，而非"B 也不错"
- 撤销条件必须可操作（可触发、可判定），不能"如有需要再评估"
- 高影响决策未留痕即交付 → 按「无验证证据=未完成」红线处置

## 关联 reference

- **tech-selection**（技术选型）— 技术栈级选型，本 reference 聚焦实现方案级取舍
- **spec-driven-development**（Spec驱动开发）— 其「Architecture Decisions」为本 reference 的 Spec 场景应用
- **code-generation**（代码生成）— 生成前若命中复杂度门槛，须先走本流程产出决策记录
- **project-memory-management**（项目记忆管理）— 决策记录沉淀