spec-writing

name	spec-writing
description	撰写和修订模块化需求功能文档，输出到 specs/ 目录。每篇功能文档包含六段结构：功能概述、用户故事、需求描述、技术要求、约束条件、测试标准。所有结构图（逻辑、模块、流程、时序、架构、ER）严格使用 Mermaid 代码，目录树使用纯文本树格式。Monorepo 默认 apps/ + packages/ 布局。 务必在以下场景使用本 skill：用户提到需求文档、PRD、产品需求、功能文档、specs、用户故事、user stories、验收标准、acceptance criteria、feature requirements、需求分析、业务需求、功能需求、需求规格、需求评审、需求变更、功能点拆分，或者用户要求撰写 / 修订 / 评审某个功能的详细描述，即使没有明确说“需求文档”。不适用于纯技术选型文档。

需求文档（Specs）

本 Skill 负责需求文档的撰写与修订——从一句话需求到结构化的、可交付的功能文档。它解决的核心问题是：让需求表达从模糊口头沟通变成可追踪、可评审、可验收的标准化文档。

不负责独立技术选型长文。不替代 UI 视觉设计稿，但须用 Mermaid 表达所有结构类信息，因为 Mermaid 可版本管理、可协作编辑、可嵌入 Markdown。

原则

• 模块化：按系统模块拆分目录；模块内按页面或功能点独立成文件，避免单文件过长。这样做的好处是每个文件有清晰的职责边界，团队可并行编写，评审和变更时只需关注受影响的文件。
• 结构化：每个功能文档必须包含下列 六个部分，缺一不可。六段结构确保从"做什么"到"怎么验收"形成闭环，避免遗漏。
• Monorepo 语境：若需求涉及仓库布局，默认约定为 apps/ 业务应用、packages/ 可复用包；与项目实际不符时以用户/仓库说明为准。

图表绘制策略

场景	工具	说明
逻辑/流程图（分支、回流、状态）	Mermaid flowchart	强制定义每条路径，消除歧义
模块/架构图（依赖、分层）	Mermaid graph TD/LR	结构关系可视化
时序图（API 调用、消息流）	Mermaid sequenceDiagram	多角色交互天然匹配
实体关系图（数据库、领域模型）	Mermaid erDiagram	实体 + 关系 + 属性
状态机	Mermaid stateDiagram-v2	状态转移天然匹配
目录树 / 文件结构	纯文本树（├── └──）	层级结构紧凑直观，模型天然理解

规则：逻辑、模块、流程、时序、架构、ER 等结构图严格使用 Mermaid 代码。目录树/文件结构使用纯文本树格式。Mermaid 是纯文本，可 Git 管理、可 diff、可 PR review。

何时该画图：≥2 角色交互→时序图；≥3 步分支→流程图；新增/变更实体→ER 图；模块依赖→模块图。

详细类型表、使用指南与示例见 → references/mermaid-guide.md

推荐目录示例

specs/
├── auth/
│   ├── login.md
│   └── register.md
├── user/
│   ├── profile.md
│   └── settings.md
└── dashboard/
    └── overview.md

单篇功能文档六段结构

1. 功能概述
   一两句话说明目标与业务价值：做什么、为什么做，范围清晰。好的概述能让不了解项目背景的人在 10 秒内理解这个功能的意义。

2. 用户故事
   格式：作为 [用户角色]，我希望 [完成某件事]，以便 [获得某种价值]。
   可多条，覆盖不同角色或场景。

   示例：

   • 作为普通用户，我希望通过手机号+验证码登录，以便无需记忆密码即可快速访问系统。
   • 作为管理员，我希望查看登录失败日志，以便及时发现异常访问行为。

3. 需求描述（结构化）

   • 输入：数据、触发条件
   • 输出：结果、界面变化
   • 交互流程：步骤与状态流转（复杂流程须配流程图或时序图）
   • 界面要求：布局、组件形态、文案；空态 / 加载态 / 错误态

4. 技术要求
   接口与数据结构、性能指标（响应时间、并发等）、特殊实现（防抖、轮询、懒加载等）；涉及多模块协作时可配模块图；涉及新增或变更库表/实体时须配 erDiagram（或与项目统一 ER 文档交叉引用并说明变更点）。

5. 约束条件
   时间线与优先级、第三方依赖（短信、支付、地图等）、合规与安全、本期不做的边界。明确"不做什么"与"做什么"同等重要，它防止范围蔓延。

6. 测试标准（验收）

   • 正常路径：覆盖核心业务流程
   • 边界值：极值、空值、最大长度等
   • 异常路径（非法输入、网络错误、权限不足等）
   • 回归点（可能影响到的已有功能）
   • 交叉组合编排（当存在多个测试维度时）

   每条测试标准应具备可执行性：描述操作步骤和预期结果，而非仅说明抽象要求。

交叉组合编排与优先级评定

当一个功能涉及多组独立的测试维度（≥ 2 维且至少有一维 ≥ 3 取值）时，需要显式列出维度组合矩阵并评定每条组合的优先级（P0 / P1 / P2 / P3），为后续 TDD 提供铺垫。

优先级判定顺序：核心业务路径 → 资金/安全相关 → 错误恢复 → 边界值 → 等价类合并 → 逻辑不可达。矩阵中 P0 行直接对应 TDD 第一批测试用例。

完整编排步骤、优先级定义、判断依据与登录功能 12 组合示例见 → references/test-matrix.md

执行方式

• 新建：先定模块与文件路径，再按六段逐段补齐；缺信息时向用户确认，不臆造业务规则；该画图处给出 Mermaid，不省略。
• 修订：保持模块边界；改动处同步更新「测试标准」与「约束条件」中相关条目，并同步更新相关 Mermaid 图。
• 评审辅助：如果用户提供了已有需求文档让你评审，按六段结构逐项检查完整性，指出缺失或模糊之处，给出修改建议。

常见问题与处理

• 用户只给了一句话需求（如"做一个登录功能"）：先拆解为需要收集的信息清单（支持哪些登录方式？有无第三方登录？是否需要注册？），逐步引导用户澄清，再输出六段文档。
• 需求跨多个模块：为每个模块生成独立文档，但在各文档的「技术要求」中交叉引用相关模块，必要时画模块依赖图。
• Mermaid 图过于复杂：拆成多张小图，每张聚焦一个关注点（如一张时序图专注登录流程，另一张专注 token 刷新流程）。