30b - AI辅助架构决策

┌─────────────────────────────────────────────────────────────┐
│                    多维度权衡矩阵                              │
├──────────────┬────────┬─────────┬─────────┬─────────────────┤
│ 评估维度      │ 权重   │ 方案 A  │ 方案 B  │ 方案 C          │
├──────────────┼────────┼─────────┼─────────┼─────────────────┤
│ 开发速度      │ 0.25   │ 5 (1.25)│ 3 (0.75)│ 4 (1.00)        │
│ 运维复杂度    │ 0.20   │ 5 (1.00)│ 2 (0.40)│ 3 (0.60)        │
│ 可扩展性      │ 0.15   │ 3 (0.45)│ 5 (0.75)│ 4 (0.60)        │
│ 团队匹配度    │ 0.15   │ 5 (0.75)│ 2 (0.30)│ 4 (0.60)        │
│ 成本效益      │ 0.10   │ 4 (0.40)│ 2 (0.20)│ 5 (0.50)        │
│ 安全合规      │ 0.10   │ 4 (0.40)│ 4 (0.40)│ 3 (0.30)        │
│ 长期维护      │ 0.05   │ 4 (0.20)│ 3 (0.15)│ 4 (0.20)        │
├──────────────┼────────┼─────────┼─────────┼─────────────────┤
│ 加权总分      │ 1.00   │ 4.45    │ 2.95    │ 3.80            │
└──────────────┴────────┴─────────┴─────────┴─────────────────┘

你是一位经验丰富的软件架构评估师，精通 ATAM（架构权衡分析方法）。
请对以下架构方案执行 ATAM 分析。

## 架构方案描述
[粘贴架构方案或设计文档]

## 关键质量属性场景
1. **性能场景**：[描述，如"1000 并发用户下，API 响应时间 P95 < 200ms"]
2. **可用性场景**：[描述，如"单节点故障时，系统在 30 秒内自动恢复"]
3. **安全性场景**：[描述，如"未授权用户无法访问其他租户数据"]
4. **可修改性场景**：[描述，如"添加新的支付方式需要 < 2 人天"]
5. **可扩展性场景**：[描述，如"用户量从 1 万增长到 100 万时的架构演进"]

## 请输出 ATAM 分析报告：

### 1. 架构方法识别
- 识别架构中使用的关键架构模式和策略
- 每个模式对应的质量属性

### 2. 质量属性效用树
- 将质量属性分解为具体场景
- 标注优先级（H/M/L）和风险（H/M/L）

### 3. 风险点（Risks）
- 识别架构中的风险点
- 每个风险的影响范围和严重程度

### 4. 敏感点（Sensitivity Points）
- 识别对质量属性影响最大的架构决策

### 5. 权衡点（Tradeoff Points）
- 识别影响多个质量属性的架构决策
- 分析这些决策在不同质量属性间的权衡

### 6. 改进建议
- 针对每个风险点提供具体的缓解措施
- 按优先级排序

┌─────────────────────────────────────────────────────────┐
│              架构方案全生命周期成本模型                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  初始成本（一次性）          运营成本（持续性）              │
│  ┌──────────────┐         ┌──────────────┐             │
│  │ · 开发人力成本 │         │ · 基础设施费用 │             │
│  │ · 学习曲线成本 │         │ · 运维人力成本 │             │
│  │ · 工具/许可费用│         │ · 监控/告警费用 │             │
│  │ · 环境搭建成本 │         │ · 安全合规费用 │             │
│  └──────────────┘         └──────────────┘             │
│                                                         │
│  演进成本（阶段性）          隐性成本（容易忽略）            │
│  ┌──────────────┐         ┌──────────────┐             │
│  │ · 架构迁移成本 │         │ · 技术债务利息 │             │
│  │ · 数据迁移成本 │         │ · 招聘/培训成本 │             │
│  │ · 停机/降级损失│         │ · 故障恢复成本 │             │
│  │ · 并行运行成本 │         │ · 机会成本     │             │
│  └──────────────┘         └──────────────┘             │
│                                                         │
└─────────────────────────────────────────────────────────┘

请为以下架构方案进行全生命周期成本效益分析：

## 方案描述
[架构方案摘要]

## 项目参数
- 团队规模：[人数]
- 开发者平均月薪：[金额]
- 项目周期：[月数]
- 预期运营年限：[年数]
- 云平台：[AWS/GCP/Azure]

## 请输出：

### 1. 初始成本估算（第 0-N 个月）
| 成本项 | 方案 A | 方案 B | 方案 C |
|--------|--------|--------|--------|
| 开发人力（人月 × 单价） | | | |
| 学习曲线（额外人天） | | | |
| 工具/许可费用 | | | |
| 环境搭建 | | | |
| **小计** | | | |

### 2. 月度运营成本估算
| 成本项 | 方案 A | 方案 B | 方案 C |
|--------|--------|--------|--------|
| 基础设施（计算/存储/网络） | | | |
| 第三方服务 | | | |
| 运维人力（占比） | | | |
| 监控/安全工具 | | | |
| **月度小计** | | | |

### 3. 3 年总拥有成本（TCO）
| | 方案 A | 方案 B | 方案 C |
|--|--------|--------|--------|
| 初始成本 | | | |
| 运营成本（36 个月） | | | |
| 预估演进成本 | | | |
| **3 年 TCO** | | | |

### 4. 成本风险因素
- 哪些成本项可能超出预估？
- 规模增长对成本的影响曲线
- 隐性成本提醒

# ADR-{编号}：{决策标题}
 
