01 需求调研：把模糊想法变成可验收的用户故事¶

需求阶段的目标不是“写一份很长的文档”，而是让后面每一个 Agent 都能明确回答三个问题：做什么、不做什么、怎么算做完。

1. 这个阶段要产出什么¶

产物	路径	作用	谁读
原始记录	`docs/00-discovery/raw-notes.md`	保存访谈、灵感、约束，避免信息丢失	人、需求 Agent
功能规格	`docs/00-discovery/spec.md`	完整的需求说明：目标、范围、规则、边界	架构师、开发 Agent、测试 Agent
用户故事总表	`docs/00-discovery/user-story.csv`	唯一状态源：优先级、状态、负责人、链接	人、所有 Agent、看板
故事实现细节	`docs/00-discovery/user-story-details.md`	每个故事的 UI、API、数据、规则、验收用例	开发 Agent、测试 Agent
排期	`docs/00-discovery/schedule.md`	里程碑、依赖、关键路径、缓冲	人
追溯矩阵	`docs/00-discovery/traceability.md`	需求 → 故事 → API → 表 → 测试	人、审查 Agent

为什么要有 CSV 和 MD 两个文件？

CSV 负责“管理和追踪”：人一眼能看到全局状态，脚本能可靠更新。
MD 负责“表达和推理”：业务规则、边界条件、验收用例写成自然语言，Agent 读起来更准确。

两者通过 story_id 关联。CSV 里记录 details_ref 指向 MD 的章节锚点。

2. 第一步：保存原始输入¶

在开始任何 AI 分析之前，先把你脑子里的东西倒出来，保存为 raw-notes.md。不要急着结构化，先把信息留住。

# 原始需求记录

日期：2026-10-25
记录人：xxx

## 背景
我们是一个 20 人的咨询团队，目前用 Excel 管理项目任务，经常出现：
- 任务负责人不清楚
- 截止日期被忘记
- 客户反馈散落在微信里

## 想要的东西
一个简单的团队任务协作系统，能创建项目、分配任务、看板展示、评论提醒。

## 约束
- 预算有限，先做 MVP
- 团队用微信登录
- 需要部署到 AWS
- 3 周内上线

## 我还不确定的
- 要不要做移动端？
- 要不要对接企业微信？
- 权限模型要几层？

保存原始记录的好处：

后面 AI 生成的 spec 如果偏离原意，你可以对照。
新会话可以从原始记录重新开始，不依赖记忆。
需求变更时，能看到“最初为什么这么想”。

3. 第二步：让 AI 做需求访谈¶

不要一上来就让 AI “写 PRD”。先让它提问。一个不会提问的需求分析师，只会把你没想清楚的地方编得很圆满。

3.1 访谈提示词¶

你是资深产品经理兼需求分析师，擅长把模糊想法变成可交付的软件需求。

请阅读 @docs/00-discovery/raw-notes.md。

现在不要写方案，也不要写 PRD。请一次性提出最多 12 个澄清问题。
要求：
1. 覆盖以下维度：目标用户、核心场景、非目标、数据实体、权限、集成、合规、成功指标、上线约束、运维。
2. 每个问题给出 2-3 个可选答案，并标出你推荐哪个、为什么。
3. 优先问那些“答案会显著改变技术方案”的问题。
4. 如果某个问题可以从原始记录推断，不要重复问。
5. 用表格输出：编号、问题、选项、推荐、影响。

拿到回答后，再让 AI 做一轮“追问”：

基于我上面的回答，请再做一轮追问，最多 6 个问题。
重点追问：
- 异常流程（失败了怎么办）
- 权限边界（谁能看、谁能改、谁能删）
- 数据生命周期（创建、修改、归档、删除、导出）
- 并发与冲突（两个人同时改同一条数据怎么办）
- 非功能要求（性能、可用性、审计、隐私）

3.2 访谈问题清单（人类自查）¶

如果你不想完全依赖 AI，可以用这张清单自查：

目标与范围 - [ ] 这个产品解决谁的什么问题？ - [ ] 成功的标准是什么？用哪个指标衡量？ - [ ] MVP 必须有什么？可以推迟什么？ - [ ] 明确不做什么？（非目标） - [ ] 有没有预算、时间、合规上的硬约束？

