用途
create-adr 技能用于创建架构决策记录（Architecture Decision Records，ADR），记录重要技术决策、其背景、所考虑的备选方案以及后果。其目的是为未来的开发者提供决策上下文，并保留关于为何做出某项技术选择的机构知识。
何时使用
在以下情况触发该技能：
- 做出重大架构决策
- 在竞争性技术或方案之间进行选择
- 设计新的系统组件或 API
- 改变系统结构的重构
- 在实现涉及设计权衡的功能之后
何时跳过
在以下情况跳过创建 ADR：
- 仅修复小缺陷或重构
- 仅文档或测试变更
- 没有架构影响的配置调整
- 实现方式显而易见的琐碎变更
工作流程
1. 收集上下文
审查实现以理解：
- 做出了哪些技术决策
- 为何选择此方案
- 存在哪些备选方案
- 接受了哪些权衡
如果审查现有代码：
git diff main...HEAD git log --oneline main..HEAD
2. 进一步调查
如果 diff 未提供足够上下文：
- 阅读引用的文件/函数
- 检查配置文件
- 审查相关测试
- 查看新增的依赖
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 中的模板来组织文档。
需要完成的关键章节：
- Status（状态）：Proposed、Accepted、Deprecated 或 Superseded
- Context（背景）：驱动该决策的问题或机会
- Decision（决策）：决定了什么以及技术方案
- Consequences（后果）：正面、负面和风险
- Alternatives（备选方案）：还考虑过什么以及为何未被选择
质量指南
好的 ADR 应具备：
- 具体的技术细节（而非模糊描述）
- 在有用处提供具体示例和代码片段
- 对权衡的诚实评估
- 指向相关资源或先前工作的链接
应避免：
- 模糊的理由（“它更好”）
- 缺少备选方案章节
- 没有对后果的讨论
- 过多的实现细节（那属于代码注释）
示例
用户：“记录使用 Redis 进行缓存的决定”
技能激活：
- 审查缓存实现
- 识别所考虑的备选方案（Memcached、内存缓存等）
- 记录权衡（复杂度与性能）
- 创建 docs/adr/0005-redis-for-application-cache.md
集成
与以下工作配合良好：
- 重大功能实现
- 系统重构工作
- 技术迁移
- API 设计决策