SkillSpace/archives/dev-pipeline-universal/SKILL.md

name	description	version	date	author	metadata
dev-pipeline	通用研发流水线 — 从需求分析到功能上线的全流程 Agent 协作方案。定义角色、阶段、质量门禁、测试分层和流转规则。	1.0.0	2026-06-30	马总管 🐎	openclaw hermes emoji tags requires 🔧 研发流程 subagent 多模型协作 流水线 devops 质量门禁 测试分层 bins tags 研发流程 subagent 多模型协作 流水线 devops 质量门禁 测试分层

通用研发流水线（Dev Pipeline）

版本: v1.0.0（通用版） 创建日期: 2026-06-30 维护者: 马总管 🐎 适用平台: Hermes Agent / OpenClaw / 其他 AgentSkills 兼容平台

一、概述

组建一个完整的研发小单元，覆盖从需求分析到功能上线的全流程。由总管负责调度，通过 delegate_task / subagent 机制将各阶段任务分派给不同角色的子 Agent，每个角色使用最适合的模型。

流程总览

用户（提需求）
 │
 ▼
┌──────────────────────────────────────────────┐
│  ① 需求分析 — 总管                              │
│  理解业务意图，输出结构化需求文档，跟用户确认        │
└──────────┬───────────────────────────────────┘
           ▼ [QG1: 需求门禁]
┌──────────────────────────────────────────────┐
│  ② 技术方案 — 架构师                            │
│  读代码库 + 需求文档，输出设计方案                 │
│  总管 review 方案，必要时跟用户确认                │
└──────────┬───────────────────────────────────┘
           ▼ [QG2: 设计门禁]
┌──────────────────────────────────────────────┐
│  ③ UI设计 — 设计师                    (可选)   │
│  输出设计规范（配色/字体/间距/组件样式代码）         │
│  仅面向用户的项目需要，纯后端/API可跳过             │
└──────────┬───────────────────────────────────┘
           ▼
┌──────────────────────────────────────────────┐
│  ④ 编码实现（结对编程模式，可选）                  │
│  ④a 主程序员写代码                               │
│  ④b 结对程序员 review+改进                       │
│  大型/中型启用结对，小型/热修复单程序员             │
└──────────┬───────────────────────────────────┘
           ▼ [QG3: 编码门禁]
┌──────────────────────────────────────────────┐
│  ⑤ 代码审查 — 审查员                            │
│  Review 代码变更，输出结构化审查报告               │
│  ├─ REQUEST_CHANGES → 回到④让程序员修改          │
│  └─ APPROVED → 进入下一阶段                      │
└──────────┬───────────────────────────────────┘
           ▼
┌──────────────────────────────────────────────┐
│  ⑥ 测试验证 — 测试员                            │
│  分层编写测试（单元+集成+冒烟）并执行              │
│  ├─ PARTIAL_FAIL → 回到④让程序员修复             │
│  └─ ALL_PASS → 进入下一阶段                      │
└──────────┬───────────────────────────────────┘
           ▼ [QG4: 测试门禁]
┌──────────────────────────────────────────────┐
│  ⑦ 部署上线 — 总管                              │
│  构建、部署、验证，汇报结果给用户                   │
└──────────────────────────────────────────────┘

角色定义

角色	代号	流程阶段	推荐模型类型
🧑‍💼 总管	PM	①需求分析 ⑦部署上线	快速响应模型（日常对话）
🏗️ 架构师	ARCH	②技术方案	强推理模型（复杂推理）
🎨 设计师	UI	③UI设计	编码版模型（设计+编码）
💻 主程序员	DEV	④编码实现	深度推理编码模型
👥 结对程序员	DEV2	④编码实现(review)	与主程序员不同家族模型
🔍 审查员	REVIEW	⑤代码审查	深度推理模型
🧪 测试员	QA	⑥测试验证	Agent/Tool 能力强的模型

模型选择原则：

• 编码/审查/测试使用不同模型家族，消除单模型偏见
• 主程序员和结对程序员用不同厂商模型，交叉审视
• 测试员与编码员信息隔离（测试员不看实现思路）

