datai/docs/archive/skill/0005-architecture-decision.md

---
name: 0005-architecture-decision
description: 方案决策，基于 ADR 模板创建架构决策记录
---

# 技能：架构决策 (Architecture Decision)

## 元数据 (Metadata)

- **name**: architecture-decision
- **description**: 方案决策，基于 ADR 模板创建架构决策记录
- **version**: 1.0.0
- **author**: SSOT Architect
- **lastUpdated**: 2026-01-15

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

### 触发条件 (Triggers)
当以下情况发生时，AI 应当"觉醒"本技能：

1. **需求已定义**: 完成需求定义后，需要制定技术方案
2. **技术选型**: 需要在多个技术方案中选择
3. **架构变更**: 需要记录架构变更决策
4. **方案冲突**: 发现现有方案与新需求冲突
5. **工作流阶段 2**: 用户进入工作流的"方案决策"阶段

### 定位范围 (Scope)
- **适用模块**: 所有 Datai 项目模块
- **影响文件**: `docs/decisions/adr/ADR-XXX.md`, `docs/index.md`
- **相关技能**: skill-define-requirements, skill-prompt-engineering

## 核心指令集 (Instructions)

### 架构约束 (Architecture Constraints)

1. **ADR 文档命名规范**:
   - 格式: `ADR-XXX.md`
   - XXX: 三位数字，从 001 开始递增
   - 示例: `ADR-001.md`, `ADR-002.md`

2. **ADR 必须包含**:
   - 决策标题
   - 状态（Draft/Accepted/Deprecated）
   - 背景（为什么要做这个决策）
   - 决策内容（我们决定做什么）
   - 后果（好的后果与坏的后果）
   - 合规性验证（如何验证决策已被执行）

3. **决策流程要求**:
   - 针对该需求，分析至少两种技术方案
   - 记录选定方案的理由、潜在风险及回滚策略
   - **强制校验**: 检查方案是否冲突于已有的 ADR 记录

### 业务逻辑 SOP (Business Logic SOP)

#### 步骤 1: 分析技术方案
```markdown
## 技术方案分析

### 方案 A: [方案名称]
**描述**: [方案描述]

**优点**:
- [优点1]
- [优点2]

**缺点**:
- [缺点1]
- [缺点2]

**风险**:
- [风险1]
- [风险2]

**成本评估**:
- 开发成本: [高/中/低]
- 维护成本: [高/中/低]
- 学习成本: [高/中/低]

### 方案 B: [方案名称]
**描述**: [方案描述]

**优点**:
- [优点1]
- [优点2]

**缺点**:
- [缺点1]
- [缺点2]

**风险**:
- [风险1]
- [风险2]

**成本评估**:
- 开发成本: [高/中/低]
- 维护成本: [高/中/低]
- 学习成本: [高/中/低]

### 方案对比
| 维度 | 方案 A | 方案 B |
|------|--------|--------|
| 开发成本 | [评估] | [评估] |
| 维护成本 | [评估] | [评估] |
| 性能 | [评估] | [评估] |
| 可扩展性 | [评估] | [评估] |
| 团队熟悉度 | [评估] | [评估] |
```

#### 步骤 2: 选择最优方案
```markdown
## 决策结果

### 选定方案
**方案**: [方案名称]

### 选择理由
1. [理由1]
2. [理由2]
3. [理由3]

### 放弃方案的原因
**方案 A**: [放弃原因]
**方案 B**: [放弃原因]
```

#### 步骤 3: 检查冲突
```markdown
## 冲突检查

### 已有 ADR 检查
- [ADR-001](./ADR-001.md): [冲突检查结果]
- [ADR-002](./ADR-002.md): [冲突检查结果]

### 冲突解决
[如果有冲突，说明如何解决]
```

