# 阶段 3：方案决策技能书

## A. 元数据 (Metadata)

**name**: `phase3-decision`

**description**: 在 Datai 项目中，基于已创建的设计文档，分析至少两种技术方案，进行架构决策，生成标准化的决策记录（ADR），并更新索引和会话记录。此技能确保技术决策的可追溯性和合理性。

---

## B. 触发与定位 (Triggers & Scope)

### 触发关键词
当用户输入包含以下关键词时，必须觉醒此技能：
- "架构决策"、"ADR"、"决策记录"
- "技术方案对比"、"方案分析"
- "进入阶段 3"、"下一阶段"
- "决策"、"选择方案"、"方案评估"

### 触发场景
- 用户确认阶段 2 完成，要求进入阶段 3
- 用户要求创建决策记录（ADR）
- 用户询问如何进行技术方案决策
- 用户提到"按照项目规则"或"SSOT 流程"进行决策

### 操作路径
此技能涉及以下文件和目录的操作：
- **读取**: `docs/design/YYYY-MM-DD-00X-设计名.md` (阶段 2 创建的设计文档)
- **创建**: `docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md`
- **更新**: `docs/index.md`
- **更新**: `docs/design/YYYY-MM-DD-00X-设计名.md` (添加决策记录引用)
- **更新**: `docs/sessions/YYYY-MM-DD-00X-session.md`
- **读取**: `.trae/rules/project_rules.md` (项目规则)
- **读取**: `docs/Prompt/0004-单一真源文档驱动架构师.md` (SSOT 架构师提示词)