流程裁剪规则

并非所有需求都必须走完全部阶段。由总管根据需求规模判断裁剪：

需求规模	定义	走哪些阶段	结对编程	示例
🔴 大型	新功能/新模块/架构变更	①②③④⑤⑥⑦ 全流程	✅ 启用	新增模块、系统重构
🟡 中型	现有功能扩展/较复杂 Bug	①④⑤⑥ 跳过②③设计	✅ 启用	加导出功能、修复复杂 Bug
🟡 中型(含UI)	现有功能扩展+UI改版	①③④⑤⑥ 跳过②方案设计	✅ 启用	界面改版、新增交互页面
🟢 小型	简单修改/配置变更	①④⑥ 最小流程	❌ 单程序员	改字段校验、加配置项
⚪ 微型	一行代码/纯配置	总管直接做，不 delegate	—	改文案、调参数
🔥 热修复	线上紧急 Bug	④⑥⑦ 跳过需求和审查	❌ 单程序员	线上崩溃、数据错误

裁剪原则：

• ①需求分析（总管）永远不跳过——再小的需求也要先确认理解对了（热修复除外）
• ⑤代码审查在中型以上需求中必须执行
• ⑥测试验证在有代码变更时必须执行（至少验证不破坏现有功能）
• 总管负责判断需求规模，有争议时向用户确认

项目目录规范（建议）

• 所有研发项目统一放在 ~/projects-dev/ 下（可自定义）
• 每个项目一个子目录，git 初始化管理
• 便于代码审查阶段做 diff 和回滚

二、质量门禁

详细规范见 references/quality-gates.md

门禁总览

门禁	位置	关键检查	通过条件
QG1	需求→设计	产物完整性、验收标准可测试、用户确认	全部通过
QG2	设计→编码	文件变更清单、API与需求对齐	无阻断问题
QG3	编码→审查	编译通过、lint通过、变更与设计一致	自检全通过
QG4	测试→部署	测试全通过、覆盖率达标、无回归、用户确认	全部通过

重试与超时机制

重试策略：

第1次失败 → 同模型重试，附带失败原因
第2次失败 → 换备用模型重试
第3次失败 → 上报用户，进入人工介入

超时保护：

阶段	超时时间	超时处理
②设计	30分钟	终止，记录已有产出，人工介入
③编码	50分钟	终止，保留已写代码，人工介入
④审查	25分钟	终止，标记"审查超时"，直接进测试
⑤测试	40分钟	终止，保留已有测试结果，人工介入

三、阶段产物规范

完整模板见 templates/stage-artifacts.md

每个阶段的子 Agent 必须输出结构化 YAML 产物。总管负责校验产物格式。

产物设计原则

1. 结构化优先：用 YAML Schema 约束，减少解析歧义
2. 摘要辅助：每个产物附带自然语言摘要，帮助 LLM 快速定位
3. 决策可追溯：记录关键决策的理由和替代方案
4. 问题前传：显式列出 open_issues，确保下游关注
5. 信息隔离：审查员不看编码 prompt，测试员不看实现思路

产物传递规则

① 需求产物 ──→ ②架构师（完整） + ④程序员（验收标准）
② 设计产物 ──→ ③设计师（页面/组件清单） + ④程序员（完整）+ ⑤审查员（摘要+文件清单）
③ UI设计产物 ──→ ④程序员（完整设计规范+组件样式）
④ 编码产物 ──→ ⑤审查员（git diff + 产物） + ⑥测试员（签名+验收标准）
⑤ 审查产物 ──→ ④程序员（如需修改：issues列表）
⑥ 测试产物 ──→ ④程序员（如有失败：failed_tests）/ ⑦总管（如全通过）

关键：测试员只接收接口签名和验收标准，不接收编码思路和实现 prompt。

四、测试分层策略

详细规范见 references/testing-strategy.md

