| name | standard-team |
| description | 标准开发团队总指挥剧本（11 Phase 契约驱动 + 任务级 Dev-QA Loop）。当用户需要从需求到上线完整开发一个中型应用、说"用标准团队开发"、"完整开发新应用"、"按 11 Phase 跑"时激活。主会话作为调度者，按本剧本通过 Task 工具直接派遣 12 个成员 agent，不存在中间 orchestrator agent。 |
标准开发团队总指挥剧本
执行模型：本 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：初始化目录
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 报错后的处理（事中）
按以下顺序，不要跳步：
- 不要立即重派
ls 一遍 deliverables 清单中每个路径，分类：
- ✅ 已存在 = 上次中断前完成
- ❌ 不存在 = 缺失
- 抽查 1–2 个关键已存在文件（如入口、controller），Read 看一眼确认不是空文件或半截内容。Write 工具是原子的，正常情况文件都是完整的；但若 agent 死在 Edit 工具中间，被 Edit 的文件可能不完整，要警惕。
- 派一个同类型新 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次 |
| 任何重试超限 | 暂停 → 向用户报告卡点 | — |
人工介入检查点
以下节点完成后主动暂停，展示摘要等待用户"继续"：
- Phase 1 后：展示 PRD 功能列表（F01/F02...）
- Phase 2 后：展示 API 接口列表 + 数据库表结构
- 任意重试超限时：展示失败详情，等待用户决策
其余阶段自动执行，不打扰用户。
最终汇报格式
✅ 项目构建完成
📋 需求：[PRD 功能数量] 个功能，MVP 全部实现
🎨 设计：DESIGN_SYSTEM.md 已生成，[颜色/字体/间距] 规范已落地
🔌 接口：[已实现] / [契约定义总数] 个，全部通过 QA
🗄️ 数据库：[表数量] 张表
🔒 安全：[高危/中危/低危问题数]，高危问题已全部修复
🧪 QA：所有任务通过 testing-evidence-collector 验证
✅ 验收：reality-checker 判决 READY
📁 文档：README.md + API_DOC.md 已生成
⚠️ 遗留项：[若有跳过或降级处理的问题]
