155 lines
3.5 KiB
Markdown
155 lines
3.5 KiB
Markdown
|
# 架构决策记录 (ADR)
|
|||
|
|
|
|||
|
|
## 什么是 ADR？
|
|||
|
|
|
|||
|
|
ADR（Architecture Decision Record）记录项目中重要的架构决策及其原因。当新成员（或 AI）加入时，可以通过 ADR 快速理解"为什么这么做"。
|
|||
|
|
|
|||
|
|
## 决策记录
|
|||
|
|
|
|||
|
|
### ADR-001: 采用"1 人 + 2AI"协作框架
|
|||
|
|
|
|||
|
|
**日期**: 2026-05-23
|
|||
|
|
**状态**: 已采纳
|
|||
|
|
**决策者**: 人类负责人
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
项目需要高效开发，但团队只有 1 人。利用 AI 辅助编程可以大幅提升效率。
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
采用 1 个负责人 + 2 个 AI（Dev AI 编码 + QA AI 测试）的协作模式。
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 开发效率大幅提升
|
|||
|
|
- ✅ 代码质量有保障（独立测试 AI）
|
|||
|
|
- ⚠️ 需要维护权限体系和协作流程
|
|||
|
|
- ⚠️ 人类需要审阅 AI 输出
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### ADR-002: 采用 R/W/RW/- 四态权限体系
|
|||
|
|
|
|||
|
|
**日期**: 2026-05-23
|
|||
|
|
**状态**: 已采纳
|
|||
|
|
**决策者**: 人类负责人
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
初始框架使用简单的 allowed/forbidden 二元权限，无法满足"只读"场景。
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
采用四态权限：`-`（无权）、`R`（只读）、`W`（可写）、`RW`（读写）。
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 更细粒度的权限控制
|
|||
|
|
- ✅ 明确只读路径（如 task.md、feedback/）
|
|||
|
|
- ⚠️ 权限矩阵更复杂，需要维护
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### ADR-003: 项目级文档放在根目录 docs/
|
|||
|
|
|
|||
|
|
**日期**: 2026-05-23
|
|||
|
|
**状态**: 已采纳
|
|||
|
|
**决策者**: 人类负责人
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
项目级文档（产品需求、架构设计等）不属于任何子项目，需要独立存放。
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
在根目录创建 `docs/` 目录，而非 `projects/P00_DOCS/`。
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 语义清晰，业界标准
|
|||
|
|
- ✅ 路径简短
|
|||
|
|
- ⚠️ 需要在权限矩阵中单独定义
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### ADR-004: 新增 tools/ 和 data/ 目录
|
|||
|
|
|
|||
|
|
**日期**: 2026-05-23
|
|||
|
|
**状态**: 已采纳
|
|||
|
|
**决策者**: 人类负责人
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
开发工具脚本和训练数据需要独立管理，不应混入项目代码。
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
在根目录创建 `tools/`（开发工具）和 `data/`（训练数据）。
|
|||
|
|
|
|||
|
|
**权限**:
|
|||
|
|
- `tools/`: Dev AI 可写，QA AI 禁止
|
|||
|
|
- `data/`: Dev AI 可写，QA AI 只读
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 职责分离，便于管理
|
|||
|
|
- ✅ 训练数据独立于代码
|
|||
|
|
- ⚠️ 需要维护数据版本
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### ADR-005: 工作流增加 retry 和 escalation 机制
|
|||
|
|
|
|||
|
|
**日期**: 2026-05-23
|
|||
|
|
**状态**: 已采纳
|
|||
|
|
**决策者**: 人类负责人
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
线性工作流无法处理测试失败的情况。
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
- 增加 retry 机制：最多 3 轮测试修复循环
|
|||
|
|
- 增加 escalation 机制：第 3 轮仍有 BLOCKER/HIGH 时升级给人类
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 自动处理常见 Bug 修复
|
|||
|
|
- ✅ 严重问题及时升级
|
|||
|
|
- ⚠️ 需要维护修复轮次计数
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### ADR-006: 创建 resume-context Skill 解决多电脑同步
|
|||
|
|
|
|||
|
|
**日期**: 2026-05-23
|
|||
|
|
**状态**: 已采纳
|
|||
|
|
**决策者**: 人类负责人
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
用户在家和单位两台电脑间切换，需要快速恢复开发上下文。
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
- 创建 `resume-context` Skill
|
|||
|
|
- 创建 `docs/PROJECT_CONTEXT.md` 项目上下文
|
|||
|
|
- 创建 `docs/06_开发日志/` 按日期记录讨论
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 换电脑后快速恢复上下文
|
|||
|
|
- ✅ 新 AI 对话可以读取背景
|
|||
|
|
- ⚠️ 需要维护文档更新
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 决策模板
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
### ADR-XXX: 决策标题
|
|||
|
|
|
|||
|
|
**日期**: YYYY-MM-DD
|
|||
|
|
**状态**: 考虑中 / 已采纳 / 已废弃
|
|||
|
|
**决策者**: XXX
|
|||
|
|
|
|||
|
|
**背景**:
|
|||
|
|
[为什么需要做这个决策]
|
|||
|
|
|
|||
|
|
**决策**:
|
|||
|
|
[具体决定是什么]
|
|||
|
|
|
|||
|
|
**后果**:
|
|||
|
|
- ✅ 好处
|
|||
|
|
- ⚠️ 需要注意的点
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**最后更新**: 2026-05-23
|
|||
|
|
**维护者**: 人类负责人 + Dev AI
|