# 角色与用户故事

> 三类人 + 两类 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](agents-overview.html)。

A2

### 外部 Claude Code Session

从零拉起一份本仓库后，**只读本套文档**就能复现整个 DevLoop 系统。详见 [复现指南](plan-reproducibility.html)。

## 核心 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 新增 `
`，不重写旧 section
- 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 < 0.5 → 发 SSE `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](plan-reproducibility.html) |
| **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 后续验证 |