D5 · Template · ADR
ADR 架构决策记录模板
Xisound Architecture Decision Record Template v1.0
1
标准模板
6
必填章节
4
状态流转
ADR 架构决策记录模板 v1.0
摘要
本文档是 Xisound Architecture Decision Record（ADR） 的标准模板。 ADR 用于记录架构层面的重大决策：为什么这么设计、考虑过哪些备选方案、最终选择的理由、可能的风险。 本模板配合《文档-代码同步规范 v1.0》§3.5 使用：当代码实现偏离 D3 架构文档时必须开 ADR。
1. 使用说明
1.1 什么时候写 ADR？
根据《文档-代码同步规范》§3.5 与 §9，下列情形必须写 ADR：
| 触发场景 | 示例 |
|---|---|
| 代码偏离 D3 架构设计 | D3 规定用 gRPC，实际代码用了 WebSocket |
| 技术栈选型（首次） | 从 C++ 切到 Rust · 从 React 切到 Vue |
| 协议 / 数据模型重大变更 | WebSocket 协议 v1 → v2 · 数据库 schema 大改 |
| 依赖升级有破坏性影响 | .NET 6 → .NET 8 · Astro 4 → 6 |
| 废弃某功能或模块 | 移除 XiForge 旧版 UIEditor |
| 安全 / 合规决策 | 改用哪家 CDN · 加密算法升级 |
| 性能 / 成本权衡 | SQLite → PostgreSQL · 为省钱放弃某 SaaS |
不需要 ADR 的情况： - Bug 修复 - 小功能增量 - 测试补充 - 纯 refactor（不改接口） - 文档 only 修改
1.2 ADR 命名规范
- 文件名：
adr-<序号>-<kebab-case-标题>.md - 序号：全局递增 4 位数字（
0001/0002/ ... ） - 示例：
adr-0001-choose-astrojs-node-adapter.md - 存放位置：各中心 / 项目自管（建议
<center>/adr/子目录），索引登记到本模板链接的中央 ADR 表
1.3 ADR 生命周期状态
| 状态 | 含义 | 谁可流转 |
|---|---|---|
proposed |
草案 · 提议阶段 | ADR 作者 |
accepted |
已接受 · 进入实施 | Tech Lead / Architect 评审通过 |
superseded by ADR-XXXX |
已被后续 ADR 取代 | 新 ADR 作者（必须双向链接） |
deprecated |
废弃 · 不再有效 | Tech Lead / Architect |
2. ADR 模板正文（复制下方 frontmatter + 内容开始填写）
将下面 「───── 复制分割线 ─────」 之间的内容复制到新文件开始填写：
───── 复制分割线（开始） ─────
---
title: ADR-XXXX · <简短决策标题>
description: <一句话概述决策内容>
level: l2
layer: L5
category: adr
doc_id: D5-ADR-XXXX
version: v1.0
status: proposed
author: <作者姓名> · <中心名>
date: YYYY-MM-DD
---
# ADR-XXXX · <简短决策标题>
> **状态**：🟡 proposed | 🟢 accepted | 📦 superseded by ADR-YYYY | ⚫ deprecated
> **决策日期**：YYYY-MM-DD
> **决策人**：<Tech Lead / Architect 姓名>
> **相关**：`<相关 PR 链接>` · `<相关 issue 链接>` · `<相关 D3 架构文档链接>`
## 1. 背景（Context）
<!--
- 描述问题产生的背景
- 为什么现在需要做这个决策？
- 不做这个决策会有什么后果？
- 2-4 段文字 · 不要太长
-->
## 2. 考虑的备选方案（Options）
### 2.1 方案 A · <方案名称>
**做法**：<简述>
**优点**：
- ...
- ...
**缺点**：
- ...
- ...
**成本估算**：<时间 / 金钱 / 复杂度>
### 2.2 方案 B · <方案名称>
（同上格式）
### 2.3 方案 C · <方案名称>（可选）
（同上格式）
## 3. 决策（Decision）
!!! success "最终选择：方案 X · <方案名称>"
**理由**：
1. ...
2. ...
3. ...
## 4. 影响与后果（Consequences）
### 4.1 正面影响
- ...
- ...
### 4.2 负面影响 / 风险
- ...
- **缓解措施**：...
### 4.3 需要同步更新的其他文档
| 文档 | 修改类型 | Owner |
|:-----|:---------|:------|
| D3-architecture/xxx | 更新 §X 章节 | 架构组 |
| D4-implementation/xxx | 新增文档 | 代码 owner |
| D2-products/Pxx-xxx/api.md | 版本号升级 | 产品经理 |
### 4.4 代码落地范围（Code-First 对齐 · O3=Y 拍板）
- **主要涉及代码路径**：`04_development/backend_csharp/...`
- **预计 PR 数量**：N 个
- **里程碑**：完成时间 YYYY-MM-DD
- **CI 同步检查**：需要 / 不需要
## 5. 验证计划（Validation）
<!--
决策实施后如何验证？有哪些可衡量的指标？
-->
| 验证项 | 方法 | 通过标准 |
|:-------|:-----|:---------|
| 功能 | 单元测试 / 集成测试 | 全部通过 |
| 性能 | benchmark 对比 | 不低于 baseline |
| 稳定性 | 生产环境观察 2 周 | 无 P0/P1 事故 |
## 6. 参考资料（References）
- <外部技术文章 / 标准 / 竞品研究>
- <内部 D0-D6 相关文档>
- <会议纪要>
---
## 版本历史
| 版本 | 日期 | 状态变更 | 变更人 |
|:----:|:----:|:---------|:-------|
| v1.0 | YYYY-MM-DD | 首次提议（proposed） | <作者> |
| v1.1 | YYYY-MM-DD | 决策通过（accepted） | <评审人> |
*ADR-XXXX · v1.0 · YYYY-MM-DD · © Xisound Inc.*
───── 复制分割线（结束） ─────
3. 填写指南
3.1 §1 背景（Context）写作要点
- ✅ 写：问题是什么 · 为什么需要决策 · 不做会怎样
- ❌ 不要写：已有方案介绍（那是 §2）· 结论（那是 §3）
- 📏 长度：200-500 字
3.2 §2 备选方案（Options）写作要点
- 至少列 2 个方案（只有 1 个就不用 ADR）
- 每个方案都必须有优缺点对比
- 成本估算要具体（人天 / 金额 / 风险等级）
- 如果有方案明显不可行，也要说明为什么 rule out
3.3 §3 决策（Decision）写作要点
- 一句话表达最终选择
- 理由列 3-5 条（太少说明没深思 · 太多说明没主次）
- 如果是有争议决策，附 Tech Lead 姓名 + 评审会时间
3.4 §4 后果（Consequences）写作要点
- 正负面都要写（只写正面说明没想清楚风险）
- 缓解措施要具体
- 文档联动表对齐《文档-代码同步规范》§3.6 映射规则
4. 典型 ADR 示例（供参考）
4.1 工程类 ADR 典型命题
| ADR 编号 | 可能的标题 | 适用场景 |
|---|---|---|
| ADR-0001 | Choose Astro Node Adapter Standalone Mode | 07_web M6.1 技术选型 |
| ADR-0002 | Adopt SQLite before PostgreSQL in M6.1 | 渐进式升级策略 |
| ADR-0003 | Split xisound-api into Independent Repo | 前后端仓库分离 |
| ADR-0004 | Migrate from @astrojs/node Hybrid to CF Pages Static | M6.1 路线变更 |
| ADR-0005 | Adopt Wework Webhook over Feishu for M6.1 | 企微 vs 飞书选型 |
4.2 架构类 ADR 典型命题
| ADR 编号 | 可能的标题 |
|---|---|
| ADR-0010 | DSPAlgo v6 to v7 Module Registry Refactor |
| ADR-0011 | Adopt WebSocket over gRPC for Frontend-Backend Communication |
| ADR-0012 | Use Pinia v3 over Vuex for State Management |
5. ADR 与其他文档的关系
flowchart LR
ADR[ADR 决策记录<br/>D5 模板] --> D3[D3 架构级<br/>更新相关章节]
ADR --> D4[D4 实现级<br/>代码按 ADR 实施]
ADR --> D2[D2 产品级<br/>api.md 版本号升级]
ADR --> D6[D6 测试与运维<br/>新增测试用例]
classDef xyL0 fill:#6B3FA0,stroke:#6B3FA0,color:#fff
classDef xyL3 fill:#DFA66D,stroke:#DFA66D,color:#fff
class ADR xyL0
class D3,D4,D2,D6 xyL36. FAQ
Q1：ADR 和 Tech Design Doc（TDD）有什么区别？
A： - ADR：单一决策 · 1-3 页 · 重"为什么选这个" · 持久化留存 - TDD：综合设计 · 10+ 页 · 重"怎么实现" · 可能随代码演进被替换
一个项目可能有多个 ADR，但只有 1 份最新 TDD。
Q2：旧决策过时了怎么办？
A：
1. 不要删除旧 ADR（保留历史视角）
2. 写新 ADR 明确说明：Supersedes ADR-XXXX
3. 旧 ADR 状态改为 superseded by ADR-YYYY
4. 双向链接
Q3：小决策也要 ADR 吗？
A：用这个判断树： - 决策影响 > 1 个团队？ 是 → 要 ADR - 决策会写进产品/架构文档？ 是 → 要 ADR - 决策 6 个月后还会被问起？ 是 → 要 ADR - 三个都否 → 写 PR description 就够
Q4：ADR 要不要 review？
A：要。proposed → accepted 必须经 Tech Lead / Architect 评审（异步评审 ≥ 3 天）。重大决策需要评审会（人数 ≥ 4）。
Q5：ADR 数量太多怎么管理？
A：
- 每个中心自己维护 <center>/adr/index.md（中央索引）
- 按季度 review · 合并重复 ADR
- 超过 100 个 ADR 时考虑按产品分类存放
7. 相关文档
- 文档-代码同步规范 v1.0（本模板的使用依据）
- 技术开发文档体系方案 v1.0
- D3 架构级总览
- D4 实现级总览
版本历史
| 版本 | 日期 | 变更 |
|---|---|---|
| v1.0 | 2026-05-06 | 首次发布 · 基于文档-代码同步规范 v1.0 §3.5 强制要求创建 |
ADR 架构决策记录模板 · v1.0 · 2026-05-06 · © Xisound Inc.
反馈
对本模板有意见？请提 PR 或联系 docs@xisound.com。