用户与场景 - [ ] 有哪几类用户？他们的权限有什么不同？ - [ ] 每类用户最重要的 3 个场景是什么？ - [ ] 新用户第一次使用会发生什么？ - [ ] 用户操作失败时，期望看到什么？

数据与规则 - [ ] 核心实体有哪些？它们的关系是什么？ - [ ] 哪些字段是必填的？有哪些格式/长度限制？ - [ ] 数据可以删除吗？删除是软删除还是硬删除？ - [ ] 需要审计日志吗？记录哪些操作？ - [ ] 数据需要导出/导入吗？什么格式？

权限与安全 - [ ] 谁能创建、查看、修改、删除、审批？ - [ ] 跨团队/跨租户的数据如何隔离？ - [ ] 需要哪些登录方式？要不要多因素认证？ - [ ] 有没有敏感数据（个人信息、支付信息、健康数据）？

集成与运维 - [ ] 需要对接哪些外部系统？接口文档有吗？ - [ ] 部署到哪里？有什么网络/域名/证书要求？ - [ ] 需要监控、告警、备份吗？ - [ ] 预计多少用户、多少数据量、多少并发？

4. 第三步：生成功能规格 `spec.md`¶

4.1 规格文档的结构¶

一份可执行的 spec.md 应该包含以下部分：

# 功能规格说明书：<产品名>

## 1. 背景与问题
## 2. 目标与非目标
## 3. 用户与角色
## 4. 核心用户旅程
## 5. 功能需求（FR）
## 6. 非功能需求（NFR）
## 7. 数据实体与关系
## 8. 权限模型
## 9. 错误与异常处理
## 10. 验收标准
## 11. 范围之外
## 12. 假设与待确认问题
## 13. 成功指标

4.2 功能需求编号¶

每个功能需求用 FR-xxx 编号，后面所有故事、接口、测试都引用它：

### FR-001 用户登录
系统应支持用户使用邮箱和密码登录。

规则：
- 邮箱必须已注册且已验证。
- 密码错误连续 5 次，锁定 15 分钟。
- 登录成功后返回访问令牌和刷新令牌。
- 访问令牌有效期 15 分钟，刷新令牌有效期 7 天。
- 所有登录尝试记录审计日志。

异常：
- 邮箱未注册：返回统一错误 `AUTH_INVALID_CREDENTIALS`，不暴露邮箱是否存在。
- 账号被锁定：返回 `AUTH_ACCOUNT_LOCKED`，并告知剩余锁定时间。
- 系统错误：返回 `INTERNAL_ERROR`，记录 request_id。

关键：规则要写成可测试的句子。 “友好的错误提示”不可测试，“返回 AUTH_INVALID_CREDENTIALS 且 HTTP 401”可测试。

4.3 非功能需求¶

NFR 经常被 AI 忽略，但它们是线上事故的高发区：

类别	示例	可测试的写法
性能	页面加载快	P95 API 延迟 < 300ms（100 并发）
可用性	系统稳定	月度可用性 ≥ 99.9%
安全	防止越权	用户只能访问自己所属租户的数据
隐私	合规	日志中不得出现密码、令牌、身份证号
可维护性	易扩展	新增一种登录方式不超过 2 人日
可观测性	可排查	每个请求有 `request_id`，错误日志包含用户 ID 和路径
兼容性	多端	支持 Chrome/Safari/Edge 最近两个大版本
可访问性	无障碍	关键流程可通过键盘完成，对比度 ≥ 4.5:1

4.4 生成 spec 的提示词¶

你是资深产品经理。基于以下材料生成 `spec.md`：

- 原始记录：@docs/00-discovery/raw-notes.md
- 访谈问答：@docs/00-discovery/interview-answers.md

要求：
1. 严格按模板结构输出（见 @模板/spec.md）。
2. 每个功能需求用 FR-xxx 编号，规则必须可测试。
3. 每个功能需求至少写一个异常分支。
4. 明确写出“非目标”和“范围之外”。
5. 不要发明我没有提供的信息；不确定的地方列入“假设与待确认问题”。
6. 用中文输出，术语保持一致。
7. 输出前自查：有没有互相矛盾的需求？有没有无法测试的形容词？