## 状态
 
{提议 | 已接受 | 已废弃 | 已替代（被 ADR-XXX 替代）}
 
## 日期
 
{YYYY-MM-DD}
 
## 背景
 
{描述决策的业务和技术背景。为什么需要做这个决策？当前面临什么问题或机会？}
 
## 决策驱动因素
 
- {驱动因素 1：如"团队规模限制"}
- {驱动因素 2：如"上线时间压力"}
- {驱动因素 3：如"合规要求"}
 
## 考虑的选项
 
### 选项 1：{选项名称}
 
{简要描述}
 
- ✅ 优势：{优势 1}、{优势 2}
- ❌ 劣势：{劣势 1}、{劣势 2}
 
### 选项 2：{选项名称}
 
{简要描述}
 
- ✅ 优势：{优势 1}、{优势 2}
- ❌ 劣势：{劣势 1}、{劣势 2}
 
### 选项 3：{选项名称}
 
{简要描述}
 
- ✅ 优势：{优势 1}、{优势 2}
- ❌ 劣势：{劣势 1}、{劣势 2}
 
## 决策结果
 
选择 **{选项 X}**，因为 {核心理由}。
 
### 权衡矩阵
 
| 维度 | 权重 | 选项 1 | 选项 2 | 选项 3 |
|------|------|--------|--------|--------|
| {维度 1} | {权重} | {评分} | {评分} | {评分} |
| {维度 2} | {权重} | {评分} | {评分} | {评分} |
| **加权总分** | | **{总分}** | **{总分}** | **{总分}** |
 
## 后果
 
### 正面后果
- {正面后果 1}
- {正面后果 2}
 
### 负面后果
- {负面后果 1}
- {负面后果 2}
 
### 风险与缓解
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| {风险 1} | {高/中/低} | {高/中/低} | {缓解措施} |
 
## 相关决策
 
- 依赖：{ADR-XXX}
- 被依赖：{ADR-YYY}
- 相关：{ADR-ZZZ}
 
## 备注
 
{任何补充信息、参考链接、讨论记录等}

┌─────────────────────────────────────────────────────────┐
│              对话式 ADR 生成工作流                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ① 描述决策背景    ② AI 生成选项    ③ 团队讨论          │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│  │ 架构师描述│───→│ AI 生成   │───→│ 团队审查  │         │
│  │ 决策上下文│    │ 3-5 个   │    │ 补充选项  │         │
│  │ 和约束条件│    │ 候选方案  │    │ 调整权重  │         │
│  └──────────┘    └──────────┘    └──────────┘         │
│                                       │                 │
│  ④ AI 生成权衡矩阵  ⑤ 确认决策    ⑥ AI 输出 ADR       │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐         │
│  │ 多维度评分│───→│ 团队确认  │───→│ 完整 ADR  │         │
│  │ 加权计算  │    │ 最终选择  │    │ Markdown  │         │
│  │ 可视化对比│    │ 记录理由  │    │ 归档版控  │         │
│  └──────────┘    └──────────┘    └──────────┘         │
│                                                         │
└─────────────────────────────────────────────────────────┘

我们需要做一个架构决策，请帮我生成 ADR。

## 决策背景
我们正在构建一个 [系统类型] 系统。当前需要决定 [决策主题]。

## 约束条件
- 团队：[规模和技术栈]
- 预算：[预算范围]
- 时间：[截止日期]
- 合规：[合规要求]
- 现有系统：[需要集成的系统]

## 已知的候选方案
1. [方案 A]（如果有的话）
2. [方案 B]

请先帮我：
1. 补充我可能遗漏的候选方案
2. 为每个方案列出优劣势
3. 建议评估维度和权重

感谢你的分析。基于团队讨论，我们做了以下调整：
- [调整 1：如"去掉方案 C，因为团队没有相关经验"]
- [调整 2：如"将'开发速度'的权重从 0.15 提高到 0.25"]
- [调整 3：如"补充一个评估维度：'社区生态成熟度'"]

请基于调整后的参数重新生成权衡矩阵，并输出完整的 ADR 文档。
我们的最终决策是选择 [方案 X]。

请扫描当前代码库，识别以下类型的架构决策：

1. **技术栈选择**：使用了哪些语言、框架、数据库、消息队列？
2. **架构模式**：采用了什么架构模式（单体/微服务/Serverless/事件驱动）？
3. **数据策略**：数据存储、缓存、一致性策略是什么？
4. **通信模式**：组件间如何通信（REST/gRPC/消息队列/事件）？
5. **安全策略**：认证、授权、加密方案是什么？
6. **部署策略**：如何部署（容器/Serverless/VM）？

对于每个识别到的决策，请推断：
- 可能的决策背景和动机
- 可能考虑过的替代方案
- 该决策的优势和潜在风险

请将审查后的 ADR 按以下格式归档：

目录结构：
docs/adr/
├── 0001-选择-typescript-作为主要语言.md
├── 0002-采用模块化单体架构.md
├── 0003-选择-postgresql-作为主数据库.md
├── 0004-使用-redis-作为缓存层.md
├── 0005-采用-jwt-认证方案.md
└── README.md  ← ADR 索引和使用指南

