⚡

架构决策记录Skill architecture-decision-record

架构决策记录（ADR）技能提供标准化的模板和最佳实践，帮助开发团队系统化地记录和追踪重要的技术架构决策。包含背景分析、决策依据、后果评估和备选方案比较，适用于微服务设计、数据库选型、API版本策略等场景。关键词：架构决策记录 ADR模板 技术文档 微服务设计 数据库选型 API设计 系统架构 决策管理 团队协作 技术债务管理

架构设计 0 次安装 0 次浏览 更新于 3/2/2026

name: architecture-decision-record description: 使用此技能来记录重要的架构决策。提供遵循Nygard格式的ADR模板，包含背景、决策、后果和备选方案等部分。帮助团队维护后端系统、API设计、数据库选择和基础设施决策的架构记忆和决策依据。 version: 1.0.0 author: AI Agent Hub tags: [架构, 文档, 决策制定, 后端]

架构决策记录

概述

架构决策记录（ADRs）是轻量级文档，用于记录重要的架构决策及其背景和后果。本技能提供创建和维护项目中ADRs的模板、示例和最佳实践。

何时使用此技能：

  • 做出重要的技术选择（数据库、框架、云提供商）
  • 设计系统架构或主要组件
  • 为团队建立模式或约定
  • 评估多种方法之间的权衡
  • 记录将影响未来开发的决策

ADRs的重要性

ADRs作为团队的架构记忆：

  • 背景保存：记录决策的原因，而不仅仅是决策内容
  • 新人入职：帮助新团队成员理解架构原理 n- 避免重复讨论：避免对已确定决策的无休止争论
  • 跟踪演进：查看架构如何随时间演变
  • 责任明确：清晰的负责人和决策时间线

ADR格式（Nygard模板）

每个ADR应遵循以下结构：

1. 标题

格式：ADR-####: [决策标题] 示例：ADR-0001: 采用微服务架构

2. 状态

决策的当前状态：

  • 提议中：正在考虑中
  • 已接受：决策已批准并正在实施
  • 已取代：被后续决策取代（引用ADR编号）
  • 已弃用：不再推荐但尚未被取代
  • 已拒绝：已考虑但未采用（记录原因）

3. 背景

包含内容：

  • 问题陈述或机会
  • 业务/技术约束
  • 利益相关者要求
  • 系统当前状态
  • 影响因素（相互冲突的关注点）

示例：

## 背景

我们的单体应用程序正面临可扩展性问题：
- 高峰流量期间数据库连接池耗尽
- 任何功能的部署都需要完整的应用程序重启
- 团队因共享资源而受阻
- 45分钟的构建时间影响开发人员生产力

业务要求：
- 支持未来12个月内10倍的流量增长
- 实现独立团队部署
- 缩短新功能上市时间

技术约束：
- 团队熟悉Node.js和Python
- AWS基础设施已就位
- 2名高级DevOps工程师的预算

4. 决策

包含内容：

  • 正在做出的选择
  • 遵循的关键原则或模式
  • 因此会发生的变化
  • 实施负责人

具体且可操作：

  • ✅ “我们将使用Node.js和Express采用微服务架构”
  • ❌ “我们将考虑使用微服务”

示例：

## 决策

我们将从单体架构迁移到微服务，使用：

**技术栈：**
- Node.js 20+ 和 Express 用于服务实现
- PostgreSQL 用于事务数据（每个服务）
- Redis 用于缓存和会话管理
- RabbitMQ 用于服务间的异步通信
- Docker + Kubernetes 用于部署编排

**服务边界：**
- 用户服务：认证、个人资料、偏好设置
- 订单服务：订单处理、支付集成
- 库存服务：产品目录、库存管理
- 通知服务：电子邮件、短信、推送通知

**迁移策略：**
- 绞杀者模式：逐步从单体中提取服务
- 从通知服务开始（风险最低、边界清晰）
- 6个月内完成迁移（2026年Q1-Q2）

**责任：**
- 后端架构师：服务设计和API契约
- DevOps团队：Kubernetes设置和部署流水线
- 团队负责人：按服务执行迁移

5. 后果

包含内容：

  • 积极结果（收益）
  • 消极结果（成本、风险、权衡）
  • 中性结果（发生变化但不明显更好/更差的事情）

诚实地说明权衡：

## 后果

### 积极方面
- **可扩展性**：每个服务可以根据负载独立扩展
- **开发速度**：团队可以在无需协调的情况下部署服务
- **技术自由**：服务可以根据需要使用不同的技术栈
- **故障隔离**：一个服务的故障不会导致整个系统崩溃
- **更快的构建时间**：服务在2-5分钟内构建，而不是45分钟

### 消极方面
- **运维复杂性**：管理4+个服务 vs 1个应用程序
- **网络延迟**：服务间调用每次跳转增加10-50毫秒
- **分布式调试**：跨服务跟踪请求更加困难
- **数据一致性**：最终一致性 vs 立即一致性
- **学习曲线**：团队需要学习Kubernetes、服务网格概念
- **初始速度减慢**：在获得收益之前需要2-3个月的基础设施设置

### 中性方面
- **测试策略**：从集成测试转向契约测试
- **监控**：需要分布式追踪（Jaeger） vs 简单日志
- **成本**：更高的基础设施成本被提高的开发人员生产力所抵消

6. 考虑的备选方案

至少记录2个备选方案：

对每个备选方案，解释：

  • 是什么
  • 为什么考虑它
  • 为什么没有选择它

示例：