4.5 让 AI 做“需求批判”¶

生成之后，换一个 Agent（或新会话）做批判，避免同一个 AI 为自己的输出辩护：

你是苛刻的需求评审专家。请审查 @docs/00-discovery/spec.md。

请找出：
1. 模糊、不可测试的需求（给出原文和改写建议）。
2. 互相矛盾的需求。
3. 缺失的异常流程（失败、超时、权限不足、数据为空）。
4. 缺失的权限边界。
5. 可能导致范围蔓延的地方。
6. 技术上明显不可行或成本过高的地方。
7. 应该拆分的过大需求。

输出表格：问题编号、位置、问题、影响、建议。
不要改文件，只输出审查结果。

5. 第四步：拆用户故事¶

5.1 用户故事格式¶

统一使用：

作为 <角色>，
我希望 <能力>，
以便 <价值>。

示例：

作为 项目成员，
我希望 在任务卡片上看到截止日期和负责人，
以便 我能快速判断今天该做什么。

避免的写法：

“系统应该有一个任务列表。”（没有角色和价值）
“用户可以管理任务。”（太模糊，无法验收）
“实现任务 CRUD。”（这是技术任务，不是用户故事）

5.2 INVEST 原则¶

原则	含义	检查问题
Independent	独立	能否单独开发、测试、上线？
Negotiable	可协商	实现方式是否还有讨论空间？
Valuable	有价值	用户能感知到什么价值？
Estimable	可估算	团队能否给出大致工作量？
Small	小	能否在 1-3 天内完成？
Testable	可测试	有没有明确的验收标准？

5.3 验收标准：Given / When / Then¶

每个故事至少写 1 个正常路径 + 2 个异常路径：

US-004 创建任务

AC-1 正常创建
Given 我是项目成员，且项目处于进行中状态
When 我填写标题“完成周报”、负责人“张三”、截止日期“2026-11-01”并提交
Then 任务创建成功，返回 201，任务出现在看板“待办”列
And 审计日志记录“created task <id>”

AC-2 标题为空
Given 我是项目成员
When 我提交标题为空的任务
Then 返回 400，错误码 `VALIDATION_ERROR`
And 页面在标题输入框下方显示“标题不能为空”

AC-3 无权限
Given 我不是该项目成员
When 我尝试在该项目下创建任务
Then 返回 403，错误码 `FORBIDDEN`
And 页面显示“你没有权限在该项目中创建任务”

AC-4 截止日期早于今天
Given 我是项目成员
When 我选择昨天的日期并提交
Then 返回 400，错误码 `VALIDATION_ERROR`
And 页面提示“截止日期不能早于今天”

验收标准的质量，直接决定 E2E 测试的质量。 如果验收标准写得模糊，AI 的测试也会模糊。

5.4 故事拆分技巧¶

大故事拆法：

按 CRUD 拆：创建 → 查看 → 编辑 → 删除（但要注意每个都是独立价值）。
按角色拆：普通成员 → 管理员 → 访客。
按规则拆：基础流程 → 权限 → 异常 → 批量操作。
按数据拆：单条 → 列表 → 搜索/筛选 → 导出。
按渠道拆：Web → 移动端 → API。

不要按技术层拆（“先做数据库，再做 API，再做页面”）。那样每个故事都无法独立验收，也无法并行。

5.5 生成用户故事的提示词¶

你是资深敏捷教练。请基于 @docs/00-discovery/spec.md 拆分用户故事。

要求：
1. 每个故事用“作为…我希望…以便…”格式。
2. 每个故事至少 1 个正常路径 + 2 个异常路径的 Given/When/Then 验收标准。
3. 每个故事标注：
   - 所属模块
   - 优先级（P0/P1/P2/P3）
   - 依赖的故事 ID
   - 涉及的数据实体
   - 预估故事点（1/2/3/5/8）
4. 每个故事必须能独立开发、测试、演示。
5. 不要按技术层拆分，按用户价值拆分。
6. 如果某个故事超过 8 个故事点，继续拆分。
7. 输出为 Markdown 表格，最后再输出 CSV 行（我会复制到 user-story.csv）。

6. 第五步：建立 `user-story.csv`¶

6.1 列定义¶

