kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/skill/0005-architecture-decision.md

8.2 KiB
Raw Blame History

name description
0005-architecture-decision 方案决策，基于 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: 分析技术方案

## 技术方案分析

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

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

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

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

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

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

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

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

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

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

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

步骤 2: 选择最优方案

## 决策结果

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

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

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

步骤 3: 检查冲突

## 冲突检查

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

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

步骤 4: 创建 ADR 文档

---
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

### 🎯 架构决策 (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 示例

## 技术方案分析

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

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

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

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

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

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

## 决策结果

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

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

Incorrect 示例

## 决策

我们决定使用 REST API。

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

相关文档 (Related Documents)