# 架构决策记录 (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