列名	说明	示例
`story_id`	唯一 ID，建议 `US-001`	`US-004`
`module`	所属模块	`任务管理`
`title`	简短标题	`创建任务`
`as_a`	角色	`项目成员`
`i_want`	能力	`创建一个带负责人和截止日期的任务`
`so_that`	价值	`我能把工作分配清楚`
`priority`	P0/P1/P2/P3	`P0`
`status`	状态机枚举	`ready`
`owner`	负责的 Agent 或人	`backend-agent-1`
`branch`	分支名	`feat/US-004-create-task`
`spec_ref`	规格章节	`spec.md#fr-004`
`details_ref`	细节文档锚点	`user-story-details.md#us-004`
`api_ref`	API 契约	`openapi.yaml#/paths/~1tasks/post`
`db_tables`	涉及的表	`tasks;audit_logs`
`feature_report`	实现报告路径	`docs/03-dev/reports/US-004-创建任务.md`
`e2e_manifest`	E2E 清单路径	`docs/04-qa/manifests/US-004.json`
`unit_test_status`	`pending/pass/fail`	`pass`
`integ_test_status`	`pending/pass/fail`	`pass`
`dev_url`	开发环境入口	`http://localhost:5173`
`staging_url`	预发环境入口	`https://staging.example.com`
`prod_url`	生产环境入口	`https://app.example.com`
`dev_deploy_status`	`not_deployed/deployed/failed`	`deployed`
`staging_deploy_status`	同上	`deployed`
`prod_deploy_status`	同上	`deployed`
`estimate_sp`	预估故事点	`3`
`actual_sp`	实际故事点	`2`
`dependencies`	依赖的故事	`US-002;US-003`
`last_updated`	ISO 时间	`2026-10-25T14:30:00+08:00`
`notes`	备注	`需要企业微信登录，暂用邮箱`

spec_ref / details_ref 建议使用显式 HTML 锚点（模板已内置 <a id="fr-001"></a>、<a id="us-001"></a>），避免标题改名后链接失效。

6.2 示例 CSV¶

story_id,module,title,as_a,i_want,so_that,priority,status,owner,branch,spec_ref,details_ref,api_ref,db_tables,feature_report,e2e_manifest,unit_test_status,integ_test_status,dev_url,staging_url,prod_url,dev_deploy_status,staging_deploy_status,prod_deploy_status,estimate_sp,actual_sp,dependencies,last_updated,notes
US-001,认证,用户登录,注册用户,用邮箱和密码登录,我能安全地进入系统,P0,ready,backend-agent-1,feat/US-001-login,spec.md#fr-001,user-story-details.md#us-001,openapi.yaml#/paths/~1auth~1login/post,"users;audit_logs",docs/03-dev/reports/US-001-用户登录.md,docs/04-qa/manifests/US-001.json,pending,pending,http://localhost:5173,https://staging.example.com,https://app.example.com,not_deployed,not_deployed,not_deployed,3,,,,2026-10-25T10:00:00+08:00,先做邮箱登录
US-002,项目,创建项目,团队管理员,创建一个新项目,我能把团队的工作组织起来,P0,ready,backend-agent-1,feat/US-002-create-project,spec.md#fr-002,user-story-details.md#us-002,openapi.yaml#/paths/~1projects/post,"projects;project_members;audit_logs",docs/03-dev/reports/US-002-创建项目.md,docs/04-qa/manifests/US-002.json,pending,pending,http://localhost:5173,https://staging.example.com,https://app.example.com,not_deployed,not_deployed,not_deployed,3,US-001,,2026-10-25T10:00:00+08:00,
US-003,项目,邀请成员,项目管理员,邀请团队成员加入项目,团队成员能协作,P0,ready,backend-agent-2,feat/US-003-invite-member,spec.md#fr-003,user-story-details.md#us-003,openapi.yaml#/paths/~1projects~1{id}~1members/post,"project_members;invitations;audit_logs",docs/03-dev/reports/US-003-邀请成员.md,docs/04-qa/manifests/US-003.json,pending,pending,http://localhost:5173,https://staging.example.com,https://app.example.com,not_deployed,not_deployed,not_deployed,3,US-002,,2026-10-25T10:00:00+08:00,
US-004,任务,创建任务,项目成员,创建带负责人和截止日期的任务,我能把工作分配清楚,P0,ready,backend-agent-3,feat/US-004-create-task,spec.md#fr-004,user-story-details.md#us-004,openapi.yaml#/paths/~1tasks/post,"tasks;audit_logs",docs/03-dev/reports/US-004-创建任务.md,docs/04-qa/manifests/US-004.json,pending,pending,http://localhost:5173,https://staging.example.com,https://app.example.com,not_deployed,not_deployed,not_deployed,5,US-002;US-003,,2026-10-25T10:00:00+08:00,
US-005,任务,任务看板,项目成员,在看板上拖动任务改变状态,我能直观地管理进度,P1,ready,frontend-agent-1,feat/US-005-kanban,spec.md#fr-005,user-story-details.md#us-005,openapi.yaml#/paths/~1tasks~1{id}~1status/patch,"tasks",docs/03-dev/reports/US-005-任务看板.md,docs/04-qa/manifests/US-005.json,pending,pending,http://localhost:5173,https://staging.example.com,https://app.example.com,not_deployed,not_deployed,not_deployed,5,US-004,,2026-10-25T10:00:00+08:00,