┌─────────────────────────────────────────────────────────┐
│              Kiro Spec 驱动 ADR 工作流                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  requirements.md          design.md                     │
│  ┌──────────────┐       ┌──────────────────┐           │
│  │ 需求 1        │       │ 架构概览          │           │
│  │ 需求 2        │──────→│ 组件设计          │           │
│  │ 需求 3        │       │ ┌──────────────┐ │           │
│  └──────────────┘       │ │ ADR 列表      │ │           │
│                          │ │ ADR-001: ...  │ │           │
│                          │ │ ADR-002: ...  │ │           │
│                          │ └──────────────┘ │           │
│                          └────────┬─────────┘           │
│                                   │                     │
│  tasks.md                         │                     │
│  ┌──────────────┐                │                     │
│  │ 任务清单      │◄───────────────┘                     │
│  │ （基于 ADR    │                                      │
│  │  约束实现）   │                                      │
│  └──────────────┘                                      │
│                                                         │
└─────────────────────────────────────────────────────────┘

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  提议     │───→│  已接受   │───→│  已废弃   │    │  已替代   │
│ Proposed │    │ Accepted │    │Deprecated│    │Superseded│
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │                │                              │
     │                │         ┌────────────────────┘
     │                │         │
     ▼                ▼         ▼
  团队审查         正常使用    新 ADR 引用
  可能被拒绝      直到上下文   "替代 ADR-XXX"
                  发生变化

请审查以下 ADR，评估其当前状态是否仍然有效：

## ADR 内容
[粘贴 ADR 内容]

## 当前项目状态
- 团队规模变化：[从 X 人变为 Y 人]
- 用户规模变化：[从 X DAU 变为 Y DAU]
- 技术栈变化：[新增/移除的技术]
- 业务需求变化：[新增的需求或约束]

请评估：
1. 该 ADR 的决策驱动因素是否仍然成立？
2. 是否有新的选项需要考虑？
3. 建议：维持/废弃/替代？
4. 如果建议替代，请生成新的 ADR 草稿

┌─────────────────────────────────────────────────────────┐
│              技术评估六维度模型                              │
├─────────────────────────────────────────────────────────┤
│                                                         │
│              ┌──────────────┐                           │
│              │   功能匹配度  │                           │
│              │  (Feature Fit)│                           │
│              └──────┬───────┘                           │
│                     │                                   │
│  ┌──────────────┐   │   ┌──────────────┐               │
│  │  生态成熟度   │───┼───│  性能与扩展性  │               │
│  │ (Ecosystem)  │   │   │ (Performance) │               │
│  └──────────────┘   │   └──────────────┘               │
│                     │                                   │
│  ┌──────────────┐   │   ┌──────────────┐               │
│  │  团队适配度   │───┼───│  成本效益     │               │
│  │ (Team Fit)   │   │   │ (Cost)       │               │
│  └──────────────┘   │   └──────────────┘               │
│                     │                                   │
│              ┌──────┴───────┐                           │
│              │  风险与长期性  │                           │
│              │ (Risk/Future)│                           │
│              └──────────────┘                           │
│                                                         │
└─────────────────────────────────────────────────────────┘

总分 = Σ (维度权重 × 维度评分)

其中：
- 维度评分：1-5 分（1=完全不满足，5=完全满足）
- 维度权重：0-1（所有权重之和 = 1）
- 总分范围：1-5

请帮我对以下技术候选方案进行初步筛选：

## 候选方案
[列出所有候选方案]

## 硬性标准（不满足即淘汰）
1. 必须支持 [语言/平台]
2. 必须有 [许可类型] 许可证
3. 月度成本不超过 [金额]
4. 必须支持 [合规标准]
5. 社区活跃度：最近 6 个月有持续更新

## 请输出：
1. 每个方案是否满足所有硬性标准
2. 不满足的方案及原因
3. 通过筛选的方案列表（进入详细评估阶段）

请对以下数据库候选方案进行场景化评估：

## 候选方案
1. PostgreSQL
2. MongoDB
3. DynamoDB

## 评估场景
### 场景 1：用户数据存储（强一致性，复杂查询）
- 数据模型：关系型，多表关联
- 查询模式：复杂 JOIN、聚合、全文搜索
- 一致性要求：强一致性
- 数据量：100 万-1000 万行

### 场景 2：事件日志存储（高写入，时序查询）
- 数据模型：半结构化，追加写入
- 查询模式：时间范围查询、聚合统计
- 一致性要求：最终一致性可接受
- 数据量：每天 1000 万条

### 场景 3：配置和元数据存储（低频读写，灵活 Schema）
- 数据模型：文档型，Schema 经常变化
- 查询模式：按 Key 查询，偶尔范围查询
- 一致性要求：强一致性
- 数据量：< 10 万条

## 请输出：
每个场景下各方案的评分（1-5）和推荐选择

请为以下技术选型生成完整的决策矩阵：

## 选型场景
[描述选型场景]

## 候选技术
1. [技术 A]
2. [技术 B]
3. [技术 C]
4. [技术 D]

## 项目约束
- [约束 1]
- [约束 2]
- [约束 3]

## 评估维度和权重
（如果不确定，请帮我建议合适的维度和权重）

## 输出要求
请生成以下内容：

### 1. 决策矩阵表格
包含：维度、权重、每个技术的评分（1-5）、加权分、总分排名

### 2. 雷达图数据
（用于可视化各技术在不同维度的表现）

### 3. 每个技术的一句话总结
格式："[技术名] 最适合 [场景]，但在 [维度] 上有短板"

### 4. 最终推荐
- 首选：[技术] — 理由
- 备选：[技术] — 在什么条件下选择备选
- 不推荐：[技术] — 理由

### 5. 风险提示
- 选择首选方案的主要风险
- 缓解措施

请帮我进行 [选型场景] 的技术选型对比分析。

