# Wiki 文件参考

每个 wiki 文件的完整说明：为什么需要、写给谁看、核心内容、维护频率、长度建议。

---

## 00-product-proposal.md — 产品提案

**为什么需要：** Agent 没有产品直觉。你不告诉它边界在哪，它就会在你让它加个简单功能时顺手加上一堆你不需要的东西。产品提案是 Agent 的行为边界。"不做什么"这条比"做什么"更重要——它防止 Agent 越界发挥。

**写给谁看：** Agent + 未来的你

**核心内容：**
- 产品愿景（为什么做这个、长期方向）
- 产品定位（一句话说清楚做什么）
- 不做什么（明确的边界约束）
- 目标用户和核心场景
- 功能矩阵（功能 × 解决的问题 × 阶段）
- 路线图叙事（各阶段一句话目标 + 成功标志）

**维护频率：** 每个大阶段开始前检查一次，通常改动很小。

---

## 01-project-roadmap.md — 功能索引

**为什么需要：** Agent 需要一个"鸟瞰图"来理解项目全貌。product-proposal 的路线图是叙事性的（讲为什么），roadmap 是索引性的（查什么功能在哪、状态如何）。两者互补不重叠。改动频率高于 product-proposal，低于 stage 文件——这正是它独立存在的原因。

**写给谁看：** Agent + 你自己

**核心内容：**
- 阶段总览表（阶段 × 主题 × 状态 × 链接到 stage 文件）
- 全量功能索引（所有功能按阶段分组，每行标注状态）
- 关键里程碑

**维护频率：** 新功能定义时追加行，阶段完成时批量更新状态。

---

## 02-system-architecture.md — 系统架构

**为什么需要：** Agent 动手前先读这个。它回答"项目长什么样"，帮 Agent 建立全局心智模型。没有它，Agent 要读完所有源文件才能定位该改哪里。没有它的时候，Agent 经常在入口文件里堆代码；有了它之后，Agent 知道该改哪个模块。

**写给谁看：** Agent

**核心内容：**
- 技术栈概览、架构图
- 目录结构
- 数据流（请求链路、推送机制、定时任务等）
- 核心类型定义（跨功能的 domain types）
- 完整 API 路由表（方法、路径、响应类型）
- 文件约定、环境变量、构建命令

**长度建议：** 300-500 行。超出说明混入了功能特有细节，应拆到 stage 文件。

**维护频率：** 架构变更时更新（新增模块、数据流改变、新 API 路由）。Bug fix 不用更新。

---

## 03-design-principle.md — 设计原则

**为什么需要：** 视觉系统的内容容易膨胀——调色板、字体、间距、动效、组件模式加在一起轻松超过 100 行。嵌在架构文件里会让它超出 300-500 行的建议上限，且视觉决策的读者和维护节奏与架构决策不同。没有它时，Agent 每次新建组件都在"猜"项目的配色和间距，结果不同组件风格不一致。

**写给谁看：** Agent

**核心内容：**
- 设计哲学（一句话定义视觉方向，如"CRT 终端美学"或"极简留白"）
- 调色板（CSS 变量 / Design Token × 语义用途）
- 字体系统（字体族、字号阶梯、行高）
- 间距与布局系统（基准单位、栅格、响应式断点）
- 状态 → 颜色映射（success / warning / error / info）
- 动效规范（关键帧动画、过渡时长、缓动函数）
- 组件模式（卡片、面板、按钮的通用视觉约束）

**何时需要：** 项目有自定义视觉语言时。如果只用 shadcn/ui 默认主题，可以不写。

**维护频率：** 设计语言确立后稳定。调色板扩展、新增组件模式时更新。

---

## 04-api-reference.md — API 参考

**为什么需要：** system-architecture 的路由概览只有一行摘要，stage 文件的 API 契约会随归档消失。当项目 API 超过 5 条路由时，需要一个持久的、完整的 API 参考，让 Agent 查完整接口不用翻多个 stage 文件。

**与其他文件的分工：**
- `02-system-architecture.md`：路由概览表（方法 + 路径 + 一句话用途）
- `04-api-reference.md`：完整契约（请求参数、响应字段、示例、错误码）
- `1X-stage-X.md`：API 的设计决策和取舍（为什么这样设计）

**写给谁看：** Agent

**核心内容：**
- 路由概览表（快速索引）
- 每个 API 的：请求参数、请求体、响应字段、示例、错误码
- 按功能模块分组

**何时需要：** API 超过 5 条路由，或已有 stage 文件归档后仍需查 API 细节。

**维护频率：** 新增 / 修改 API 时同步更新。stage 交付后，将 stage 里的 API 契约搬运到此文件。

---

## 05-glossary.md — 术语表

**为什么需要：** Agent 没有领域知识，容易用错词或混用近义词。一张"术语 → 定义 → 不要混淆的词"表能统一 Agent 的输出用语——变量命名、注释、UI 文案都会更准确。

**写给谁看：** Agent