6.3 CSV 使用规则¶

UTF-8 with BOM：用 Excel 打开中文不乱码。Python 写入时用 encoding="utf-8-sig"。
含逗号、引号、换行的字段必须用双引号包裹，内部双引号写成 ""。
不要手改状态：用脚本 scripts/update_story_status.py 更新，避免格式损坏。
每次更新 last_updated：方便排序和审计。
notes 不要写长文：长内容放 user-story-details.md 或实现报告。
提交到 Git：CSV 是项目资产，不是临时文件。

6.4 CSV 校验脚本¶

在进入开发前，先校验 CSV 的结构和状态合法性：

python3 scripts/validate_user_stories.py docs/00-discovery/user-story.csv

脚本应检查：

列名是否完整；
story_id 是否唯一；
priority 是否在枚举内；
status 是否在状态机内；
引用的 feature_report / e2e_manifest 路径是否存在（已完成的才检查）；
dependencies 是否指向存在的故事；
是否有循环依赖。

配套脚本见脚本目录。如果暂时没有校验脚本，至少用 Python 的 csv 模块读一遍，不要用 Excel 直接另存。

7. 第六步：编写 `user-story-details.md`¶

CSV 只适合放短字段。真正指导开发的细节，写在 MD 里。

7.1 每个故事的结构¶

## US-004 创建任务

### 1. 目标
项目成员可以在项目中创建任务，并指定负责人、截止日期和优先级。

### 2. 角色与权限
- 项目成员：可以在自己所属的项目中创建任务。
- 项目访客：只能查看，不能创建。
- 非项目成员：返回 403。

### 3. 入口与界面
- 页面：项目详情页 → 看板 → “+ 新建任务”按钮。
- 弹窗字段：
  | 字段 | 类型 | 必填 | 校验 |
  |---|---|---|---|
  | 标题 | 文本 | 是 | 1-100 字符 |
  | 描述 | 多行文本 | 否 | ≤ 2000 字符 |
  | 负责人 | 下拉选择 | 是 | 必须是项目成员 |
  | 截止日期 | 日期 | 否 | 不早于今天 |
  | 优先级 | 枚举 | 是 | 低/中/高，默认中 |

### 4. 业务规则
1. 任务创建后默认状态为 `todo`。
2. 任务编号由服务端生成，格式 `TASK-<项目短码>-<序号>`。
3. 创建人自动成为任务关注者。
4. 负责人会收到站内通知（如果已开启通知）。
5. 所有创建操作写入审计日志。

### 5. 数据模型
- 表：`tasks`
- 关键字段：`id`, `project_id`, `title`, `description`, `assignee_id`, `due_date`, `priority`, `status`, `created_by`, `created_at`, `updated_at`, `version`
- 索引：`(project_id, status, due_date)`

### 6. API
- `POST /api/v1/tasks`
- 请求体：见 OpenAPI `CreateTaskRequest`
- 成功：201 + `TaskResponse`
- 失败：400 `VALIDATION_ERROR` / 403 `FORBIDDEN` / 404 `PROJECT_NOT_FOUND`

