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/）

规划层

实现层

质量层

文档层

完整执行流程

► 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：初始化目录

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

# 后端任务清单
> 基于 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

# 前端任务清单
> 每任务对应一个页面或核心组件

### [ ] 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 它们。
   完成后简短汇报本次新写入的文件列表。
   

续传次数上限

反模式

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

打回重试总规则

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

人工介入检查点

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

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 — distributed by TomeVault.