# 架构与产品决策记录（ADR）

> 记录本仓库重要决策及理由。一个 ADR = 一个不可逆的技术/产品选择。
>
> **ADR 是「为什么」不是「是什么」** — PRD 写功能，ADR 写取舍。
> **废弃的 ADR 不删除**，标记 `已废弃 · 由 ADR-XXX 取代`。

---

## ADR 哲学

| 原则 | 说明 |
|------|------|
| 决策写下来才算做了 | 只讨论不记录 = 没决策 |
| 错误决策比无决策好 | 错误的 ADR 标记「已废弃」并说明替代，不删除 |
| 一个 ADR 一件事 | 不要在一个 ADR 里捆多个无关决策 |

---

## 需要写 ADR 的信号

满足**任一**条件即触发 ADR：

| 信号 | 示例 |
|------|------|
| 技术栈选型分叉 | Rust vs Go、PostgreSQL vs MySQL |
| 架构模式变更 | 单体 → 微服务、SSR → CSR |
| 产品行为多解 | 删除策略、权限模型、定价模式 |
| 平台/工具切换 | 迁移技术栈、更换部署方式 |
| 范围边界裁定 | 做 vs 不做、本阶段 vs 下阶段 |
| 踩坑后的纠正 | 踩坑条目对应的架构修正 |

---

## ADR 标准格式

```
## ADR-NNN：{一句话决策标题}

| 项 | 内容 |
| -- | ---- |
| **状态** | 提议中 / 已接受 / 已废弃 |
| **日期** | YYYY-MM-DD |
| **背景** | 为什么需要做这个决策？上下文是什么？ |
| **决策** | 选择了什么方案？ |
| **替代方案** | 考虑过但没选的方案及原因 |
| **后果** | 正向：带来的好处；负向：引入的约束和代价 |
```

---

## 示例 ADR

### ADR-001：技术栈选型

| 项 | 内容 |
| -- | ---- |
| **状态** | 已接受 |
| **日期** | 2026-01-15 |
| **背景** | 新项目启动，需选择前后端技术栈 |
| **决策** | 前端 React + TypeScript，后端 Go + PostgreSQL；前后端分离，REST API 通信 |
| **替代方案** | A) Next.js 全栈（拒绝：SEO 需求不强，不需 SSR 复杂度）；B) Python Django（拒绝：本项目 Go 经验更多，性能要求高） |
| **后果** | 正向：高性能、栈熟悉、静态类型安全；负向：需额外维护 API 文档、前后端协约版本管理 |

### ADR-002：AI 协作文档体系

| 项 | 内容 |
| -- | ---- |
| **状态** | 已接受 |
| **日期** | 2026-01-15 |
| **背景** | 采用 Vibe Coding，需要让 AI 助手理解项目全貌，跨会话保持一致 |
| **决策** | 引入 6 份协作文档（AGENTS、QUICKREF、PITFALLS、DECISIONS、DEVELOPMENT-STANDARDS、GOVERNANCE），每次会话前后更新 STATUS |
| **替代方案** | A) 仅用 `.cursorrules`（拒绝：工具绑定，跨 IDE 不可用）；B) 全写在一个 README（拒绝：太长，AI 难以按需加载） |
| **后果** | 正向：工具无关、按需加载、自动化规则生成；负向：初期需花时间建立文档、需坚持更新 |

---

## 你的项目决策

> 以下为项目首个 ADR，建议在初始化时填写。后续决策按时间顺序追加。

### ADR-001：技术栈选型

| 项 | 内容 |
| -- | ---- |
| **状态** | 提议中 |
| **日期** | {{today}} |
| **背景** | {{project_name}} 启动，需确定技术栈 |
| **决策** | {{tech_decision}} |
| **替代方案** | {{alternatives}} |
| **后果** | {{consequences}} |

### ADR-002：AI 协作文档体系

| 项 | 内容 |
| -- | ---- |
| **状态** | 已接受 |
| **日期** | {{today}} |
| **背景** | 采用 Vibe Coding，需要让 AI 助手理解项目全貌 |
| **决策** | 引入 6 份协作文档（AGENTS、QUICKREF、PITFALLS、DECISIONS、DEVELOPMENT-STANDARDS、GOVERNANCE） |
| **替代方案** | 无文档（拒绝：AI 每次重头猜，效率极低） |
| **后果** | 正向：AI 协作效率大幅提升、跨工具通用；负向：需坚持更新文档 |