### 7. 验收标准
（复制 CSV 对应的 Given/When/Then，至少 4 条）

### 8. 边界与异常
- 项目已归档：不允许创建，返回 409 `PROJECT_ARCHIVED`。
- 负责人不是项目成员：400 `ASSIGNEE_NOT_IN_PROJECT`。
- 并发创建同名任务：允许，不做唯一约束。
- 日期使用用户所在时区，服务端统一存 UTC。

### 9. 可观测性
- 日志字段：`request_id`, `user_id`, `project_id`, `task_id`, `duration_ms`
- 指标：`task_created_total{project_id}`
- 审计：`action=task.created`, `resource=task:<id>`

### 10. 依赖
- 依赖 US-002（项目）和 US-003（成员）。
- 被 US-005（看板）依赖。

### 11. 完成定义
- 单元测试覆盖 service 层和 handler 层；
- 集成测试覆盖数据库约束和权限；
- E2E 覆盖正常创建、空标题、无权限；
- 实现报告已生成；
- CSV 状态为 `qa_pass`。

7.2 细节文档的写作原则¶

可执行：开发 Agent 看完就能写代码，不需要再猜。
可测试：每条规则都能对应一个测试用例。
无歧义：避免“适当”“友好”“尽快”等词。
有边界：正常路径、异常路径、权限边界、并发边界都写到。
有引用：API 引用 OpenAPI，数据引用 schema，设计引用 Figma 页面。

8. 第七步：排期¶

8.1 排期的单位¶

不要用“小时”估算 AI 的工作量。AI 的执行速度不是瓶颈，评审和返工才是。建议用“故事点 + 人的评审时间”双维度：

故事点	复杂度	AI 执行	人的评审
1	简单 CRUD、纯展示	0.5-1 小时	15 分钟
2	有校验、有状态变化	1-2 小时	30 分钟
3	多表关联、权限	2-4 小时	1 小时
5	跨模块、复杂交互	0.5-1 天	2 小时
8	高风险、外部集成	1-2 天	半天

8.2 排期模板¶

# 排期

## 里程碑
| 里程碑 | 日期 | 交付物 | 门禁 |
|---|---|---|---|
| M1 需求冻结 | 2026-10-27 | spec + stories + 排期 | G1 |
| M2 设计冻结 | 2026-10-29 | Figma + ui-spec | G2 |
| M3 契约冻结 | 2026-11-01 | OpenAPI + schema + tech-design | G4 |
| M4 功能完成 | 2026-11-08 | 代码 + 单测 + 集成测试 | G5 |
| M5 验收通过 | 2026-11-11 | Word 报告 + 人工走查 | G6 |
| M6 上线 | 2026-11-13 | 生产部署 + 冒烟 | G7 |
| M7 线上验证 | 2026-11-14 | 线上 Word 报告 | 发布验收 |

## 关键路径
US-001 → US-002 → US-003 → US-004 → US-005 → 联调 → E2E → 部署

## 缓冲
- 技术风险缓冲：20%
- 评审返工缓冲：20%
- 环境/权限缓冲：10%

## 并行计划
- 第 1 批（串行）：US-001、US-002
- 第 2 批（并行）：US-003（后端 Agent 2）、US-004（后端 Agent 3）、US-005（前端 Agent 1）
- 第 3 批：联调 + E2E + 修复

## 假设
- AWS 账号和权限已就绪
- Figma 设计稿在 M2 前完成
- 测试账号已创建

8.3 排期的常见错误¶

错误	后果	修正
按“AI 很快”压缩全部时间	评审和返工挤在一起	给人工评审留固定窗口
不留缓冲	一个环境问题拖垮全盘	至少 20% 缓冲
并行度过高	合并冲突、上下文切换	先 2-3 个 Agent
忽略依赖	前端等后端、后端等设计	画依赖图，标关键路径
没有里程碑门禁	做到哪算哪	每个里程碑绑定一个门禁

9. 第八步：追溯矩阵¶

追溯矩阵用来回答：“这个需求有没有被实现？有没有被测试？”

