架构决策（Architecture Decision）

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

输入要求

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

执行流程

第一步：识别决策点

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

第二步：列出候选方案

至少 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**: [接受的代价]

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

失败回退机制

质量标准

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

关联 reference

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

architecture-decision.md 4.9 KB История Исходник