测试金字塔

        ╱╲
       ╱ 冒烟 ╲         ← 5-10%
      ╱────────╲
     ╱  集成测试  ╲      ← 20-30%
    ╱──────────────╲
   ╱    单元测试     ╲   ← 60-70%
  ╱──────────────────╲

覆盖率阈值

项目规模	行覆盖	分支覆盖	函数覆盖
大型(新项目)	≥ 70%	≥ 60%	≥ 80%
中型(新功能)	≥ 60%	≥ 50%	≥ 75%
小型(bug修复)	修改行100%	—	—

五、各阶段执行规范

① 需求分析（总管直接执行）

输入: 用户的口头/文字需求 输出: 结构化需求产物（见 templates/stage-artifacts.md ①）

规则: 必须跟用户确认需求文档后才进入下一阶段。

② 技术方案（delegate → 架构师）

输入: 需求产物（完整） + 现有代码库上下文 输出: 结构化设计产物（见 templates/stage-artifacts.md ②）

规则: 总管 review 方案，重大决策需跟用户确认。

③ UI设计（delegate → 设计师）— 可选

适用条件: 面向用户的项目（H5、小程序、Web应用）。纯后端/API/CLI项目跳过此阶段。

输入: 需求产物 + 技术方案中的页面/组件清单 + 用户指定的风格偏好 输出: 结构化UI设计产物（见 templates/stage-artifacts.md ③）

设计产物包含:

1. 设计规范（Design Token）：配色、字体、间距、圆角、阴影
2. 组件样式清单：每个组件的具体 CSS/Tailwind 类名
3. 页面布局描述：各页面的结构和组件组合方式
4. 交互说明：关键交互的状态变化

规则:

• 设计师不需要画图，输出可直接使用的代码级设计规范
• 风格偏好由用户指定（如微信风格、Material Design 等）
• 设计规范以 Tailwind CSS 类名为主要表达方式

④ 编码实现（结对编程模式，可选）

模式: 主程序员写代码 → 结对程序员 review+改进 → 产出最终代码

④a 主程序员（delegate）

输入: 技术方案产物（完整） + UI设计产物（如有） + 需求产物中的验收标准 输出: 实现代码 + 结构化编码产物（见 templates/stage-artifacts.md ④）

④b 结对程序员（delegate）— 大型/中型项目启用

输入: 主程序员产出的代码（git diff） + 技术方案摘要 + 验收标准 输出: review 意见 + 改进后的代码

结对编程规则:

• 大型/中型项目：必须启用结对，主程序员写完 → 结对程序员 review+改进
• 小型/热修复：单主程序员即可，跳过④b
• 结对程序员的改动也会进入⑤代码审查，形成三道审视（结对→审查→测试）
• 结对程序员不重写代码，只做 review 和针对性改进

规则:

• 一次只实现一个功能点，避免大规模变更
• 单次 delegate 涉及文件 ≤ 10 个，超过则拆分
• 严禁在前台运行常驻进程（如 npm run dev），必须后台运行
• 完成后必须运行 git add -A && git commit

⑤ 代码审查（delegate → 审查员）

输入: 代码变更（git diff） + 需求摘要 + 技术方案摘要（不含编码 prompt） 输出: 结构化审查产物（见 templates/stage-artifacts.md ⑤）

审查维度（七维度）:

维度	严重级别	检查重点
安全性	🔴 阻断	SQL注入、XSS、硬编码密钥、路径遍历
正确性	🔴 阻断	逻辑错误、边界条件、空值处理、资源泄露
数据契约	🔴 阻断	前端 TS 接口与 API 实际返回字段一致性
性能	🟡 警告	算法复杂度、N+1查询、内存泄漏
可维护性	🟡 警告	函数长度、命名规范、DRY原则
规范	🟢 建议	代码风格、项目约定
测试	🟡 警告	测试覆盖、Mock合理性

规则: 审查不通过 → 问题反馈给程序员修改 → 修改后重新审查。最多 3 轮。

⑥ 测试验证（delegate → 测试员）

输入: 接口签名 + 验收标准（不含实现思路和编码 prompt） 输出: 测试代码 + 结构化测试产物（见 templates/stage-artifacts.md ⑥）