| 需求 | 用户故事 | API | 数据表 | 单元测试 | 集成测试 | E2E |
|---|---|---|---|---|---|---|
| FR-001 登录 | US-001 | POST /auth/login | users, audit_logs | auth/service_test.go | auth/integration_test.go | US-001.json |
| FR-002 创建项目 | US-002 | POST /projects | projects, project_members | project/service_test.go | project/integration_test.go | US-002.json |
| FR-003 邀请成员 | US-003 | POST /projects/{id}/members | project_members, invitations | member/service_test.go | member/integration_test.go | US-003.json |
| FR-004 创建任务 | US-004 | POST /tasks | tasks, audit_logs | task/service_test.go | task/integration_test.go | US-004.json |
| FR-005 看板 | US-005 | PATCH /tasks/{id}/status | tasks | task/service_test.go | task/integration_test.go | US-005.json |

进入 G5 代码门禁前，要求：

每个 P0/P1 需求至少有一个用户故事；
每个用户故事至少有一个 API 和一组测试；
每个验收标准至少被一个 E2E 步骤覆盖。

10. G1 范围门禁：人要确认什么¶

在需求阶段结束前，人需要明确回答以下问题。不要用“差不多”“先这样”糊弄过去。

10.1 范围确认¶

这个产品解决的核心问题是什么？一句话能说清吗？
MVP 包含哪些用户故事？P0 列表是什么？
明确不做什么？非目标列表是什么？
哪些功能可以推迟到 v2？
有没有“看起来简单但实际很复杂”的功能？是否要砍掉？

10.2 验收确认¶

每个 P0 故事都有可测试的验收标准吗？
异常路径和权限边界写了吗？
成功指标定义了吗？
上线时间和预算约束现实吗？

10.3 风险确认¶

有没有外部依赖（第三方 API、登录、支付、短信）？文档和测试账号有吗？
有没有合规/隐私要求？
有没有技术不确定性？是否需要先做 spike？
排期缓冲够吗？

10.4 签字¶

在 spec.md 末尾记录：

## 范围确认

- 确认人：<姓名>
- 确认日期：2026-10-27
- 确认内容：本 spec 的 P0/P1 范围、非目标、验收标准
- 备注：同意先不做移动端，v2 再评估

11. 常见反模式¶

反模式 1：让 AI 直接写 PRD，不做访谈¶

后果：AI 会填补所有空白，生成一份看起来完整、实际充满假设的文档。

修正：先访谈，再生成；把“假设”单独列出来，逐条确认。

反模式 2：验收标准写成形容词¶

坏例子：“页面加载要快”“提示要友好”“权限要合理”。

好例子：“P95 < 300ms”“错误提示包含错误码和下一步操作”“非项目成员返回 403”。

反模式 3：故事太大¶

坏例子：“任务管理模块”。

好例子：创建任务、编辑任务、任务看板、任务筛选、任务导出。

反模式 4：没有非目标¶

后果：AI 和人都容易范围蔓延，最后做了一堆没人用的功能。

修正：在 spec.md 里单独写“范围之外”，并在 G1 确认。

反模式 5：CSV 和 MD 不一致¶

后果：Agent 读到两个版本的“事实”，实现和验收对不上。

修正：CSV 只放短字段和链接，细节只写在 MD 里；用脚本校验引用是否存在。

反模式 6：忽略数据生命周期¶

后果：删除、归档、导出、审计没设计，上线后补很痛苦。

修正：每个实体都问一遍：创建、读取、修改、删除、归档、导出、审计。

反模式 7：没有测试账号和测试数据¶

后果：E2E 阶段卡在登录、验证码、权限上。

修正：需求阶段就创建测试账号、测试租户、种子数据脚本。

12. 本章交付清单¶

在进入 UI 阶段前，确认以下文件都已存在并提交 Git：

docs/00-discovery/raw-notes.md
docs/00-discovery/interview-answers.md（可选但推荐）
docs/00-discovery/spec.md
docs/00-discovery/user-story.csv
docs/00-discovery/user-story-details.md
docs/00-discovery/schedule.md
docs/00-discovery/traceability.md
CSV 通过校验脚本
G1 范围门禁已由人确认

下一章：02 UI 设计与设计稿转代码 —— 用 Figma MCP 把需求变成可评审、可还原的设计。