**核心内容：**
- 术语、定义、容易混淆的近义词，三列表格

**何时需要：** 项目有领域术语时（金融、医疗、游戏、特定业务等）。纯技术工具项目通常不需要。

**维护频率：** 发现 Agent 用错词时追加。

---

## 06-conventions.md — 编码约定

**为什么需要：** "用 dayjs 不用 moment""禁止 any""组件命名用 PascalCase"——这类约束不属于架构（结构性的），也不属于 pitfalls（事后踩坑的），而是事前的编码偏好。没有专门的归属地，容易散落在 CLAUDE.md 或 system-architecture 里，Agent 找不到就不遵守。

**写给谁看：** Agent

**核心内容：**
- 库选择（用什么 / 不用什么 / 原因）
- 命名规范（对象 × 规范 × 示例）
- 代码模式（错误处理、类型约束等）
- 禁止项

**何时需要：** 有明确的编码偏好或约束需要 Agent 遵循时。

**维护频率：** 新增约定时追加。频率低，稳定后很少改。

---

## 1X-stage-X.md — 阶段文件

**为什么需要：** 一个功能的设计决策（What）和它的 API 契约、数据模型（How）天然绑定在一起。把它们拆到不同文件会导致 Agent 要同时打开两个文件才能理解一个功能。

**反模式：** 不要把 roadmap（功能状态表）和 design-spec（设计规格）拆成两个文件维护。实践中必然出现：
- 两个文件记录同一个功能的状态，经常不一致
- Agent 要同时打开两个文件才能理解一个功能的全貌
- 功能交付后，design-spec 中的验收清单变成死代码

**写给谁看：** Agent

**核心内容：**
- 功能汇总表（功能 × 状态）
- 每个功能的：用户场景、设计决策与取舍
- 每个功能的：API 契约、数据模型、受影响文件
- 实现摘要（已完成时）
- 遗留项 / Backlog

**长度建议：** 150-300 行。Agent 真正需要的是数据模型、API 契约和文件影响范围，UI 交互细节它自己能处理得很好。

**何时需要：** 功能复杂度超过"一句话能说清"的时候。

**维护频率：** 功能开发过程中持续更新，阶段交付后更新状态。

---

## 80-known-pitfalls.md — 踩坑记录

**为什么需要：** Agent 不会自动记住上一次对话中踩过的坑。pitfalls 是"动手前先扫一遍"的预防性文档，和 stage 文件的"设计决策"互补——stage 记录"选了什么"，pitfalls 记录"为什么不能选另一个"。

**写给谁看：** Agent + 未来的你

**核心内容：**
- 按类别组织（API 集成、文件系统、并发、前端等）
- 每条记录三要素：现象、原因、解决方案

**维护频率：** 踩一次记一次。不用等阶段结束。

---

## 81-development-guide.md — 开发指南

**为什么需要：** 项目有非显而易见的配置要求时需要（代理地址、特殊环境变量、构建顺序依赖）。如果 `npm install && npm run dev` 就能跑起来，可以不写。

**写给谁看：** 未来的你 / 协作者

---

## 82-postmortem-*.md — 系统性问题复盘

**为什么需要：** 单点 bug 用 pitfalls 记"现象→原因→解法"就够了，但有时多个 bug 互相关联、反复出现，说明存在系统性问题（缺 e2e 心智模型、组件各自正确但组合出错、只测 happy path 等）。postmortem 做深度复盘，提炼可复用的设计规则和 checklist，防止同类问题再次出现。

**与 pitfalls 的区别：**
- `80-known-pitfalls.md`：单点问题，快速记录，读完就能避坑
- `82-postmortem-*.md`：系统性问题，深度分析，读完能改变做事方式

**写给谁看：** Agent + 未来的你

**核心内容：**
- Bug 时间线（现象 × 根因 × 修复轮次）
- 系统性根因分析（不是重复每个 bug 的技术原因）
- 提炼的设计规则（可复用到同类模块）
- Checklist（以后改这类代码时对照使用）

**何时需要：** 同一模块连续出 3+ 个相关 bug，或一个 bug 修了 2+ 轮才真正解决。

**维护频率：** 事故复盘时写，写完基本稳定。

---

## 84-design-exploration.md — 设计探索

**为什么需要：** UI 设计探索、原型迭代、视觉方案对比等创意过程产物。记录"试过什么、为什么选这个不选那个"，避免同一个方向被重复探索。

**写给谁看：** 未来的你

**核心内容：**
- 探索背景与目标
- 方案对比（方案 × 描述 × 优缺点）
- 最终选择与原因
- 参考链接 / 截图

**何时需要：** 有 UI 设计探索、原型记录等创意过程产物时。

**维护频率：** 探索时记录，决策后基本不改。

---

## 8X-external-*.md — 外部系统参考

**为什么需要：** 私有格式没有官方文档，写一次后面所有阶段都在引用。不记下来的话，每次新对话都得重新分析一遍。

**写给谁看：** Agent