### SSOT 依赖
必须参考以下"唯一真源"：
- [设计文档](file:///d:\idea_demo\datai\docs\design\YYYY-MM-DD-00X-设计名.md) - 阶段 2 创建的设计文档
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) - 项目规则和阶段定义
- [0004-单一真源文档驱动架构师.md](file:///d:\idea_demo\datai\docs\Prompt\0004-单一真源文档驱动架构师.md) - SSOT 架构师提示词
- `docs/decisions/` 目录下的现有决策记录（作为格式参考）
- `docs/decisions/adr/0000-template.md` (ADR 模板)

---

## C. 核心指令集 (Instructions)

### 架构约束

#### 1. 文档命名规范（强制）
- 必须使用格式：`YYYY-MM-DD-00X-ADR-决策名.md`
- `YYYY-MM-DD`：当前日期（如 2026-01-21）
- `00X`：需求编号（与阶段 1、2 保持一致）
- `决策名`：简洁描述，使用中文，如"用户登录功能-技术选型"
- **严禁**使用英文、拼音或无意义的文件名

#### 2. 文档结构约束（强制）
决策记录必须包含以下章节，顺序不能改变：
```markdown
# ADR-001: 决策标题

## 状态
已接受/已废弃/已替代

## 日期
YYYY-MM-DD

## 背景
[决策背景]

## 决策
[决策内容]

## 后果
### 正面影响
- [正面影响1]
- [正面影响2]

### 负面影响
- [负面影响1]
- [负面影响2]

## 替代方案
- [替代方案1]
- [替代方案2]

## 相关文档
- [需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)
- [设计文档](../design/YYYY-MM-DD-00X-设计名.md)
```

#### 3. 决策约束（强制）
- 必须分析至少两种技术方案的优缺点
- 必须有明确的决策理由
- 必须考虑与已有 ADR 记录的冲突
- 必须记录决策的正面影响和负面影响
- 必须记录替代方案

#### 4. 强制校验（强制）
- 必须检查方案是否冲突于已有的 ADR 记录
- 必须使用 SearchCodebase 工具搜索已有的 ADR 记录
- 如果发现冲突，必须重新评估方案或更新已有 ADR 记录

#### 5. 索引更新约束（强制）
- 必须在创建决策记录后立即更新 `docs/index.md`
- 必须更新设计文档，添加决策记录引用
- 采用增量更新策略，**严禁**删除现有内容
- 索引链接格式：`[文档名](./相对路径/文件名.md)`
- 必须在 `docs/index.md` 中添加到"决策记录"部分

#### 6. 会话记录约束（强制）
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
- 必须更新当前阶段为"阶段 3：方案决策"
- 必须记录关键决策内容
- 必须记录决策记录链接

### 业务逻辑 SOP（标准操作流程）

#### 步骤 1：决策分析（Let's think step by step）
在创建决策记录前，必须执行以下分析：

1. **识别关键决策点**
   - 读取阶段 2 创建的设计文档
   - 识别设计文档中的技术选型、架构设计、集成方案等关键决策点
   - 确定需要进行 ADR 记录的决策点

2. **分析至少两种技术方案的优缺点**
   - **方案 1**：
     - 技术选型
     - 优点
     - 缺点
     - 适用场景
   - **方案 2**：
     - 技术选型
     - 优点
     - 缺点
     - 适用场景
   - （可选）**方案 3**：
     - 技术选型
     - 优点
     - 缺点
     - 适用场景

3. **确定最终决策和理由**
   - 基于方案优缺点对比，确定最终选择的方案
   - 说明选择该方案的理由
   - 说明放弃其他方案的理由
   - 考虑方案的可行性、成本、风险、可维护性等因素

#### 步骤 2：强制校验
1. **搜索已有 ADR 记录**
   - 使用 SearchCodebase 工具搜索 `docs/decisions/` 目录下的所有 ADR 记录
   - 检查是否有与当前决策冲突的记录
   - 如果发现冲突，重新评估方案或更新已有 ADR 记录

2. **确认决策的一致性**
   - 确认决策与项目规则一致
   - 确认决策与 SSOT 架构师提示词一致
   - 确认决策与需求文档一致

#### 步骤 3：创建决策记录
1. **确定文档路径**
   - 路径：`docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md`
   - 使用 Write 工具创建文件
   - 确保目录存在（使用 LS 工具检查）

2. **填充文档内容**
   - **标题**：`ADR-00X: 决策标题`
   - **状态**：已接受/已废弃/已替代
   - **日期**：当前日期
   - **背景**：决策的背景和上下文
   - **决策**：最终选择的方案和理由
   - **后果**：
     - 正面影响
     - 负面影响
   - **替代方案**：列出所有考虑过的方案
   - **相关文档**：添加需求文档和设计文档链接

3. **文档质量检查**
   - 使用 Read 工具读取刚创建的文档
   - 检查是否符合文档结构约束
   - 检查是否有遗漏的章节
   - 检查决策理由是否充分

#### 步骤 4：更新索引和设计文档
1. **读取现有索引**
   - 使用 Read 工具读取 `docs/index.md`
   - 找到"决策记录"部分
   - 如果不存在，则创建该部分

2. **添加新决策链接**
   - 在"决策记录"部分追加新决策
   - 格式：`- [决策名](./decisions/YYYY-MM-DD-00X-ADR-决策名.md) - [状态]`
   - 示例：`- [用户登录功能-技术选型](./decisions/2026-01-21-001-ADR-用户登录功能-技术选型.md) - 已接受`

3. **更新设计文档**
   - 使用 Read 工具读取设计文档
   - 在"相关文档"部分添加决策记录链接
   - 格式：`- [决策记录](../decisions/YYYY-MM-DD-00X-ADR-决策名.md)`
   - 使用 Write 工具更新设计文档

4. **保存索引**
   - 使用 Write 工具更新 `docs/index.md`
   - **严禁**删除现有内容，只追加新内容

#### 步骤 5：更新会话记录
1. **读取现有会话记录**
   - 使用 Read 工具读取 `docs/sessions/YYYY-MM-DD-00X-session.md`

2. **更新阶段 3 信息**
   - 更新"当前阶段"为"阶段 3：方案决策"
   - 更新"阶段 3：方案决策"的状态为"已完成"
   - 添加生成文档链接
   - 添加关键决策内容

3. **保存会话记录**
   - 使用 Write 工具更新会话记录

#### 步骤 6：确认与询问
1. **向用户确认**
   - 显示决策记录的链接
   - 询问："决策是否合理？"
   - 询问："是否进入下一阶段（数据库结构生成）？"

2. **等待用户反馈**
   - 如果用户不满意，询问具体需要修改的地方
   - 如果用户要求回退，执行回退机制（见错误陷阱部分）
   - 如果用户确认，标记阶段 3 为已完成，准备进入阶段 4

### 工具调用

#### 必须使用的工具
1. **Read 工具**：读取现有文件
   - 使用场景：读取设计文档、读取索引、读取会话记录、读取已有 ADR 记录
   - 命令：`Read(file_path="d:\\idea_demo\\datai\\docs\\design\\2026-01-21-001-用户登录功能-设计.md")`

2. **Write 工具**：创建或更新文件
   - 使用场景：创建决策记录、更新索引、更新设计文档、更新会话记录
   - 命令：`Write(file_path="d:\\idea_demo\\datai\\docs\\decisions\\2026-01-21-001-ADR-用户登录功能-技术选型.md", content="...")`

3. **LS 工具**：检查目录是否存在
   - 使用场景：创建文档前检查 `docs/decisions/` 目录
   - 命令：`LS(path="d:\\idea_demo\\datai\\docs")`

4. **SearchCodebase 工具**：搜索已有 ADR 记录
   - 使用场景：检查方案是否冲突于已有的 ADR 记录
   - 命令：`SearchCodebase(information_request="查找 docs/decisions 目录下的所有 ADR 记录")`

#### 可选使用的工具
1. **Glob 工具**：查找文件
   - 使用场景：查找所有决策记录
   - 命令：`Glob(pattern="docs/decisions/*.md")`

2. **TodoWrite 工具**：管理任务
   - 使用场景：跟踪阶段执行进度
   - 命令：`TodoWrite(todos=[...])`

---

## D. 错误陷阱与验证 (Anti-Patterns & Checklist)

### 常见错误（Anti-Patterns）

#### 错误 1：不分析多种方案直接决策
**错误示例**：
```
用户：进入阶段 3
AI：直接创建决策记录，只分析一种方案
```

**正确示例**：
```
用户：进入阶段 3
AI：让我先分析至少两种技术方案...
AI：方案 1：使用 Spring Security + JWT
AI：方案 2：使用 Shiro + Redis
AI：分析两种方案的优缺点...
AI：基于分析，选择方案 1...
```

#### 错误 2：决策理由不充分
**错误示例**：
```markdown
## 决策
选择方案 1，因为它更好。
```

**问题**：
- 决策理由过于简单
- 没有说明为什么选择方案 1
- 没有说明放弃其他方案的理由

**正确示例**：
```markdown
## 决策
选择方案 1（Spring Security + JWT），理由如下：
1. 与项目现有技术栈（Spring Boot）集成更好
2. 社区活跃度高，文档丰富
3. 安全性更高，支持更多认证方式
4. 已在公司其他项目中广泛使用，开发人员熟悉

放弃方案 2（Shiro + Redis）的理由：
1. 与 Spring Boot 集成不如 Spring Security 紧密
2. 社区活跃度相对较低
3. 安全性功能不如 Spring Security 全面
```

#### 错误 3：不检查已有 ADR 记录
**错误示例**：
```
AI：创建决策记录，不检查已有 ADR 记录
AI：发现决策与已有 ADR 记录冲突
```

**正确示例**：
```
AI：使用 SearchCodebase 工具搜索已有 ADR 记录
AI：检查是否有与当前决策冲突的记录
AI：如果没有冲突，继续创建决策记录
AI：如果有冲突，重新评估方案或更新已有 ADR 记录
```

#### 错误 4：不更新设计文档的决策记录引用
**错误示例**：
```
AI：创建决策记录
AI：更新 docs/index.md
AI：完成（忘记更新设计文档）
```

**正确示例**：
```
AI：创建决策记录
AI：更新 docs/index.md
AI：更新设计文档，添加决策记录引用
AI：完成
```

#### 错误 5：不询问用户确认就进入下一阶段
**错误示例**：
```
AI：创建决策记录
AI：进入阶段 4：数据库结构生成（未询问用户）
```

**正确示例**：
```
AI：创建决策记录
AI：决策记录已创建：[链接]
AI：决策是否合理？
AI：是否进入下一阶段（数据库结构生成）？
```

### 验收清单（Checklist）

在完成阶段 3 前，必须检查以下项目：

#### 文档完整性检查
- [ ] 决策记录已创建在 `docs/decisions/` 目录下
- [ ] 文档命名符合 `YYYY-MM-DD-00X-ADR-决策名.md` 格式
- [ ] 文档包含所有必需章节（标题、状态、日期、背景、决策、后果、替代方案、相关文档）
- [ ] 状态已正确填写（已接受/已废弃/已替代）
- [ ] 日期已正确填写
- [ ] 背景清晰、无歧义
- [ ] 决策理由充分
- [ ] 后果包含正面影响和负面影响
- [ ] 替代方案至少包含两种
- [ ] 相关文档链接正确

#### 决策合理性检查
- [ ] 分析了至少两种技术方案
- [ ] 每种方案都有明确的优缺点
- [ ] 决策理由充分且合理
- [ ] 考虑了方案的可行性、成本、风险、可维护性等因素

#### 强制校验检查
- [ ] 使用 SearchCodebase 工具搜索了已有 ADR 记录
- [ ] 检查了方案是否冲突于已有的 ADR 记录
- [ ] 如果有冲突，已解决冲突

#### 索引更新检查
- [ ] `docs/index.md` 已更新
- [ ] 新决策链接已添加到"决策记录"部分
- [ ] 索引链接格式正确：`[文档名](./相对路径/文件名.md)`
- [ ] 索引更新采用增量策略，未删除现有内容

#### 设计文档更新检查
- [ ] 设计文档已更新
- [ ] 设计文档的"相关文档"部分已添加决策记录引用
- [ ] 决策记录链接格式正确：`[决策记录](../decisions/YYYY-MM-DD-00X-ADR-决策名.md)`

#### 会话记录更新检查
- [ ] 会话记录已更新
- [ ] 会话记录的"当前阶段"已更新为"阶段 3：方案决策"
- [ ] 会话记录的"阶段 3：方案决策"状态已更新为"已完成"
- [ ] 会话记录包含决策记录链接
- [ ] 会话记录包含关键决策内容

#### 用户确认检查
- [ ] 已向用户显示决策记录链接
- [ ] 已询问用户"决策是否合理？"
- [ ] 已询问用户"是否进入下一阶段？"
- [ ] 已等待用户反馈

#### 回退机制检查（如果需要）
- [ ] 如果用户不满意，已询问具体需要修改的地方
- [ ] 如果用户要求回退，已删除相关文档
- [ ] 如果用户要求回退，已撤销索引更新
- [ ] 如果用户要求回退，已撤销设计文档更新
- [ ] 如果用户要求回退，已更新会话记录

### Correct vs Incorrect 代码对比

#### Incorrect（错误示例）
```markdown
# ADR-001: 用户登录功能技术选型

## 状态
已接受

## 日期
2026-01-21

## 背景
用户登录功能需要选择认证方案。

## 决策
选择 Spring Security + JWT。

## 后果
### 正面影响
- 好

### 负面影响
- 不好

## 替代方案
- 其他方案

## 相关文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
```

#### Correct（正确示例）
```markdown
# ADR-001: 用户登录功能技术选型

## 状态
已接受

## 日期
2026-01-21

## 背景
用户登录功能需要选择一个可靠的认证方案，满足以下要求：
1. 与 Spring Boot 集成良好
2. 支持 JWT Token 认证
3. 支持密码加密
4. 支持权限控制
5. 社区活跃度高，文档丰富

## 决策
选择方案 1：Spring Security + JWT，理由如下：
1. 与项目现有技术栈（Spring Boot）集成更好
2. 社区活跃度高，文档丰富
3. 安全性更高，支持更多认证方式（OAuth2、OpenID Connect 等）
4. 已在公司其他项目中广泛使用，开发人员熟悉
5. 支持密码加密（BCrypt）和权限控制

## 后果
### 正面影响
1. 开发效率高，与现有技术栈集成良好
2. 安全性高，支持多种认证方式
3. 维护成本低，社区活跃度高
4. 开发人员熟悉，学习成本低

### 负面影响
1. 配置相对复杂
2. 入门门槛较高

## 替代方案

### 方案 2：Shiro + Redis
- **优点**：配置简单，入门门槛低
- **缺点**：与 Spring Boot 集成不如 Spring Security 紧密，安全性功能不如 Spring Security 全面
- **适用场景**：小型项目，对安全性要求不高的项目

### 方案 3：自定义认证方案
- **优点**：完全定制化，符合项目特定需求
- **缺点**：开发成本高，安全性难以保证，维护成本高
- **适用场景**：对认证方案有特殊要求的项目

## 相关文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
```

---

## 附录：快速参考

### 文件路径速查
- 设计文档：`docs/design/YYYY-MM-DD-00X-设计名.md`
- 决策记录：`docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md`
- 主索引：`docs/index.md`
- 会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
- 项目规则：`.trae/rules/project_rules.md`
- SSOT 架构师提示词：`docs/Prompt/0004-单一真源文档驱动架构师.md`

### 工具命令速查
```powershell
# 读取设计文档
Read(file_path="d:\\idea_demo\\datai\\docs\\design\\2026-01-21-001-用户登录功能-设计.md")

# 创建决策记录
Write(file_path="d:\\idea_demo\\datai\\docs\\decisions\\2026-01-21-001-ADR-用户登录功能-技术选型.md", content="...")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 更新索引
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")

# 搜索已有 ADR 记录
SearchCodebase(information_request="查找 docs/decisions 目录下的所有 ADR 记录")

# 查找所有决策记录
Glob(pattern="docs/decisions/*.md")
```

### 阶段 3 输出清单
- [ ] 决策记录：`docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md`
- [ ] 更新的索引：`docs/index.md`
- [ ] 更新的设计文档：`docs/design/YYYY-MM-DD-00X-设计名.md`
- [ ] 更新的会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`

### 下一阶段提示
如果用户确认进入下一阶段，请参考：
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) 的"阶段 4：数据库结构生成"
- 准备分析需求是否涉及数据库变更
- 准备生成 SQL 脚本
- 准备更新索引和会话记录