# Standard Team

> 标准开发团队总指挥剧本（11 Phase 契约驱动 + 任务级 Dev-QA Loop）。当用户需要从需求到上线完整开发一个中型应用、说"用标准团队开发"、"完整开发新应用"、"按 11 Phase 跑"时激活。主会话作为调度者，按本剧本通过 Task 工具直接派遣 12 个成员 agent，不存在中间 orchestrator agent。 Use when this capability is needed.

- Skill: `tomevault-io/standard-team` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/standard-team`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/standard-team/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/standard-team

---


# 标准开发团队总指挥剧本

> **执行模型**：本 skill 是**主会话执行的剧本**，不是一个独立运行的 agent。
> 主会话读完本剧本后，用 `Task` 工具**直接**派遣 12 个成员 agent（按下方 Phase 0-11 顺序），可并行的并行。
>
> **为什么是 skill 不是 agent**：Claude Code 平台限制 —— subagent 不能 spawn 其他 subagent，Task 工具会被运行时强制剥离。所以"总指挥"必须由主会话亲自担任，剧本以 skill 形式装载。详见 `reference_subagent_nesting_proof.md`（5-8 沙箱实测铁证）。

---

# 角色定义

你（主会话）是总指挥，整合两种质量保障机制：
- **契约层**（事前）：强迫所有 agent 在动手前对齐接口和数据结构
- **Dev-QA Loop**（事中）：每个任务实现后立即由 EvidenceCollector 验证

你不写任何业务代码。你的职责是调度、传递契约、决策打回。
所有过程产出的 md 文件,都使用中文来描述

---

# 团队成员（全部来自标准团队 agents/）

## 规划层
| Agent | 来源文件 | 职责 |
|-------|---------|------|
| `product-manager` | product-manager.md | PRD、用户故事、MVP范围 |
| `software-architect` | software-architect.md | 技术选型、系统设计、契约生成 |

## 实现层
| Agent | 来源文件 | 职责 |
|-------|---------|------|
| `database-optimizer` | database-optimizer.md | Schema、migrations、索引 |
| `backend-architect` | backend-architect.md | API实现、业务逻辑 |
| `ui-designer` | ui-designer.md | 设计规范、颜色/字体/间距体系、组件视觉规范 |
| `frontend-developer` | frontend-developer.md | UI、组件、接口调用 |
| `devops-automator` | devops-automator.md | Docker、CI/CD、部署配置 |

## 质量层
| Agent | 来源文件 | 职责 |
|-------|---------|------|
| `testing-evidence-collector` | testing-evidence-collector.md | 任务级静态核查QA（typecheck/grep/单测，无浏览器/截图），PASS/FAIL决策 |
| `security-engineer` | security-engineer.md | 安全扫描 |
| `code-reviewer` | code-reviewer.md | 代码规范review |
| `reality-checker` | reality-checker.md | 最终上线前整体验收 |

## 文档层
| Agent | 来源文件 | 职责 |
|-------|---------|------|
| `technical-writer` | technical-writer.md | README、API文档 |

---

# 完整执行流程

---

## ► Audit 模式（已有代码审查）

> **触发方式**：用户说"审查 xxx 项目"、"audit xxx"、"检查现有代码"时进入此模式，不走 Phase 0–11。

### Audit-1：代码审查

**调用 `code-reviewer`**

```
输入：项目源码目录（用户指定，或默认当前工作目录）
重点检查（除常规项外，必须额外扫描）：

  Step 0 - 先侦察项目的部署方式：
    - 是否配置了子路径部署？（next.config basePath / vite.config base / nginx location 前缀）
    - 前端框架是什么？（Next.js / Vue / React / 其他）
    - 是否有服务端跳转逻辑？（middleware / proxy / 路由守卫 / 后端 redirect）
    → 根据侦察结果决定检查哪些文件和模式，不要假设文件名

  Step 1 - 若有子路径部署，检查所有跳转 / 重定向：
    - grep 关键词：redirect、router.push、router.replace、navigate、
      location.href、window.location、Response.redirect、NextResponse.redirect
    - 对每一处：目标路径是否正确携带了部署前缀？
      （框架路由方法通常自动补前缀；直接构造 URL 字符串时最容易丢失）

  Step 2 - 检查 API 请求路径是否硬编码：
    - grep：fetch('/api、axios.get('/api、axios.post('/api 等
    - 应使用环境变量前缀（VITE_API_BASE / NEXT_PUBLIC_BASE_PATH / 项目自定义变量）

  Step 3 - 常规 Blocker 项（安全、契约、错误处理等）

产出：docs/REVIEW_REPORT.md
```

### Audit-2：安全扫描

**调用 `security-engineer`**

```
输入：项目源码目录
产出：docs/SECURITY_REPORT.md
```

### Audit-3：验收检查（可选）

**仅当用户提供了需求文档 / PRD 时调用 `reality-checker`**

```
输入：需求描述 + 项目源码
额外验证：
  - 未登录访问受保护路由时，重定向 URL 前缀是否完整
  - 子路径部署下所有页面是否可正常访问
产出：READY / NEEDS WORK 判决 + 报告
```

### Audit 汇报格式

```
🔍 Audit 完成：{项目名}

🔴 必须修复（Blocker）：[n] 项
  - [具体问题 + 文件:行号]

🟡 建议修复：[n] 项
🔒 安全问题：[高危 n / 中危 n / 低危 n]
✅ 未发现问题的检查项：[列出]
```

**有 Blocker → 打回对应 agent 修复 → 重新 audit**
**无 Blocker → 汇报完成，等待用户指令**

---

## ► Phase 0：初始化目录

```bash
mkdir -p docs project-tasks
```

创建以下契约文件占位：
```
docs/
  PRD.md
  TECH_SPEC.md
  API_CONTRACT.md      ← 核心契约，前后端共同遵守
  DB_SCHEMA.md
  DESIGN_SYSTEM.md     ← UI 设计规范，frontend-developer 必须遵守
  DYNAMIC_CONTENT_MAP.md
  BACKEND_STATUS.md
  SECURITY_REPORT.md       ← Phase 7 安全审查报告
  REVIEW_REPORT.md         ← Phase 8 代码评审报告
  QA_REPORT.md             ← Phase 5/6 任务级 Dev-QA Loop 累计记录
  ACCEPTANCE_REPORT.md     ← Phase 10 最终验收报告
project-tasks/
  backend-tasklist.md
  frontend-tasklist.md
```

---

## ► Phase 1：需求分析

**调用 `product-manager`**

```
输入：用户原始需求
产出：docs/PRD.md

要求：
- 功能编号 F01/F02...（后续 agent 引用）
- 用户故事 Who/What/Why 格式
- 明确 MVP 范围（✅本期 / ❌不做）
- 非功能性需求（性能、安全、兼容性）

完成标志：docs/PRD.md 存在
```

**⏸ 人工检查点**：展示 PRD 功能列表，等待用户输入"继续"。

---

## ► Phase 2：技术架构 + 契约生成

**调用 `software-architect`**（这是整个流程最关键的阶段）

```
输入：读取 docs/PRD.md
产出：
  - docs/TECH_SPEC.md      技术栈、目录结构、环境变量、编码规范
  - docs/API_CONTRACT.md   ← 所有接口的完整定义（路径/方法/字段/错误码）
  - docs/DB_SCHEMA.md      所有表结构、字段类型、索引、外键关系

关键要求：
- API_CONTRACT 中每个接口必须包含：
    完整 Request body（字段名+类型+是否必填）
    完整 Response 200（字段名+类型+结构）
    所有错误码（HTTP状态码+error字段+触发条件）
- DB_SCHEMA 中每个字段必须标注类型、约束、索引原因
- 不得出现"等字段"、"其他参数"等模糊表述
- TECH_SPEC.md 必须包含"部署路径规范"章节，明确：
    APP_PATH（URL 前缀），VITE_API_BASE 的生产值和本地值
    前端 API 调用层规范（禁止硬编码 /api/...）
    .env / .env.production 的配置模板

完成标志：三个文件存在且无模糊表述，且 TECH_SPEC 包含部署路径规范
```

**⏸ 人工检查点**：展示 API 接口列表和表结构摘要，等待用户输入"继续"。

---

## ► Phase 2.5：UI 设计规范生成

**调用 `ui-designer`**

```
输入：
  - 读取 docs/PRD.md（了解产品定位和目标用户）
  - 读取 docs/TECH_SPEC.md（获取前端技术栈和适配方案）

产出:
  - docs/DESIGN_SYSTEM.md     颜色/字体/间距/圆角/阴影/组件规范
  - src/styles/variables.css  可直接引入的 CSS 变量文件

要求：
  - 颜色体系：品牌色 + 功能色 + 中性色，变量命名统一
  - 字体体系：基于实际适配方案（vw/rem）的字号梯度，最小不低于 16px
  - 间距体系：基于 4px 基础单位，覆盖页面边距/卡片内距/列表项高度
  - 组件规范：针对 PRD 中的核心组件（如：待办卡片/表单/按钮/空状态）
  - 移动端必须包含：安全区适配、可点击区域最小 44px、暗色模式变量

完成标志：docs/DESIGN_SYSTEM.md 和 src/styles/variables.css 均存在
```

---

## ► Phase 3：任务拆解

**由主会话亲自执行**（不调用子 agent）

读取 docs/API_CONTRACT.md 和 docs/DB_SCHEMA.md，生成：

**project-tasks/backend-tasklist.md**
```markdown
# 后端任务清单
> 基于 API_CONTRACT v1.0，每任务对应一个接口

### [ ] TASK-B01：实现 POST /api/v1/auth/login
- 对应契约：API_CONTRACT.md #auth-login
- 验收标准：返回 { token, user } 结构与契约一致

### [ ] TASK-B02：实现 GET /api/v1/users/:id
...
```

**project-tasks/frontend-tasklist.md**
```markdown
# 前端任务清单
> 每任务对应一个页面或核心组件

### [ ] TASK-F01：登录页面
- 调用契约：POST /api/v1/auth/login
- 验收标准：表单字段名与契约 Request 一致

### [ ] TASK-F02：用户详情页
...
```

---

## ► Phase 4：数据库实现

**调用 `database-optimizer`**

```
输入：读取 docs/DB_SCHEMA.md、docs/TECH_SPEC.md
产出：migrations/ 目录、model 文件、迁移运行器脚本、启动脚本

要求：
- 字段名严格与 DB_SCHEMA 一致，不得自行修改
- 若发现 Schema 有问题，写入 docs/DB_ISSUES.md 并停止
- 必须创建迁移运行基础设施（migrate.js/alembic stamp + start.sh）
  init.sql/init_db.py 只执行一次，生产环境表结构变更必须有独立迁移机制
- 不需要 Dev-QA Loop（纯结构性任务，无 UI 需要验证）

完成标志：
- migrations/ 存在，字段与 Schema 一致
- 迁移运行器脚本存在（scripts/migrate.js 或 alembic）
- 启动脚本存在（scripts/start.sh 或等价物）
```

若 docs/DB_ISSUES.md 存在 → 打回 `software-architect` 修正 DB_SCHEMA → 重试。

---

## ► Phase 5：后端实现（含任务级 Dev-QA Loop）

**逐任务执行以下循环：**

```
FOR 每个 project-tasks/backend-tasklist.md 中的 [ ] 任务：

  STEP 1 - 调用 backend-architect 实现该任务：
    输入：
      - 读取 docs/API_CONTRACT.md（必须第一步）
      - 读取 docs/DB_SCHEMA.md
      - 读取当前任务描述
    要求：
      - 严格按契约实现，路径/方法/字段名不得偏差
      - 若契约有歧义，写入 docs/BACKEND_STATUS.md 的 ISSUES 章节
    产出：该接口的实现代码

  STEP 2 - 调用 testing-evidence-collector 验证：
    输入：
      - 读取 docs/API_CONTRACT.md 中该接口定义
      - 扫描刚实现的代码文件
    验证内容：
      - 路径是否与契约一致
      - 返回字段名是否与契约一致
      - 错误处理是否覆盖契约中定义的状态码
    产出：
      - PASS 或 FAIL + 具体原因（返回主会话）
      - **追加写入 docs/QA_REPORT.md**（与 PRD/SECURITY/REVIEW 同级，累计记录所有任务级 QA 结果）

  STEP 3 - 决策：
    PASS → 将任务标记为 [x]，进入下一任务
    FAIL（重试 < 3）→ 将 QA 反馈传给 backend-architect，重新实现
    FAIL（重试 >= 3）→ 暂停，向用户报告卡点，等待介入

ALL 任务 PASS 后：
  检查 BACKEND_STATUS.md 的 ISSUES 章节
  若有未解决问题 → 打回 software-architect 更新契约 → 重跑受影响任务
```

---

## ► Phase 6：前端实现（含任务级 Dev-QA Loop）

**逐任务执行以下循环：**

```
FOR 每个 project-tasks/frontend-tasklist.md 中的 [ ] 任务：

  STEP 1 - 调用 frontend-developer 实现该任务：
    输入：
      - 读取 docs/API_CONTRACT.md（必须第一步）
      - 读取 docs/DESIGN_SYSTEM.md（必须第二步，所有样式数值来源）
      - 读取 docs/DYNAMIC_CONTENT_MAP.md（动态内容绑定规则）
      - 读取 docs/TECH_SPEC.md
      - 读取 docs/PRD.md（用户故事和UI需求）
      - 读取当前任务描述
    要求：
      - 所有 API 调用路径、字段名与契约完全一致
      - 所有颜色/字体/间距必须使用 DESIGN_SYSTEM 中定义的 CSS 变量
      - 不得硬编码任何颜色值、字号、间距值
      - 不得猜测接口结构

  STEP 2 - 调用 testing-evidence-collector 验证：
    验证内容（静态核查，不依赖浏览器/截图）：
      - UI 样式是否生效：CSS 静态核查（@media grep + viewport meta + 前端 typecheck）
      - API 调用字段名是否与契约一致
      - 表单提交和响应处理是否正确
      - 颜色/字体/间距是否使用了 CSS 变量（不得出现硬编码数值）
    产出：
      - PASS 或 FAIL + 可复核证据（typecheck/grep/单元测试输出，返回主会话）
      - **追加写入 docs/QA_REPORT.md**（与 PRD/SECURITY/REVIEW 同级，累计记录所有任务级 QA 结果）

  STEP 3 - 决策（同后端 Loop 规则）
```

---

## ► Phase 7：安全审查

**调用 `security-engineer`**

```
输入：扫描 src/ 目录
产出：docs/SECURITY_REPORT.md

重点检查：
- SQL 注入、XSS、CSRF
- 接口鉴权是否缺失
- 硬编码密码/密钥
- 文件上传未校验

完成标志：SECURITY_REPORT.md 存在
若发现高危问题 → 打回对应 agent 修复 → 重新扫描
```

---

## ► Phase 8：代码 Review

**调用 `code-reviewer`**

```
输入：git diff（或全量代码），读取 docs/TECH_SPEC.md（规范参考）
产出：docs/REVIEW_REPORT.md

检查项：代码规范、性能问题、可维护性、错误处理
若有 MUST FIX 级别问题 → 打回对应 agent → 重新 review
```

---

## ► Phase 9：DevOps 配置

**调用 `devops-automator`**

```
输入：读取 docs/TECH_SPEC.md（技术栈、环境变量、部署路径规范）
产出：Dockerfile、docker-compose.yml、CI/CD 配置

⚠️ 部署路径前缀检查（必须验证，不得跳过）：
  1. 确认 frontend/.env.production 存在且包含 VITE_API_BASE=/{APP_PATH}
  2. 确认 frontend/.env.production 包含 VITE_BASE_URL=/{APP_PATH}/
  3. 确认 vite.config.ts 中 base 使用环境变量（非硬编码）
  4. grep 扫描 frontend/src/ 确认无硬编码 /api/ 调用路径
  → 以上任意一项不满足，停止并报告问题，不得生成部署配置

完成标志：
  - 项目可通过 docker-compose up 启动
  - 部署路径前缀检查全部通过
```

---

## ► Phase 10：最终验收

**调用 `reality-checker`**

```
输入：
  - 读取 docs/API_CONTRACT.md
  - 读取 project-tasks/ 所有任务清单（验证全部 [x]）
  - 读取 docs/SECURITY_REPORT.md
  - 读取 docs/REVIEW_REPORT.md
  - 读取 docs/QA_REPORT.md（累计 QA 记录）
  - 运行完整用户旅程测试（端到端/接口契约测试证据，不依赖截图）

判决规则：
  - 默认判决：NEEDS WORK（必须有压倒性证据才能 READY）
  - READY 条件：
      ✅ 所有任务清单项均为 [x]
      ✅ 无未解决的安全高危问题
      ✅ 用户核心流程有端到端/接口测试通过记录
      ✅ API_CONTRACT 中所有接口均有测试通过记录

产出：
  - 判决摘要（返回主会话）
  - **写入 docs/ACCEPTANCE_REPORT.md**（与 PRD/SECURITY/REVIEW/QA 同级，覆盖式，每次验收刷新）

完成标志：
  - reality-checker 输出 READY
  - docs/ACCEPTANCE_REPORT.md 存在且判决为 READY
```

---

## ► Phase 11：文档

**调用 `technical-writer`**

```
输入：读取 docs/ 所有文件 + 项目源码结构
产出：
  - README.md（必须包含以下章节，缺一不可）：
      * 项目说明 + 技术栈
      * 本地开发启动方式
      * 环境变量说明表格
      * 首次部署步骤（创建目录、写 .env、配置 nginx location、触发 Actions）
      * 代码更新后再次部署流程
      * 数据库迁移使用说明（如何新增迁移文件、命名规范）
      * 项目目录结构
  - docs/API_DOC.md（基于 API_CONTRACT 的可读版文档）
```

---

# Subagent 中断与续传机制

## 背景

Subagent 执行长任务时可能撞到平台错误（502 upstream unreachable、context length exceeded、max turns 等），导致 agent 状态丢失并返回 error。但 agent 在死之前通过 Write/Edit 落盘的文件**仍保留在磁盘上**——Write 是原子的，文件要么完整要么不存在。

默认情况下，重新派遣同一类 subagent 不会"知道"这些残留文件，会按 prompt 从零开始，可能覆盖之前的工作。本机制要求主会话在派遣长任务前明示 deliverables，遇到中断时先做差异比对再续传。

## 触发条件

Subagent 返回的不是"任务完成"，而是以下任一：
- 平台错误：`API Error: 502`、`upstream unreachable`、`network` 等
- 资源耗尽：`context length exceeded`、`max turns exceeded`、`prompt is too long`
- Agent 中途汇报："我需要确认"、"遇到 X 问题请指示"

⚠️ 这与下方"打回重试总规则"区分——后者处理"agent 完成但 QA FAIL"，本机制处理"agent 根本没完成"。

## 派遣长任务前的标准动作（事前）

派 Phase 4 / 5 / 6 / 7 / 10 这种长任务 agent 时，prompt 必须包含一段 **deliverables 清单**：

```
预期产出文件（如已部分存在，是上次中断遗留，请勿覆盖；只补齐缺失项）：
  - backend/src/app.js
  - backend/src/routes/auth.js
  - backend/src/controllers/auth.js
  - ...
```

这份清单主会话自己也要记下来（写进 task 描述或临时变量），中断时要用。

## Subagent 报错后的处理（事中）

按以下顺序，**不要跳步**：

1. **不要立即重派**
2. **`ls` 一遍 deliverables 清单中每个路径**，分类：
   - ✅ 已存在 = 上次中断前完成
   - ❌ 不存在 = 缺失
3. **抽查 1–2 个关键已存在文件**（如入口、controller），Read 看一眼确认不是空文件或半截内容。Write 工具是原子的，正常情况文件都是完整的；但若 agent 死在 Edit 工具中间，被 Edit 的文件可能不完整，要警惕。
4. **派一个同类型新 agent**，prompt 必须包含续传说明：
   ```
   ⚠️ 这是续传任务
   上次同任务执行时在第 N 个工具调用后中断（原因：{原始 error}）。
   以下文件已写完并经过验证，请勿重写、勿修改、勿删除：
     - {file1}
     - {file2}
     - ...
   只需完成以下缺失项：
     - {missing1}
     - {missing2}
   实施前可 Read 上面已存在文件了解上下文，但绝对不要 Write/Edit 它们。
   完成后简短汇报本次新写入的文件列表。
   ```

## 续传次数上限

| 中断类型 | 最大续传次数 | 超限处理 |
|---------|------------|---------|
| 平台错误（502 / network） | 2 次 | 暂停 → 向用户报告 |
| Context/turns 耗尽 | 1 次续传，第 2 次必须降级（拆任务或换 sonnet/haiku） | 暂停 |
| Agent 主动中途汇报 | 不走续传，按下方"打回重试"规则改 prompt 后重派 | — |

## 反模式

- ❌ Agent 报错后立即原样重派 → agent 不知道有残留文件，可能覆盖
- ❌ `rm -rf` 残留目录从零开始 → 浪费已完成的工作
- ❌ Prompt 里只写"继续上次任务" → agent 没有上下文，仍是从零

---

# 打回重试总规则

> 本表处理 **agent 完成了但产出有问题**（QA FAIL、安全问题、review 不过等）。
> 若 agent 因平台错误 / 上游不可达 / 资源耗尽**根本没完成**，先走上方 §Subagent 中断与续传机制，不要走本表。

| 触发条件 | 打回目标 | 最大重试 |
|---------|---------|---------|
| DB_ISSUES.md 存在 | software-architect | 2次 |
| BACKEND_STATUS.md 有未解决 ISSUES | software-architect → backend-architect | 2次 |
| 任务级 QA FAIL（样式硬编码）| frontend-developer | 3次/任务 |
| **任务级 QA FAIL（API 路径硬编码，未使用 VITE_API_BASE）** | **frontend-developer（零容忍，必须修复）** | **3次/任务** |
| 任务级 QA FAIL（接口问题）| 对应实现 agent | 3次/任务 |
| **Phase 9 部署路径前缀检查 FAIL** | **frontend-developer → devops-automator 重新验证** | **2次** |
| 安全高危问题 | 对应实现 agent | 2次 |
| REVIEW MUST FIX | 对应实现 agent | 2次 |
| reality-checker NEEDS WORK | 对应 agent | 1次 |
| 任何重试超限 | 暂停 → 向用户报告卡点 | — |

---

# 人工介入检查点

以下节点完成后主动暂停，展示摘要等待用户"继续"：

1. **Phase 1 后**：展示 PRD 功能列表（F01/F02...）
2. **Phase 2 后**：展示 API 接口列表 + 数据库表结构
3. **任意重试超限时**：展示失败详情，等待用户决策

其余阶段自动执行，不打扰用户。

---

# 最终汇报格式

```
✅ 项目构建完成

📋 需求：[PRD 功能数量] 个功能，MVP 全部实现
🎨 设计：DESIGN_SYSTEM.md 已生成，[颜色/字体/间距] 规范已落地
🔌 接口：[已实现] / [契约定义总数] 个，全部通过 QA
🗄️  数据库：[表数量] 张表
🔒 安全：[高危/中危/低危问题数]，高危问题已全部修复
🧪 QA：所有任务通过 testing-evidence-collector 验证
✅ 验收：reality-checker 判决 READY
📁 文档：README.md + API_DOC.md 已生成

⚠️  遗留项：[若有跳过或降级处理的问题]
```

---
> Source: [xuanbingbingo/claude-standard-dev-team](https://github.com/xuanbingbingo/claude-standard-dev-team) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->