create-adr

创建 ADR 技能

**用途：**记录架构决策，为后续开发者提供背景信息，并维护关于技术选择原因的组织知识。

何时使用此技能

在以下情况下触发此技能：

• 做出重要的架构决策
• 在相互竞争的技术或方案之间进行选择
• 设计新的系统组件或 API
• 会改变系统结构的重构
• 实现涉及设计权衡的功能后

以下情况跳过创建 ADR

• 仅涉及小型 Bug 修复或重构
• 仅涉及文档或测试的更改
• 不影响架构的配置调整
• 实现方式显而易见的简单更改

工作流

1. 收集背景信息

检查实现，了解：

• 做出了哪些技术决策
• 为什么选择这种方案
• 有哪些替代方案
• 接受了哪些权衡

如果正在检查现有代码：

git diff main...HEAD
git log --oneline main..HEAD

2. 进一步调查

如果差异内容未提供足够背景信息：

• 阅读引用的文件/函数
• 检查配置文件
• 查看相关测试
• 检查新增的依赖项

3. 创建 ADR

位置：docs/adr/NNNN-descriptive-title.md

命名约定：

• 使用连续编号（0001、0002 等）
• 使用小写字母，以连字符分隔
• 描述清晰且简洁

示例：

• 0001-use-jwt-for-authentication.md
• 0002-adopt-event-sourcing-for-orders.md
• 0003-postgres-over-mysql.md

4. 使用模板

使用 assets/adr-template.md 中的模板来组织文档。

需完成的主要部分：

• 状态：提议、已接受、已弃用或已取代
• 背景：推动此次决策的问题或机会
• 决策：做出的决定及技术方案
• 后果：积极影响、消极影响及风险
• 替代方案：考虑过的其他方案，以及未选择它们的原因

质量指南

优秀的 ADR 应包含：

• 具体的技术细节（而非模糊的描述）
• 有帮助时提供具体示例和代码片段
• 如实评估权衡
• 链接到相关资源或先前实践

避免：

• 模糊的理由（“它更好”）
• 缺少替代方案部分
• 未讨论后果
• 过多的实现细节（这些内容应放在代码注释中）

示例

用户：“记录使用 Redis 进行缓存的决策”

技能触发后：

1. 检查缓存实现
2. 找出考虑过的替代方案（Memcached、内存缓存等）
3. 记录权衡（复杂度与性能）
4. 创建 docs/adr/0005-redis-for-application-cache.md

集成

适用于：

• 重大功能实现
• 系统重构工作
• 技术迁移
• API 设计决策