## 项目背景
- 项目类型：[SaaS/电商/内部工具/API 平台/移动应用]
- 团队规模：[人数]
- 团队技术栈：[当前熟悉的技术]
- 预期规模：[用户量/数据量/请求量]
- 预算范围：[月度预算]
- 上线时间：[截止日期]

## 候选技术
1. [技术 A]
2. [技术 B]
3. [技术 C]

## 特殊需求
- [特殊需求 1，如"必须支持多租户"]
- [特殊需求 2，如"需要实时推送能力"]

## 请输出：

### 1. 快速对比表
| 维度 | [技术 A] | [技术 B] | [技术 C] |
|------|---------|---------|---------|
| 一句话定位 | | | |
| 最新稳定版本 | | | |
| 许可证 | | | |
| GitHub Stars | | | |
| 价格模型 | | | |

### 2. 详细评估矩阵
（包含 6 个维度的 1-5 评分和加权总分）

### 3. 场景化推荐
- 如果优先考虑 [开发速度]，选择 [X]
- 如果优先考虑 [性能]，选择 [Y]
- 如果优先考虑 [成本]，选择 [Z]

### 4. 迁移难度评估
- 从 [技术 A] 迁移到 [技术 B] 的难度和成本
- 从 [技术 B] 迁移到 [技术 A] 的难度和成本

### 5. 12 个月展望
- 各技术的发展趋势和路线图
- 潜在的风险信号（如维护者减少、商业化转向）

我们在 [技术 A] 和 [技术 B] 之间难以抉择。请帮我设计一个最小化的 PoC 来验证关键差异。

## 决策的关键不确定性
1. [不确定性 1，如"技术 A 在 1000 并发下的实际性能"]
2. [不确定性 2，如"技术 B 的学习曲线是否在团队可接受范围内"]
3. [不确定性 3，如"技术 A 的 XX 功能是否满足我们的需求"]

## PoC 约束
- 时间预算：[天数]
- 人力：[人数]

## 请输出：

### 1. PoC 范围定义
- 需要验证的具体假设（每个假设有明确的"通过/不通过"标准）
- 不需要在 PoC 中验证的内容

### 2. PoC 实现计划
- 每个技术的 PoC 实现步骤
- 预计耗时

### 3. 评估标准
- 定量指标（性能数据、代码行数、完成时间）
- 定性指标（开发体验、代码可读性、调试难度）

### 4. 决策规则
- 如果 [条件 A]，选择 [技术 A]
- 如果 [条件 B]，选择 [技术 B]
- 如果结果不明确，[后续行动]

❌ 错误：
"我们应该用微服务还是单体？"

✅ 正确：
"请为我们的系统提供 3 个架构方案（单体、模块化单体、微服务），
从开发速度、运维复杂度、扩展性、团队匹配度、成本 5 个维度进行对比，
每个维度给出 1-5 分评分和评分理由。"

❌ 错误：
"帮我选一个数据库"

✅ 正确：
"帮我为以下场景选择数据库：
- 数据模型：用户、订单、商品，强关系型
- 查询模式：80% 读、20% 写，需要复杂 JOIN
- 数据量：初期 100 万行，1 年后预计 5000 万行
- 并发：峰值 500 QPS
- 团队：3 人，熟悉 PostgreSQL，不熟悉 NoSQL
- 预算：月度数据库费用 < $100
- 合规：需要 GDPR 合规，数据驻留在欧洲"

✅ 好的 Prompt 补充：
"在推荐方案后，请扮演'魔鬼代言人'角色，
列出选择该方案可能遇到的 3 个最大风险，
以及在什么条件下应该重新考虑这个决策。"

✅ 好的 Prompt 补充：
"请分别从以下时间维度分析各方案：
- 短期（0-3 个月）：MVP 阶段的适用性
- 中期（3-12 个月）：增长阶段的适用性
- 长期（12+ 个月）：成熟阶段的适用性
如果不同阶段的最优方案不同，请说明演进路径。"

❌ 错误：
"哪个方案性能更好？"

✅ 正确：
"请估算各方案在以下场景下的性能指标：
- 场景：1000 并发用户，每秒 500 个 API 请求
- 指标：P50/P95/P99 响应时间、最大吞吐量、CPU/内存使用率
- 基于：官方基准测试数据或社区性能报告"

请从以下 4 个角色的视角分析"采用微服务架构"这个决策：

### 角色 1：CTO（关注技术战略和长期演进）
- 这个决策对技术战略的影响？
- 长期技术债务风险？

### 角色 2：开发团队 Lead（关注开发效率和团队体验）
- 对开发效率的影响？
- 团队学习成本？
- 日常开发体验变化？

### 角色 3：运维工程师（关注稳定性和可运维性）
- 运维复杂度变化？
- 监控和告警需求？
- 故障排查难度？

### 角色 4：CFO（关注成本和 ROI）
- 基础设施成本变化？
- 人力成本变化？
- 投资回报周期？

最后，综合 4 个角色的视角，给出平衡建议。

假设我们选择了 [方案 X]，请预设以下失败场景并分析应对策略：

1. **规模超预期**：用户量在 3 个月内增长 10 倍
   - 该方案能否应对？瓶颈在哪里？
   - 紧急扩展方案是什么？

2. **关键依赖故障**：[核心依赖] 服务宕机 2 小时
   - 系统影响范围？
   - 降级策略？

3. **团队变动**：核心开发者离职
   - 新人上手难度？
   - 知识传承风险？