规则: 测试不通过 → 失败信息反馈给程序员修复 → 修复后重新测试。最多 3 轮。

⑦ 部署上线（总管直接执行）

输入: 通过审查和测试的代码 输出: 结构化部署产物（见 templates/stage-artifacts.md ⑦）

规则: 部署前跟用户确认。部署后验证核心功能。

六、设计理念与参考文献

核心设计理念

理念	来源	落地方式
SOP驱动+结构化输出	MetaGPT (arXiv:2308.00352)	7阶段YAML产物模板
测试与编码分离	AgentCoder (arXiv:2312.13010)	不同模型+信息隔离
多模型交叉审查	业界最佳实践	编码/审查/测试各用不同模型家族
Task级重试	CrewAI	每阶段 max 3 次+备用模型降级
事件流快照	OpenHands	git checkpoint 用于崩溃恢复
ACI精简工具	SWE-agent	子 agent 按需分配最小工具集

参考文献

1. MetaGPT — SOP驱动多角色协作，结构化中间产物减少30%信息损失
2. AgentCoder — 独立测试Agent比自测通过率高12-18%
3. ChatDev — 角色扮演对话提升20%完成率
4. SWE-bench — 60%修复失败源于定位错误，强调代码搜索能力
5. Agentless — 简单流水线有时比复杂Agent更有效

完整框架对比调研见 references/framework-comparison.md

七、实战陷阱与最佳实践

子 Agent 超时恢复模式

子 Agent 可能在执行过程中超时，但代码文件可能已经写入。超时后总管应执行以下恢复步骤：

1. 检查文件系统 — 查看已生成的文件
2. 检查 git 状态 — 确认子 Agent 是否已自动 commit
3. 验证后端 — 启动服务并测试 API 端点
4. 验证前端 — 确认构建通过
5. 修复关键问题 — 子 Agent 超时前可能来不及处理边界情况
6. 提交修复 — 完成收尾

超时不代表失败——子 Agent 可能完成了 80% 的工作，总管收尾比重新 delegate 更高效。

前后端数据契约不一致（高频致命问题）

程序员 Agent 同时写 API 和前端时，TypeScript 接口定义经常与 API 实际返回字段对不上，导致客户端 JS 崩溃。

防范措施：

1. 编码完成后，总管用 curl API 抓取实际响应
2. 对比前端 TypeScript 接口定义与 API 实际字段
3. 重点检查：字段名差异、字段是否存在、类型是否匹配
4. 对可能为 undefined 的字段，检查是否有安全访问（?.、|| 默认值）

常驻进程防护规则

子 Agent 禁止前台运行 npm run dev / next start / python -m http.server 等常驻命令，必须后台运行或设超时。违反此规则会导致整个 delegation 链路卡死。

代码修改必须提交后再通知构建

修改代码后，必须先 git status 确认已 staging、git log --oneline -1 确认已提交，再通知用户触发 CI/CD。本地工作区的修改不会自动进入远程仓库。

八、附带参考文档

本技能包附带以下参考文档，按通用性分类：

通用技术参考（适用于任何项目）

文档	内容
references/fastapi-pitfalls.md	FastAPI 实战陷阱（路由顺序、N+1、NULL处理等）
references/frontend-build-optimization.md	Vite 代码分割 + 路由懒加载优化
references/operation-log-pattern.md	操作日志系统四层架构模板
references/testing-strategy.md	测试分层策略详情
references/quality-gates.md	质量门禁详情
references/framework-comparison.md	AI 编码框架调研对比

业务模式参考（按需选用）

文档	适用场景
references/excel-data-import.md	从 Excel 批量导入业务数据
references/revenue-allocation-pattern.md	人×项目收益归属矩阵
references/doc-sync-pattern.md	里程碑文档同步到仓库

Changelog

版本	日期	变更内容
v1.0.0	2026-06-30	通用版首发。剥离环境特定信息（API key、服务器IP、具体项目名），保留通用流水线逻辑。适配 OpenClaw/Hermes 等多平台。