2. 核心概念：决策记录（ADR）的定义、结构与在项目组合中的角色
2.1 什么是架构决策记录（ADR）
架构决策记录（Architecture Decision Record，ADR）是一种轻量级的文档化实践，用于捕获在软件架构或项目管理过程中做出的重要决策及其上下文。在项目组合管控场景中，ADR 不仅是技术选型的备忘录，更是跨项目沟通、风险追溯与组合级对齐的核心资产。
核心定义：ADR 是一个自包含的、有时间戳的、不可变（仅追加）的决策快照，记录“在什么背景下，考虑了哪些选项，最终选择了哪个方案，以及该决策带来的后果”。
2.2 ADR 的标准结构（Y-Statemement 变体）
本课程采用经过组合管理适配的 7 字段结构，每个 ADR 文件对应一个独立的决策点：
| 字段 | 名称 | 说明 | 示例 |
|---|---|---|---|
| 1 | 标题 | 格式：ADR-{序号}：{决策主题} | ADR-012：采用微前端拆分订单模块 |
| 2 | 状态 | 提议 / 已接受 / 已废弃 / 已取代 | 已接受 |
| 3 | 上下文 | 触发决策的问题、约束、业务驱动因素 | 订单模块月均变更 40 次，单体部署阻塞发布 |
| 4 | 决策 | 明确的选择陈述，使用“我们决定……”句式 | 我们决定将订单模块拆为 3 个独立微前端子应用 |
| 5 | 备选方案 | 至少列出 2 个被否决的方案及否决理由 | 方案A：模块内聚重构（否决：仍共享部署单元） |
| 6 | 后果 | 正面 + 负面影响的显式描述 | 正面：独立部署；负面：增加 3 个仓库维护成本 |
| 7 | 关联 | 关联的 ADR、项目 ID、风险编号 | 关联 ADR-008，关联项目 P-ORD-2024 |
组合管理适配提示：在项目组合视图中，关联字段是连接 ADR 与项目、风险、里程碑的关键纽带。建议使用统一编码体系（如 P-{项目缩写}-{序号}）实现跨视图追溯。
2.3 ADR 在项目组合中的角色
在单项目层面，ADR 解决“为什么这样做”；在项目组合层面，ADR 解决“这些决策之间如何相互影响”。具体角色体现在以下四个维度：
- 决策透明度：组合经理无需参加每个技术评审会，通过 ADR 即可掌握关键决策的上下文与影响范围。
- 冲突检测：当两个项目的 ADR 在技术栈、数据模型或资源依赖上产生矛盾时，组合视图可提前预警。
- 变更影响分析：当某个 ADR 被废弃或取代，组合视图能快速定位受影响的全部项目与里程碑。
- 治理合规：审计或合规检查时，ADR 序列构成完整的决策时间线，证明组合级管控过程可追溯。
2.4 ADR 生命周期与组合视图的映射
每个 ADR 经历从“提议”到“已接受”或“已废弃”的生命周期。在项目组合管控中，不同状态的 ADR 对应不同的视图行为：
| ADR 状态 | 组合视图行为 | 数据可见性 |
|---|---|---|
| 提议 | 标记为“待评审”，在组合看板中高亮 | 仅项目团队 + 组合经理可见 |
| 已接受 | 纳入组合基线，参与依赖计算 | 全组合视图可见 |
| 已废弃 | 保留历史记录，从活跃依赖图中移除 | 可归档，但不可删除 |
| 已取代 | 生成“取代链”，指向新的 ADR | 取代链在组合关系图中可视化 |
2.5 ADR 在组合数据结构中的位置
下图展示了 ADR 作为核心节点，如何连接项目、风险、里程碑与资源，形成组合管控的多视图数据模型：
2.6 组合级 ADR 的典型应用场景
- 跨项目技术栈统一：当项目 A 的 ADR 选择 PostgreSQL，项目 B 的 ADR 选择 MySQL 时，组合视图标记为“技术栈分歧”，触发架构评审。
- 共享组件决策：项目 C 的 ADR 决定自建日志组件，而组合级已有统一日志方案，ADR 的“关联”字段可自动链接到组合级标准，提示复用。
- 里程碑依赖：ADR-015（数据库迁移）被标记为“已接受”后，自动更新组合里程碑视图中的“数据库迁移完成”节点状态。
常见误区：ADR 不是需求文档，也不是设计说明书。它只记录决策本身及其直接理由，不应包含实现细节、代码示例或长篇讨论。每个 ADR 应控制在 200-500 字以内，保持“一个文件一个决策”的原子性。
2.7 小结：ADR 作为组合管控的数据锚点
在项目组合管控的多项目视图数据结构中，ADR 承担了“决策锚点”的角色。它既向下连接具体项目的技术实现，又向上对齐组合级的战略目标与资源约束。通过标准化的 7 字段结构、生命周期状态机以及跨实体的关联字段，ADR 使得组合经理能够在不陷入技术细节的前提下，精准掌握决策脉络与潜在冲突，从而做出更及时、更可靠的组合级调整。