4. **需求剧变**：需要支持 [新需求，如实时协作]
   - 当前架构能否适应？
   - 改造成本估算？

5. **安全事件**：发现 [安全漏洞类型]
   - 影响范围？
   - 修复难度和时间？

第 1 轮：高层方案对比
"请用一句话描述每个候选方案的核心优势和最大风险"

第 2 轮：聚焦关键差异
"基于第 1 轮分析，[维度 X] 是关键差异点。
请深入分析各方案在 [维度 X] 上的具体表现"

第 3 轮：验证假设
"你在分析中假设了 [假设 A]。
如果这个假设不成立（即 [反面情况]），结论会如何变化？"

第 4 轮：生成决策
"基于以上分析，请生成最终的决策矩阵和 ADR"

在你的分析中，请明确标注以下信息的确定性级别：

- 🟢 高确定性：基于官方文档、基准测试数据、广泛的社区验证
- 🟡 中确定性：基于社区经验分享、案例研究、合理推断
- 🔴 低确定性：基于有限信息的推测，建议通过 PoC 验证

这帮助我们识别哪些结论可以直接采信，哪些需要进一步验证。

project-root/
├── docs/
│   └── adr/
│       ├── README.md                          # ADR 索引和使用指南
│       ├── templates/
│       │   └── adr-template.md                # ADR 模板
│       ├── 0001-选择-typescript-作为主要语言.md
│       ├── 0002-采用模块化单体架构.md
│       ├── 0003-选择-postgresql-作为主数据库.md
│       ├── 0004-使用-jwt-认证方案.md
│       ├── 0005-采用-事件驱动通知系统.md
│       └── 0006-选择-redis-作为缓存层.md
├── .kiro/
│   └── steering/
│       └── architecture-rules.md              # 基于 ADR 的 Steering 规则
└── ...

# 架构决策记录（ADR）索引
 
## 使用指南
 
- 每个重要的架构决策都应该记录为一个 ADR
- ADR 编号递增，不重复使用
- 使用 `docs/adr/templates/adr-template.md` 作为模板
- ADR 一旦"已接受"，不修改原文，如需变更则创建新 ADR 并标记旧 ADR 为"已替代"
 
## ADR 列表
 
| 编号 | 标题 | 状态 | 日期 |
|------|------|------|------|
| 0001 | 选择 TypeScript 作为主要语言 | ✅ 已接受 | 2025-01-15 |
| 0002 | 采用模块化单体架构 | ✅ 已接受 | 2025-01-20 |
| 0003 | 选择 PostgreSQL 作为主数据库 | ✅ 已接受 | 2025-01-22 |
| 0004 | 使用 JWT 认证方案 | ⚠️ 已替代（→ 0008） | 2025-01-25 |
| 0005 | 采用事件驱动通知系统 | ✅ 已接受 | 2025-02-01 |
| 0006 | 选择 Redis 作为缓存层 | ✅ 已接受 | 2025-02-05 |

请基于以下 ADR 列表，生成对应的 Steering 规则：

## ADR 列表
- ADR-0002：采用模块化单体架构
- ADR-0003：选择 PostgreSQL 作为主数据库
- ADR-0006：选择 Redis 作为缓存层

## 请生成 Steering 规则，覆盖：
1. 模块边界约束（哪些模块不能直接依赖）
2. 数据访问约束（必须通过 Repository 层）
3. 缓存使用约束（什么数据应该/不应该缓存）
4. 禁止事项（基于 ADR 中的"负面后果"和"风险"）

# 架构约束 Steering 规则
# 基于 ADR-0002, ADR-0003, ADR-0006
 
## 模块边界（ADR-0002）
- 模块间通过公共接口通信，禁止直接导入其他模块的内部实现
- 每个模块拥有独立的数据库 Schema，禁止跨模块直接查询
- 新增模块必须先更新 ADR 或创建新 ADR
 
## 数据访问（ADR-0003）
- 所有数据库操作必须通过 Prisma ORM
- 禁止在业务逻辑层编写原始 SQL（除非有性能优化的 ADR 支持）
- 数据库迁移必须可回滚
 
## 缓存策略（ADR-0006）
- 缓存仅用于读多写少的数据（用户 Profile、配置、权限）
- 缓存 TTL 不超过 1 小时（除非有明确的业务需求）
- 缓存失效策略：写时失效（write-through invalidation）
- 禁止将缓存作为主要数据存储

请帮我设计一个架构决策审计系统，满足以下需求：

1. **决策记录**：每个 ADR 包含决策者、审批者、日期
2. **变更追踪**：ADR 的每次修改都有 Git 提交记录
3. **影响分析**：每个 ADR 关联受影响的代码模块
4. **定期审查**：每季度审查所有"已接受"的 ADR 是否仍然有效
5. **合规报告**：生成架构决策合规报告

## 输出：
1. ADR 模板中需要添加的审计字段
2. Git hook 配置（确保 ADR 变更有适当的 commit message）
3. 季度审查 Prompt 模板
4. 合规报告生成 Prompt 模板

我们即将召开架构评审会议，讨论 [决策主题]。
请帮我准备以下材料：

1. **决策背景摘要**（1 页，供所有参会者快速了解上下文）
2. **候选方案对比表**（包含权衡矩阵）
3. **讨论引导问题**（5-8 个关键问题，确保讨论覆盖所有重要维度）
4. **风险清单**（每个方案的 Top 3 风险）
5. **决策模板**（会议结束时填写的决策记录模板）

请基于以下会议讨论要点，更新架构决策分析：

