角色与用户故事
三类人 + 两类 Agent。每个故事卡都带：Who / When / What / Acceptance。Acceptance 字段会被 Tester Agent 直接转成 vitest 用例。
三类人类角色
P1 · Founder / Tech Lead
Yibo
下需求 + 决策 + 验收。每天 1-3 次用 DevLoop。要求快、要求 PRD 与代码同步、不接受 chat-only。
主要触达：L3 反馈、Sign-off、Sidebar 全部 8 个 Section
P2 · Reviewer
同事 / 投资人
偶尔进来看进度和最终产物。不写代码，只读 PRD + Dashboard。要求一目了然。
主要触达：Dashboard 头部、PRD diff、L2 集成结果
P3 · Future Maintainer
3 个月后的自己
回过头改某个 Unit 时，得能从 PRD / SDD 反推为什么这么设计。
主要触达：PRD history、SDD section 级 diff、coder.log
两类 Agent 「角色」
Agent 不是用户，但它们消费这套文档，列出来便于把约束写在该写的位置。
A1
本项目内的六个 Agent
消费 PRD/SDD/units.json/contract.json。详见 六个 Agent。
A2
外部 Claude Code Session
从零拉起一份本仓库后，只读本套文档就能复现整个 DevLoop 系统。详见 复现指南。
核心 User Stories
US-01 · Founder 启动新项目L3
As Yibo，I want 用一句中文描述需求就启动一个 DevLoop 项目，so that 我不用先想清楚再下达指令。
| 字段 | 内容 |
|---|---|
| Trigger | POST /api/devloop/projects 或 Dashboard 「+ NEW PROJECT」 |
| Inputs | { company_id, name, requirement: string } |
| Acceptance |
- 30 秒内 prd.html v1 落盘
- 60 秒内 sdd.html v1 + units.json 落盘
- SSE 立即推
prd.updated事件 |
US-02 · Founder 追加新需求L3
As Yibo，I want 在项目跑到一半时插话「再加 OAuth 登录」，so that 系统能识别这是增量而不是从头重做。
| Trigger | POST /api/devloop/projects/:pid/requirement |
| Acceptance |
- PRD 新增
- units.json diff 输出
{added, changed, removed}三类 - 已 passed 且 contract_hash 不变的 Unit 不被 reset |
US-03 · Reviewer 查看实时进度L3
As Reviewer，I want 打开 Dashboard 就看到「现在卡在哪一步」，so that 不必去翻日志。
| Trigger | GET /devloop/:pid（前端） |
| Acceptance |
- 顶部 3 张 Loop 状态卡 5 秒内更新
- DAG 节点颜色对应 unit.status
- 失败 Unit 红色 + 显示 retry 次数 |
US-04 · 系统自愈集成失败L2
As Yibo，I want 集成失败时系统先尝试自己修，不要每次都来问我，so that 我专注高价值决策。
| Trigger | Integrator 返回 ok=false |
| Acceptance |
- BugTriager 5 分钟内产 triage.json
- confidence ≥ 0.5 → 自动 patch SDD + reset Unit
- confidence human_intervention_needed
- 同项目每 PRD rev 最多自愈 3 轮 |
US-05 · Future Maintainer 反推决策L3
As 3 个月后的 Yibo，I want 看到 SDD 某个 Unit 的「为什么这么设计」，so that 不会重复犯老错。
| Trigger | 在 Dashboard 点开某 Unit 卡片 |
| Acceptance |
- 能看到该 Unit 在哪个 PRD rev 引入
- 能看到所有 retry 时的 coder.log + tester.hint
- 能看到所有相关 triage.json（如果被 reset 过） |
US-06 · 外部 Claude Code 复现项目A2
As 一个全新的 Claude Code session，I want 拿到本套 PRD + SDD HTML 就能从空仓库重建整套 DevLoop 代码，so that 系统具备真正的「文档驱动」性质。
| Trigger | 执行 复现 prompt |
| Acceptance |
- 5 个新 JS + 6 Agent 模板 + 1 Vue 全部生成
- SDD MVCP 四象限 100% 抽取覆盖
- 单测自动通过率 ≥ 80% |
故事优先级
| P | Story | 阶段 |
|---|---|---|
| P0 | US-01 · US-04 | P1 + P3 必须 |
| P1 | US-02 · US-03 | P3 / P4 必须 |
| P2 | US-05 | P4 应有 |
| P3 | US-06 | P4 后续验证 |