名称: adr-architecture 描述: 当需要记录具有上下文、理由和后果的重要技术或架构决策时使用。在技术选项选择、基础设施决策、标准建立、系统迁移或团队需要了解决策原因时调用。当用户提及ADR、架构决策、技术决策记录或决策文档时使用。

架构决策记录（ADR）

目的

记录重要的架构和技术决策，包括完整上下文、考虑的替代方案、分析的权衡和理解后的后果。ADR创建决策轨迹，帮助团队理解决策的“原因”，即使是多年后。

何时使用此技能

记录架构决策（微服务、数据库、框架）
文档化基础设施选择（云提供商、部署策略）
捕获技术选择（库、工具、平台）
记录过程决策（分支策略、部署流程）
建立技术标准或约定
迁移或淘汰系统
做出安全或合规性选择
通过文档化理由解决技术辩论
为新团队成员提供决策历史

触发短语: “ADR”、“架构决策”、“记录此决策”、“为什么我们选择”、“决策记录”、“技术决策日志”

什么是ADR？

架构决策记录是一份文档，捕获一个重要的决策。它包括：

上下文：什么情况需要此决策？
决策：我们选择做什么？
替代方案：我们考虑了哪些其他选项？
后果：有哪些权衡和影响？
状态：提议、已接受、已弃用、已取代？

快速示例：

# ADR-042: 使用PostgreSQL作为主数据库

**状态：** 已接受
**日期：** 2024-01-15
**决策者：** 后端团队、CTO

## 上下文
需要为新微服务平台选择主数据库。
要求：ACID事务、复杂查询、启动时10k+ QPS。

## 决策
使用PostgreSQL 15+作为主要关系型数据库。

## 考虑的替代方案
- MySQL：JSON支持较弱，约束处理不够稳健
- MongoDB：文档间无ACID，最终一致性问题
- CockroachDB：优秀但增加了我们目前无法支持的操作复杂性

## 后果
✓ 强一致性和数据完整性
✓ 优秀的JSON支持用于半结构化数据
✓ 团队有深厚的PostgreSQL经验
✗ 垂直扩展限制（在50k+ QPS时需要读副本）
✗ 如果需要分片，比DynamoDB更复杂

工作流程

复制此清单并跟踪进度：

ADR进度：
- [ ] 步骤1：了解决策
- [ ] 步骤2：选择ADR模板
- [ ] 步骤3：记录决策
- [ ] 步骤4：验证质量
- [ ] 步骤5：交付和归档

步骤1：了解决策

收集决策上下文：需要做什么决策、为什么现在做、谁决策、约束（预算、时间线、技能、合规）、要求（功能、非功能、业务）和范围（一个服务与组织范围）。这确保ADR解决正确的问题。

步骤2：选择ADR模板

对于技术选择（框架、库、数据库）→ 使用resources/template.md。对于具有多个相互依赖选择的复杂架构决策 → 学习resources/methodology.md。查看示例 → 审查resources/examples/（database-selection.md、microservices-migration.md、api-versioning.md）。

步骤3：记录决策

创建adr-{number}-{short-title}.md，包括：清晰标题、元数据（状态、日期、决策者）、上下文（情况和要求）、决策（具体且可操作）、考虑的替代方案（优缺点）、后果（权衡、风险、好处）、相关实现笔记（如有）、相关ADR链接。见常见模式获取决策类型特定指导。

步骤4：验证质量

使用resources/evaluators/rubric_adr_architecture.json自检。验证：上下文解释WHY、决策具体且可操作、2-3+替代方案有记录和权衡、后果包括好处和缺点、技术细节准确、对不熟悉读者可理解、诚实地描述缺点。最低标准：得分 ≥ 3.5（如果争议大/影响高，目标4.5+）。

步骤5：交付和归档

呈现完成的ADR文件，突出识别的关键权衡，建议ADR编号（如果未提供），推荐高风险决策的审查过程，并记录任何后续决策需求。归档约定：将ADR存储在docs/adr/或architecture/decisions/目录中，按顺序编号。

常见模式

对于技术选择：

关注技术能力与要求
包括性能基准（如果可用）
记录团队专业水平
考虑操作复杂性

对于架构更改：

在后果中包括迁移策略
记录向后兼容性影响
考虑过渡期间的团队速度影响
注意监控和回滚计划

对于标准和约定：

包括标准在实践中示例
记录例外或逃生舱口
考虑执行机制
注意教育/入职影响

对于弃用：

设置状态为“已弃用”或“已取代”
链接到取代的ADR
记录淘汰时间线
包括迁移指南

护栏

做：

诚实地描述权衡（每个选择都有缺点）
为缺乏当前上下文的未来读者写作
包括具体技术细节（版本、配置）
承认不确定性和风险
保持ADR不变（状态更改，但内容不变）
每个决策写一个ADR（范围集中）

不做：

让决策听起来比实际上更好
省略认真考虑的替代方案
使用术语而不解释
写模糊的后果（“可能提高性能”）
重新访问/编辑旧ADR（改为写新的取代ADR）
在一个ADR中组合多个独立决策

快速参考

标准模板：resources/template.md
复杂决策：resources/methodology.md
示例：resources/examples/database-selection.md、resources/examples/microservices-migration.md、resources/examples/api-versioning.md
质量评分标准：resources/evaluators/rubric_adr_architecture.json

ADR命名约定：adr-{number}-{short-kebab-case-title}.md

示例：adr-042-use-postgresql-for-primary-database.md