## 会议讨论要点
1. [团队成员 A 提出的观点]
2. [团队成员 B 的反对意见]
3. [新发现的约束条件]
4. [达成的共识]
5. [仍有分歧的点]

## 请更新：
1. 权衡矩阵（基于新信息调整评分）
2. 风险清单（添加新识别的风险）
3. 如果达成决策，生成完整 ADR
4. 如果未达成决策，列出需要进一步调研的问题

架构评审会议已结束，决策结果如下：
- 选择方案：[方案 X]
- 关键理由：[理由]
- 待办事项：[列表]

请帮我：
1. 生成完整的 ADR 文档
2. 生成对应的 Steering 规则
3. 生成实施任务清单（可以直接放入 tasks.md）
4. 生成通知邮件/Slack 消息（告知相关团队决策结果）

┌─────────────────────────────────────────────────────────┐
│              异步架构决策工作流                              │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Day 1：提案                                            │
│  ┌──────────────────────────────────────────┐          │
│  │ 架构师 + AI 生成决策提案（ADR 草稿）        │          │
│  │ 提交 PR → docs/adr/0007-xxx.md           │          │
│  └──────────────────────────────────────────┘          │
│                     │                                   │
│  Day 2-4：评审                                          │
│  ┌──────────────────────────────────────────┐          │
│  │ 团队成员在 PR 中评论                        │          │
│  │ AI 辅助回应评论、更新分析                    │          │
│  │ 标注"同意/反对/需要更多信息"                 │          │
│  └──────────────────────────────────────────┘          │
│                     │                                   │
│  Day 5：决策                                            │
│  ┌──────────────────────────────────────────┐          │
│  │ 如果达成共识：合并 PR，ADR 状态→已接受       │          │
│  │ 如果有分歧：安排同步会议讨论                  │          │
│  │ AI 生成最终 ADR + Steering 规则             │          │
│  └──────────────────────────────────────────┘          │
│                                                         │
└─────────────────────────────────────────────────────────┘

你是一位拥有 15 年经验的软件架构师，擅长多维度权衡分析。
请对以下架构决策进行系统化的权衡分析。

## 决策主题
[描述需要做的架构决策]

## 项目背景
- 项目类型：[类型]
- 团队规模：[人数]
- 技术栈：[当前技术栈]
- 预期规模：[用户量/数据量]
- 预算：[预算范围]
- 时间约束：[截止日期]

## 候选方案
1. [方案 A]
2. [方案 B]
3. [方案 C]

## 分析要求

### 1. 多维度评估矩阵
请从以下维度评估（每个维度 1-5 分，附评分理由）：
- 开发速度（MVP 交付时间）
- 运维复杂度（Day 2 运维成本）
- 可扩展性（应对 10x 增长的能力）
- 团队匹配度（学习曲线和现有技能匹配）
- 成本效益（3 年 TCO）
- 安全合规（满足合规要求的难度）
- 长期演进（技术过时风险和演进灵活性）

### 2. 权衡点分析
识别影响多个维度的关键权衡点，说明"选择 A 意味着在 B 上妥协"。

### 3. 风险矩阵
每个方案的 Top 3 风险，标注概率和影响。

### 4. 推荐决策
- 首选方案及核心理由
- 在什么条件下应该选择备选方案
- 决策的有效期（在什么条件下需要重新评估）

### 5. 确定性标注
对每个评分标注确定性级别：
🟢 高确定性 | 🟡 中确定性 | 🔴 低确定性（建议 PoC 验证）

请帮我进行数据库选型的权衡分析。

## 应用场景
- 数据模型：[关系型/文档型/键值/图/时序]
- 读写比例：[如 80:20]
- 数据量：[当前和预期]
- 并发量：[峰值 QPS]
- 一致性要求：[强一致/最终一致]
- 查询模式：[简单查询/复杂 JOIN/全文搜索/聚合分析]

## 候选数据库
1. [数据库 A]
2. [数据库 B]
3. [数据库 C]

## 请从以下维度分析：
1. **数据模型匹配度**：数据库的数据模型是否天然适合应用场景
2. **查询性能**：在目标查询模式下的性能表现
3. **写入性能**：在目标写入模式下的性能表现
4. **扩展策略**：水平扩展/垂直扩展的能力和复杂度
5. **运维复杂度**：备份、恢复、监控、升级的难度
6. **生态工具**：ORM 支持、管理工具、监控工具
7. **成本**：许可费 + 基础设施费 + 运维人力
8. **团队经验**：团队对该数据库的熟悉程度

## 输出格式
1. 评估矩阵（含评分和理由）
2. 场景化推荐（不同场景可能选择不同数据库）
3. 混合方案建议（如果适用）
4. 迁移路径（如果未来需要切换）

请帮我选择最适合的架构模式。

## 系统需求
[描述系统的核心功能和非功能需求]

## 候选架构模式
1. **单体架构**（Monolith）
2. **模块化单体**（Modular Monolith）
3. **微服务**（Microservices）
4. **Serverless**
5. **事件驱动**（Event-Driven）

## 评估约束
- 团队规模：[人数]
- 团队经验：[对各模式的熟悉程度]
- 预期规模：[用户量/请求量]
- 上线时间：[截止日期]
- 运维能力：[有/无专职运维]

## 请输出：
1. **淘汰分析**：哪些模式在当前约束下明显不适合？为什么？
2. **深度对比**：对剩余候选模式进行详细权衡分析
3. **演进路径**：推荐的架构演进路线（从 MVP 到成熟期）
4. **混合建议**：是否建议混合使用多种模式？如何组合？