#### 步骤 4: 创建 ADR 文档
```markdown
---
name: ADR-001
description: [决策描述]
---

# [决策标题]

## 元数据 (Metadata)

- **决策编号**: ADR-001
- **决策标题**: [决策标题]
- **状态**: [Draft | Accepted | Deprecated]
- **日期**: YYYY-MM-DD
- **决策者**: [决策者姓名]
- **相关需求**: [REQ-XXX](../../requirements/REQ-XXX.md)

## 背景 (Context)

### 问题描述
[为什么要做这个决策？]

### 当前状态
[当前系统状态]

### 问题影响
[问题对系统的影响]

### 约束条件
- [约束1]
- [约束2]

## 决策 (Decision)

### 决策内容
[我们决定做什么？]

### 技术方案
[详细的技术方案]

### 实施计划
[实施步骤和时间表]

### 回滚策略
[如果决策失败，如何回滚]

## 后果 (Consequences)

### 正面影响
[好的后果]

### 负面影响
[坏的后果和 Trade-offs]

### 风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| [风险1] | [高/中/低] | [高/中/低] | [缓解措施] |
| [风险2] | [高/中/低] | [高/中/低] | [缓解措施] |

### 权衡分析
[详细分析权衡取舍]

## 合规性验证 (Compliance)

### 验证标准
[如何验证决策已被执行？]

### 验证方法
[验证的具体方法]

### 验证结果
[验证结果记录]

### 成功指标
| 指标 | 目标值 | 实际值 | 状态 |
|------|--------|--------|------|
| [指标1] | [目标值] | [实际值] | [状态] |
| [指标2] | [目标值] | [实际值] | [状态] |

## 相关文档 (Related Documents)

- [需求文档](../../requirements/REQ-XXX.md)
- [设计文档](../../design/DES-XXX.md)
- [其他 ADR](./ADR-XXX.md)

## 变更历史 (Change History)

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| YYYY-MM-DD | 1.0.0 | 初始版本 | [姓名] |
```

#### 步骤 5: 更新 docs/index.md
```markdown
### 🎯 架构决策 (ADRs)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [ADR-001](decisions/adr/ADR-001.md) | ✅ Accepted | [决策描述] | 2026-01-15 |
```

### 工具调用 (Tool Usage)

1. **ADR 编号生成工具**:
   - 使用 `Grep` 工具搜索 `docs/decisions/adr/` 目录
   - 查找最大的 ADR 编号
   - 生成新的 ADR 编号

2. **冲突检查工具**:
   - 使用 `Read` 工具读取现有 ADR 文档
   - 使用 `SearchCodebase` 工具搜索相关技术方案
   - 分析是否存在冲突

3. **文件创建工具**:
   - 使用 `Write` 工具创建 ADR 文档
   - 确保文件路径正确

4. **索引更新工具**:
   - 使用 `Read` 工具读取 `docs/index.md`
   - 使用 `SearchReplace` 工具更新索引

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

### 常见错误 (Anti-Patterns)

1. **错误**: 只分析一种技术方案
   - **后果**: 无法做出最优决策
   - **修正**: 必须分析至少两种技术方案

2. **错误**: 忽略冲突检查
   - **后果**: 决策可能与现有架构冲突
   - **修正**: 必须检查与已有 ADR 的冲突

3. **错误**: 缺少回滚策略
   - **后果**: 决策失败后无法恢复
   - **修正**: 必须制定详细的回滚策略

4. **错误**: 后果分析不全面
   - **后果**: 无法全面评估决策影响
   - **修正**: 必须分析正面和负面后果

5. **错误**: 缺少合规性验证
   - **后果**: 无法验证决策是否被执行
   - **修正**: 必须定义验证标准和验证方法

### 验收清单 (Acceptance Checklist)

- [ ] ADR 文档已创建
- [ ] ADR 编号符合规范
- [ ] 至少分析两种技术方案
- [ ] 已进行冲突检查
- [ ] 已选择最优方案
- [ ] 已说明选择理由
- [ ] 已制定回滚策略
- [ ] 已分析正面和负面后果
- [ ] 已定义验证标准
- [ ] docs/index.md 已更新
- [ ] 相关文档已链接

### Correct vs Incorrect 对比

#### Correct 示例
```markdown
## 技术方案分析

### 方案 A: 使用 REST API
**优点**:
- 标准化，易于理解和维护
- 支持多种数据格式（JSON/XML）
- 易于测试和调试

**缺点**:
- 性能相对较低
- 不适合实时通信

**成本评估**:
- 开发成本: 低
- 维护成本: 低
- 学习成本: 低

### 方案 B: 使用 GraphQL
**优点**:
- 灵活，按需获取数据
- 减少网络请求次数
- 类型安全

**缺点**:
- 学习曲线陡峭
- 缓存复杂度高

**成本评估**:
- 开发成本: 中
- 维护成本: 中
- 学习成本: 高

## 决策结果

### 选定方案
**方案**: 方案 A - 使用 REST API

### 选择理由
1. 团队熟悉 REST API，学习成本低
2. 项目需求不需要 GraphQL 的灵活性
3. REST API 性能满足项目需求
4. 易于维护和扩展
```

#### Incorrect 示例
```markdown
## 决策

我们决定使用 REST API。
```

**问题**: 只分析一种方案，缺少方案对比、选择理由、冲突检查等关键内容。

## 相关文档 (Related Documents)

- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-2-方案决策-architecture-decision)
- [需求定义技能](./0004-define-requirements.md)
- [提示词资产化技能](./0006-prompt-engineering.md)
- [ADR 模板](../prompts/03-创建工作流提示词.md#41-adr-模板-架构决策)