# 需求文档规范（统一模板）

本目录用于沉淀“每个需求从分析到验收”的全流程文档。目标是让任何人只看该需求目录即可完成评审、开发、测试与验收，且形成可复用的组织方式。


## 目录命名规范

每个需求一个目录，命名为：

- `YYYY-MM-DD-需求名称`

示例：
- `2026-04-27-Cursor风格Plan模式`
- `2026-05-03-任务执行状态页重构`

> 建议：需求名称尽量短（<= 20 字），避免空格与特殊符号；使用中文或英文均可，优先中文。


## 文件集合（推荐必备）

每个需求目录内，建议按以下文件拆分（可按需增删，但建议保持顺序与编号）：

- `00-README.md`
  - 需求概览、范围、关键结论、快速链接（指向下面各文档）

- `01-需求分析.md`
  - 背景/问题/目标/非目标/用户故事/成功标准（DoD）/约束与风险

- `02-方案调研.md`
  - 现状分析、竞品/参考（如 Cursor）、备选方案对比、取舍理由

- `03-总体方案与架构设计.md`
  - 全周期流程、状态机、模块边界、核心数据结构、关键交互（含时序图）

- `04-详细设计.md`
  - 关键模块细节、接口契约（入参/出参）、工具/权限门禁、数据流与存储

- `05-开发拆解与改造清单.md`
  - MUST/SHOULD/NICE 分级任务清单（含文件路径与验收点）

- `06-测试方案.md`
  - 单测/集成测/端到端、覆盖点、测试数据、回归范围

- `07-验收标准与回滚.md`
  - 验收步骤、验收口径、监控指标、灰度/回滚策略

可选：
- `08-会议纪要.md`（评审结论、决策记录）
- `09-上线记录.md`（版本、变更、问题复盘）


## 编写要求（强约束）

- **单一事实来源（SSOT）**：需求相关关键结论必须在该需求目录内可找到，不要散落到多个不相关文档里。
- **先结论后细节**：每个文档开头先写“结论/决策”，再写推导过程。
- **有验收就有约束**：每个关键设计点都应对应测试/验收点。
- **接口契约明确**：涉及 API/上下文/工具调用必须写清楚“什么时候用、入参、出参、失败分支”。
- **图优先**：复杂流程必须给出 Mermaid 图（flowchart/sequenceDiagram/stateDiagram 三选一或组合）。


## Mermaid 兼容性建议（避免解析报错）

- 尽量使用 ASCII：`<=` 替代 `≤`，避免全角标点。
- flowchart 节点建议用 `A["中文文本"]` 这种写法。
- 每条边单独一行，避免一行太长导致某些渲染器换行异常。