请帮我生成一份架构决策记录（ADR）。

## 决策标题
[简短描述决策内容]

## 决策背景
[描述为什么需要做这个决策]

## 已考虑的选项
1. [选项 A]：[简述]
2. [选项 B]：[简述]
3. [选项 C]：[简述]

## 最终选择
[选项 X]

## 选择理由
[核心理由]

## 请按 MADR 格式输出完整 ADR，包含：
1. 状态
2. 日期
3. 背景（扩展描述）
4. 决策驱动因素
5. 考虑的选项（每个选项的详细优劣分析）
6. 决策结果
7. 权衡矩阵
8. 正面后果
9. 负面后果
10. 风险与缓解措施
11. 相关决策

请扫描以下代码结构，识别架构决策并生成 ADR：

## 项目结构
[粘贴 tree 命令输出或目录结构]

## 关键配置文件
[粘贴 package.json、docker-compose.yml、terraform 配置等]

## 请识别并生成 ADR：
1. 识别至少 5 个重要的架构决策
2. 对每个决策推断可能的背景和动机
3. 列出可能考虑过的替代方案
4. 分析当前选择的优劣势
5. 按 MADR 格式输出每个 ADR

## 注意：
- 标注哪些推断是"高确定性"（基于代码证据），哪些是"推测"
- 对于推测性内容，建议与团队确认

以下 ADR 需要更新，因为项目上下文发生了变化。

## 原始 ADR
[粘贴原始 ADR 内容]

## 上下文变化
1. [变化 1，如"团队从 3 人增长到 10 人"]
2. [变化 2，如"用户量从 1 万增长到 50 万"]
3. [变化 3，如"新增了实时协作需求"]

## 请评估：
1. 原始决策是否仍然有效？
2. 如果需要变更，推荐的新方案是什么？
3. 迁移策略和成本估算
4. 生成新的 ADR（状态为"提议"），并在原 ADR 中标注"已替代"

请对 [技术名称] 进行全面的技术评估。

## 评估目的
[为什么要评估这个技术？计划用在什么场景？]

## 评估维度

### 1. 技术成熟度
- 当前版本和发布历史
- 重大版本的发布频率
- 向后兼容性记录
- 已知的重大 Bug 或限制

### 2. 社区与生态
- GitHub Stars / npm 下载量 / 社区规模
- 文档质量和完整性
- 第三方库和插件数量
- Stack Overflow 问题数量和回答质量
- 企业采用案例

### 3. 性能特征
- 官方基准测试数据
- 社区性能对比报告
- 已知的性能瓶颈
- 优化空间和策略

### 4. 安全性
- CVE 历史记录
- 安全更新响应速度
- 内置安全特性
- 合规认证

### 5. 开发体验
- 学习曲线评估
- IDE/工具支持
- 调试体验
- 错误信息质量

### 6. 商业因素
- 许可证类型
- 价格模型（如果是商业产品）
- 供应商锁定风险
- 长期路线图和资金支持

## 输出格式
1. 评估摘要（一段话）
2. 评分卡（每个维度 1-5 分）
3. SWOT 分析
4. 推荐/不推荐的使用场景
5. 风险提示

请为以下技术选型生成决策矩阵。

## 选型场景
[描述选型场景和需求]

## 候选技术
1. [技术 A]
2. [技术 B]
3. [技术 C]
4. [技术 D]

## 评估维度和权重
| 维度 | 权重 | 说明 |
|------|------|------|
| 功能匹配度 | [权重] | [说明] |
| 性能 | [权重] | [说明] |
| 生态成熟度 | [权重] | [说明] |
| 团队适配度 | [权重] | [说明] |
| 成本 | [权重] | [说明] |
| 风险 | [权重] | [说明] |

（如果不确定权重，请根据项目类型建议合适的权重分配）

## 请输出：

### 决策矩阵
| 维度 | 权重 | [技术 A] | [技术 B] | [技术 C] | [技术 D] |
|------|------|---------|---------|---------|---------|
| ... | ... | 评分(加权) | 评分(加权) | 评分(加权) | 评分(加权) |
| **总分** | | **X.XX** | **X.XX** | **X.XX** | **X.XX** |

### 评分依据
（每个评分的简要理由）

### 敏感性分析
（如果调整权重，结论是否会变化？哪些维度的权重变化会导致不同的推荐？）

### 最终推荐
- 🥇 首选：[技术] — [一句话理由]
- 🥈 备选：[技术] — [在什么条件下选择]
- ⚠️ 不推荐：[技术] — [一句话理由]

我们是一个 5 人全栈团队，要在 6 个月内构建 B2C 电商平台 MVP。
团队熟悉 TypeScript/React/PostgreSQL。
预期初期 5000 DAU，1 年内增长到 5 万 DAU。
月度基础设施预算 $500。

请帮我识别需要做的关键架构决策，按优先级排序。

关键架构决策清单（按优先级）：

1. 🔴 P0：整体架构模式（单体 vs 微服务 vs Serverless）
2. 🔴 P0：后端框架选型（Express vs Fastify vs NestJS vs Hono）
3. 🔴 P0：数据库策略（单库 vs 读写分离 vs 多库）
4. 🟡 P1：前端框架/元框架（Next.js vs Remix vs Nuxt）
5. 🟡 P1：认证方案（Auth0 vs Clerk vs 自建）
6. 🟡 P1：支付集成（Stripe vs 自建支付网关）
7. 🟡 P1：搜索方案（PostgreSQL 全文搜索 vs Meilisearch vs Algolia）
8. 🟢 P2：缓存策略（Redis vs 应用层缓存）
9. 🟢 P2：文件存储（S3 vs Cloudflare R2）
10. 🟢 P2：部署平台（Vercel + Railway vs AWS ECS vs Fly.io）