**维护频率：** 外部系统更新时才需要改。

---

## 90-CHANGELOG.md — 变更日志

**为什么需要：** Vibe Coding 的 git log 通常很粗，因为你不会花时间写精细的 commit message。changelog 是你补上这个信息差的地方——记录"什么时候做了什么，为什么这样做"。

**写给谁看：** 你自己

**维护频率：** 每个阶段交付后补一笔。不用每次 commit 都写。

---

## 小型项目通常不需要维护的

> 以下判断基于 1-2 人、单 Agent 协作的 Vibe Coding 项目。如果项目有多人协作、外部 API 调用者、或 stage 文件超过 10 个，请重新评估。

| 文档类型 | 为什么通常不需要 | 何时需要重新考虑 |
|---------|-------------|----------------|
| API 文档（Swagger/OpenAPI） | `04-api-reference.md` 已覆盖项目内部 API 需求 | 需要对外发布标准化 API 文档时 |
| 组件文档（Storybook） | UI 迭代太快，独立组件文档瞬间过时 | 组件被多个项目复用时 |
| 会议纪要 | 对话历史就是"会议纪要"，MEMORY.md 更有效 | 有多个人类参与决策时 |
| 贡献指南（CONTRIBUTING.md） | 除非有其他人类贡献者 | 开源或团队扩展时 |
| 架构决策记录（ADR） | stage 文件的"设计决策"章节够用 | stage 超过 10 个、早期决策上下文丢失时 |

---

## 子目录文件说明

### specs/spec-{name}.md — 任务规格

**为什么需要：** Stage 文件覆盖一个阶段的全部功能，粒度偏大。当一个小功能/改进点需要明确的边界和验收标准，但又不值得开一个完整的 stage 时，spec 是最合适的载体。它也是 review 的评审对象——没有 spec，评审就没有锚点。

**命名兼容：** 推荐 `spec-{name}.md`，历史遗留的 `task-spec-*.md` 也可接受。新建一律用 `spec-*`。

**写给谁看：** Agent + 评审者

**核心内容：** 背景、目标、边界、设计方案（数据模型 + API + 受影响文件）、验收标准

**生命周期：** 在 `specs/` = 活跃，在 `archive/specs/` = 完成。位置即状态，无需维护额外标记。

**与 stage 文件的关系：** Spec 是 stage 内某个功能点的展开。Stage 文件用一行索引指向 spec，不重复 spec 的内容。

**维护频率：** 活跃开发期间持续更新，完成后归档不再修改。

---

### refs/{topic}.md — 参考资料

**为什么需要：** Agent 没有外部系统的内部知识。Stripe webhook 的重试机制、WebRTC 的 signaling 流程、某个私有 API 的字段含义——这些信息每次新对话都要重新查阅。写一次 ref，后续所有 stage/spec 直接引用，不重复调研。

**命名：** 描述性文件名即可（如 `git-sync-workflow.md`、`npx-skills-mechanism.md`）。`ref-` 前缀可选。

**写给谁看：** Agent

**核心内容：** 机制说明、关键 API 摘要、与本项目的集成点、踩坑备注、来源链接和版本

**生命周期：** 长期存在，不主动归档。外部系统更新时更新内容并刷新 `Last verified` 标记。集成方案废弃时标记 `<!-- Deprecated -->`。

**与其他文件的关系：** Stage/spec 中通过 `→ 详见 refs/ref-xxx.md` 引用。Ref 文件本身不引用 stage/spec（单向依赖）。

**维护频率：** 外部系统版本更新时检查。日常开发中基本稳定。

---

### reviews/review-{date}-{subject}.md — 评审记录

**为什么需要：** Spec 通过评审进入 approved 状态，但评审中发现的问题和 action items 如果不记录，下次对话就丢失了。Review 文件是评审结论的持久化存储，也是归档前的 checklist——action items 全部完成才能归档。

**写给谁看：** 你自己 + Agent（检查 action items）

**核心内容：** 评审对象（链接到 spec/PR）、结论、发现的问题列表、action items、遗留讨论点

**生命周期：** 创建后更新 action items 的完成状态，全部完成后移入 `archive/reviews/`。

**联动规则：** 创建后在对应 spec 头部追加 `<!-- Reviewed: YYYY-MM-DD → reviews/review-xxx.md -->`。

**维护频率：** 评审后创建，action items 推进时更新勾选，归档后不再修改。

---

### archive/ — 归档目录

**为什么需要：** 删除历史文档会丢失上下文——三个月后你想知道"当时为什么这样设计"却找不到了。归档保留完整历史，但把它们从活跃目录移走，减少 Agent 的搜索噪音。

**子结构：** `archive/specs/`、`archive/reviews/`、`archive/stages/`

**归档原则：**
- 只做移入，不删除（`git mv` 保留 git 历史）
- 原位留痕：在 roadmap/backlog 中标注 `[archived → archive/xxx]`
- 引用不断链：归档后全文搜索旧路径，更新指向新路径