## 考虑的备选方案

### 备选方案1：优化现有单体
**描述：**
- 为数据库添加只读副本
- 实现缓存层（Redis）
- 使用负载均衡器进行水平扩展

**优点：**
- 复杂性较低，团队已经熟悉
- 实施更快（4-6周）
- 无需架构重构

**缺点：**
- 无法解决部署耦合问题
- 可扩展性上限有限
- 构建时间仍然缓慢
- 团队仍然受共享资源阻碍

**为何未选择：**
这解决了症状但不是根本原因。随着我们继续增长，在12-18个月内我们将再次面临同样的问题。

### 备选方案2：无服务器架构（AWS Lambda）
**描述：**
- 将应用程序分解为Lambda函数
- 使用API Gateway进行路由
- DynamoDB用于存储

**优点：**
- 极高的可扩展性
- 按使用付费的定价模式
- 无需服务器管理

**缺点：**
- 供应商锁定于AWS
- 冷启动延迟（500毫秒+）
- 限制为15分钟执行时间
- 团队无服务器经验
- 本地调试和测试更加困难

**为何未选择：**
鉴于团队缺乏经验，风险太高。冷启动对我们的实时功能不可接受。微服务提供了类似的好处，但控制更多。

7. 参考（可选）

相关资源的链接：

  • 会议记录或讨论线程
  • 相关ADRs
  • 外部研究或文章
  • 概念验证实现

ADR生命周期

提议 → 已接受 → [已实施] → （最终）已取代/已弃用
          ↓
      已拒绝

状态转换：

  1. 提议中：草稿创建，正在审查
  2. 已接受：团队同意，可以开始实施
  3. 已实施：决策在生产环境中生效
  4. 已取代：被新ADR取代（添加引用）
  5. 已弃用：不再推荐（记录迁移路径）
  6. 已拒绝：未采用（记录推理）

最佳实践

1. 保持ADRs不可变

一旦接受，不要编辑ADRs。创建新的ADRs来取代旧的。

  • ✅ 创建取代ADR-0003的ADR-0015
  • ❌ 用新决策更新ADR-0003

2. 使用现在时态编写

ADRs是历史记录，写作时仿佛决策正在做出。

  • ✅ “我们将采用微服务”
  • ❌ “我们采用了微服务”

3. 关注’为什么’，而不是’如何’

ADRs记录决策，而不是实施细节。

  • ✅ “我们选择PostgreSQL是为了关系一致性”
  • ❌ “使用这些特定设置配置PostgreSQL…”

4. 作为团队审查ADRs

在接受之前获得相关利益相关者的意见。

  • 架构师：技术可行性
  • 开发人员：实施可行性
  • 产品：业务一致性
  • DevOps：运维关注点

5. 顺序编号

使用4位零填充数字：ADR-0001、ADR-0002等。 即使有多个项目，也保持单一序列。

6. 存储在Git中

将ADRs与代码一起存储在版本控制中：

  • 位置：/docs/adr/ 或 /architecture/decisions/
  • 格式：Markdown便于阅读
  • 分支：与实施相同的分支

快速入门清单

  • [ ] 从/templates/adr-template.md复制ADR模板
  • [ ] 分配下一个顺序编号（检查现有ADRs）
  • [ ] 填写背景：问题、约束、要求
  • [ ] 记录决策：什么、为什么、如何、谁
  • [ ] 列出后果：积极、消极、中性
  • [ ] 描述至少2个备选方案：什么、优点/缺点、为何未选择
  • [ ] 添加参考：讨论、研究、相关ADRs
  • [ ] 将状态设置为"提议中"
  • [ ] 与团队审查
  • [ ] 批准后将状态更新为"已接受"
  • [ ] 在实施PR中链接ADR
  • [ ] 部署后将状态更新为"已实施"

要避免的常见陷阱

❌ 过于技术化：“我们将使用Kubernetes和这50个YAML配置…” ✅ 适当层级：“我们将使用Kubernetes进行容器编排，因为…”

❌ 过于模糊：“我们将使用更好的数据库” ✅ 具体：“我们将使用PostgreSQL 15+处理事务数据，因为…”

❌ 无备选方案：只记录选择的解决方案 ✅ 比较性：记录为何未选择备选方案

❌ 缺少后果：只列出好处 ✅ 平衡：诚实地说明成本和权衡

❌ 无背景：“我们决定使用Redis” ✅ 有背景：“考虑到我们有100万+并发用户和低于50毫秒的延迟要求…”

示例

查看/examples/获取完整的ADR示例：

  • adr-0001-adopt-microservices.md - 系统架构决策
  • adr-0002-choose-postgresql.md - 数据库选择
  • adr-0003-api-versioning-strategy.md - API设计模式

相关技能

  • api-design-framework：当ADR涉及API设计时使用
  • database-schema-designer：当ADR涉及数据库选择时使用
  • security-checklist：当ADR有安全影响时咨询

与智能体的集成

后端系统架构师

  • 在设计主要系统组件时创建ADRs
  • 在做出相关架构决策时引用ADRs
  • 审查ADRs以确保与整体架构的一致性

工作室教练

  • 为复杂的多智能体项目建议ADRs
  • 确保架构决策被记录
  • 在项目规划中跟踪ADR状态

代码质量审查员

  • 验证重大更改是否有相应的ADRs
  • 确保实施与接受的ADRs一致
  • 标记可能需要被取代的ADRs

技能版本：1.0.0 最后更新：2025-10-31 维护者：AI Agent Hub团队