请帮我进行后端框架选型的权衡分析。

项目：B2C 电商平台，TypeScript，5 人团队
候选：Express、Fastify、NestJS、Hono

评估维度权重：
- 开发速度：0.25（6 个月 MVP 压力大）
- TypeScript 支持：0.20（团队全 TS）
- 性能：0.15（5 万 DAU 不算高并发）
- 生态成熟度：0.20（需要丰富的中间件）
- 学习曲线：0.10（团队有 Express 经验）
- AI 工具支持：0.10（大量使用 AI 辅助开发）

| 维度 | 权重 | Express | Fastify | NestJS | Hono |
|------|------|---------|---------|--------|------|
| 开发速度 | 0.25 | 4 (1.00) | 4 (1.00) | 3 (0.75) | 4 (1.00) |
| TypeScript 支持 | 0.20 | 3 (0.60) | 5 (1.00) | 5 (1.00) | 5 (1.00) |
| 性能 | 0.15 | 3 (0.45) | 5 (0.75) | 4 (0.60) | 5 (0.75) |
| 生态成熟度 | 0.20 | 5 (1.00) | 4 (0.80) | 4 (0.80) | 3 (0.60) |
| 学习曲线 | 0.10 | 5 (0.50) | 4 (0.40) | 2 (0.20) | 4 (0.40) |
| AI 工具支持 | 0.10 | 5 (0.50) | 4 (0.40) | 4 (0.40) | 3 (0.30) |
| **总分** | **1.00** | **4.05** | **4.35** | **3.75** | **4.05** |

推荐：Fastify
- 首选理由：TypeScript 原生支持最好，性能最优，生态足够成熟
- 风险：部分 Express 中间件不兼容，需要寻找 Fastify 替代
- 备选：Express（如果团队不愿学习新框架）

基于以上分析，请生成完整的 ADR。
决策：选择 Fastify 作为后端框架。

# ADR-0002：选择 Fastify 作为后端 API 框架
 
## 状态
已接受
 
## 日期
2025-XX-XX
 
## 背景
团队需要为 B2C 电商平台选择后端 API 框架。团队 5 人，全部使用 TypeScript，
有 Express 经验。项目需要在 6 个月内交付 MVP，预期 1 年内支持 5 万 DAU。
 
## 决策驱动因素
- 6 个月 MVP 时间压力，需要高开发效率
- 团队全面使用 TypeScript，需要一流的 TS 支持
- 预期 5 万 DAU，需要合理的性能表现
- 大量使用 AI 辅助开发，需要 AI 工具对框架有良好支持
 
## 考虑的选项
 
### 选项 1：Express
- ✅ 最成熟的 Node.js 框架，生态最丰富
- ✅ 团队已有经验，零学习成本
- ❌ TypeScript 支持需要额外配置
- ❌ 性能在候选方案中最低
 
### 选项 2：Fastify
- ✅ 原生 TypeScript 支持，类型安全的路由和插件
- ✅ 性能优异（比 Express 快 2-3 倍）
- ✅ 插件系统设计优秀，生态快速增长
- ❌ 部分 Express 中间件不兼容
 
### 选项 3：NestJS
- ✅ 企业级架构，内置依赖注入、模块系统
- ✅ TypeScript 原生支持
- ❌ 学习曲线陡峭（装饰器、DI、模块概念）
- ❌ 对 5 人团队来说架构过重
 
### 选项 4：Hono
- ✅ 超轻量，性能极致
- ✅ 多运行时支持（Node.js/Deno/Bun/Edge）
- ❌ 生态较新，第三方库较少
- ❌ AI 工具的训练数据中 Hono 示例较少
 
## 决策结果
选择 **Fastify**，因为它在 TypeScript 支持、性能和生态成熟度之间
提供了最佳平衡，且学习成本对有 Express 经验的团队来说可控。
 
## 后果
 
### 正面后果
- TypeScript 类型安全贯穿路由、插件、请求/响应
- 性能余量充足，5 万 DAU 无压力
- 插件系统便于模块化组织代码
 
### 负面后果
- 需要 1-2 周学习 Fastify 的插件系统和生命周期
- 部分 Express 中间件需要寻找 Fastify 替代或编写适配器
 
### 风险与缓解
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| Express 中间件不兼容 | 中 | 低 | 使用 @fastify/express 兼容层 |
| 团队学习成本超预期 | 低 | 中 | 安排 1 周集中学习，编写团队 Fastify 指南 |

# 后端框架 Steering 规则（基于 ADR-0002）
 
## 框架使用
- 使用 Fastify 作为 HTTP 框架，禁止引入 Express
- 路由定义使用 Fastify 的 TypeScript 类型系统
- 插件使用 Fastify 的 fp（fastify-plugin）模式封装
 
## 中间件
- 优先使用 Fastify 原生插件（@fastify/ 前缀）
- 如果必须使用 Express 中间件，通过 @fastify/express 适配
- 自定义中间件使用 Fastify 的 hook 系统（onRequest/preHandler/onSend）
 
## 性能
- 使用 Fastify 的 JSON Schema 验证（而非 Joi/Zod 运行时验证）
- 利用 Fastify 的序列化优化（fast-json-stringify）
- 避免在请求处理中使用同步操作