当 AI Agent 接管软件工程:一套开箱即用的研发工作流模板

从调研到设计，从拆解到编码，从验证到评审——让 GitHub Copilot 像一个有方法论的工程师一样交付。

一、你是不是也遇到过这些问题？

用 AI 写代码已经不稀奇了。但当你把一个真正的需求丢给 Copilot 或 Claude，经常会遇到这些情况：

• • 上来就写代码，没经过需求分析、没有设计文档、没有证据支撑
• • 范围越写越大，一个接口的修改牵连出三个服务的重构
• • 没有可追溯性，为什么这样设计、上下文从哪来、谁验证过——全靠记忆
• • 文档和代码脱节，改完代码忘了更新设计，设计里写的和实现的是两回事
• • 调试靠玄学，测试挂了就改代码，改完又挂，进入死循环

如果你踩过这些坑，那么今天介绍的这套 Agent-Based Workflow Template 可能正是你需要的。

二、它是什么？

这是一个仓库级的 AI 研发工作流模板。你可以把它复制到任何新项目中，配合 GitHub Copilot（也兼容 Claude Code）使用。

它的核心理念是：不要让 AI 自由发挥，而是给它一套完整的工程方法论。

具体来说，这个模板通过四类资产协同工作：

这四类资产不是孤立的——它们被组织到一个 12 阶段的交付生命周期 中，形成一条从”想法”到”可交付代码”的完整链路。

三、12 阶段交付生命周期

这套工作流把软件研发分为 12 个阶段。每个阶段都有对应的 Skill 模块和 Prompt（快捷入口），部分阶段还可以委派子 Agent 执行具体任务。

核心原则：每一步都有据可查，每一个交付切片一个 commit。

阶段速览

你会注意到，前 5 个阶段（调研→发现→澄清→证据→Spike）全都由同一个 discovery-workflow Skill 的不同模块承载；8–9 阶段由 planning-workflow 承载；10 阶段由 execution-workflow 承载。这种统一 Skill + 模块化拆分的架构，让每个阶段自成闭环，又共享通用的上下文管理和证据传递机制。

四、四类资产怎么配合工作？

用一个例子来说明。假设你要给系统增加一个”优惠券服务”：

Step 1：调研（Prompt → Skill → Agent）

你在 Copilot Chat 中输入斜杠命令 /Conduct Research，或直接描述：

“帮我调研主流电商平台的优惠券系统设计模式”

Copilot 加载 discovery-workflow 的 research 模块，按阶段执行：

1. 1. 明确调研边界
2. 2. 委派 Evidence Scout 子代理扫描仓库已有资料
3. 3. 系统性调研技术方案和行业实践
4. 4. 区分事实与推测
5. 5. 对比多方案，输出调研报告（使用 RESEARCH_FINDINGS_TEMPLATE.md）

Step 2：需求发现（Prompt → Skill）

你在 Copilot Chat 中输入斜杠命令 /Discover Requirements，或直接描述：

“基于刚才的优惠券调研报告，帮我提炼出需求文档”

Copilot 加载 discovery-workflow 的 requirements 模块，按阶段执行：

1. 1. 读取 Step 1 产出的调研报告，提取已确认事实
2. 2. 区分功能需求和非功能需求
3. 3. 为每条需求定义验收标准和归属边界
4. 4. 识别依赖和前置条件
5. 5. 输出需求文档（使用 REQUIREMENTS_DOCUMENT_TEMPLATE.md），包含需求清单、验收标准、优先级排序和待澄清项

Step 3：技术设计（Prompt → Skill → Agent）

你在 Copilot Chat 中输入斜杠命令 /Design Service，或直接描述：

“基于优惠券服务的需求文档，帮我做服务设计”

Copilot 加载 design-workflow 的 service-delivery 模块，按阶段执行：

1. 1. 读取需求文档，确认设计范围和约束
2. 2. 委派 Evidence Scout 子代理扫描仓库中已有的相关设计和参考资料
3. 3. 定义服务边界与职责划分
4. 4. 设计数据模型和存储方案
5. 5. 为每个 API 端点定义契约（请求/响应/校验规则/错误码）
6. 6. 识别未闭环项，记录到设计文档的 closure items 中
7. 7. 输出服务设计文档（使用 SERVICE_DESIGN_TEMPLATE.md），如需独立的 API 契约文档则同时产出 API_CONTRACT_TEMPLATE.md

Step 4：实施拆解（Prompt → Skill）

你在 Copilot Chat 中输入斜杠命令 /Break Down Implementation，或直接描述：

“把优惠券服务设计拆解成可执行的交付切片”

Copilot 加载 planning-workflow 的 feature-breakdown 模块，按阶段执行：

1. 1. 读取服务设计文档，识别所有可独立交付的功能单元
2. 2. 确定切片之间的依赖关系和执行顺序
3. 3. 为每个切片定义验证动作和通过信号
4. 4. 标注每个切片的前置条件和完成标志
5. 5. 输出功能拆解文档（使用 FEATURE_IMPLEMENTATION_BREAKDOWN_TEMPLATE.md），包含切片索引表：

Step 5：逐片执行（Prompt → Skill → Agent）

拆解完成后，有两种执行方式：

方式 A：逐片执行。 输入斜杠命令 /Run Slice，或直接描述：

“执行优惠券服务的切片 S1：领域模型与数据库迁移”

Copilot 加载 execution-workflow 的 implementation 模块，按阶段执行：

1. 1. 委派 Slice Boundary Auditor 子代理审计切片边界——确认前置条件已满足、范围没有越界、验证动作可执行
2. 2. 委派 Delivery Slice Executor 子代理执行实现——探索代码库、编写代码、运行验证
3. 3. 执行切片定义的验证动作（运行迁移脚本），确认通过信号（表结构正确创建）
4. 4. 如果验证失败，自动切换到 execution-workflow 的 debugging 模块，走根因分析流程
5. 5. 验证通过后，更新相关活跃文档，产出一个切片级的 git commit

方式 B：整体执行。 输入斜杠命令 /Run Plan，或直接描述：

“执行优惠券服务的完整实施计划”

Copilot 加载 execution-workflow 的 implementation 模块（plan 模式），按阶段执行：

1. 1. 读取功能拆解文档，确认所有切片的状态和依赖顺序
2. 2. 使用 execution-workflow 的 worktrees 模块，创建 Git worktree 隔离工作区
3. 3. 按顺序逐片执行——每个切片走与方式 A 相同的流程（审计 → 实现 → 验证 → commit）
4. 4. 每个切片完成后，记录执行日志，如遇阻塞自动切换到 debugging 模块
5. 5. 全部切片完成后，委派 E2E Acceptance Runner 子代理运行最终验收验证
6. 6. 合并 worktree 回主分支，产出完整的执行报告

关键约束：无论哪种方式，每次只执行一个切片，每个切片一个 commit，不跨界。

⚠️ 实践提示： 虽然模板生成的执行计划要求每个切片完成后单独提交，但 VS Code 等 agent 开发者工具的默认提示词可能包含”除非用户明确要求，否则不执行 git commit”的安全约束。这会导致计划中的自动提交步骤被静默跳过。如果你需要每个切片完成后都真正提交，请在输入中明确要求，例如：“执行切片 S1，完成后提交“ 或 “执行完整计划，每个切片完成后分别提交“。

五、7 个统一 Skill 和它们的模块

与许多 AI 工作流工具为每个任务独立定义一个 Skill 不同，这套模板采用了模块化 Skill 架构。7 个顶层 Skill 各自包含若干功能模块：

这种设计的好处是：同一领域的模块共享上下文传递、证据管理和错误处理逻辑，不需要在每个独立 Skill 中重复定义。

六、7 个专业子代理

这套系统内置了 7 个专业子代理（Agent），它们由 Skill 或 Prompt 协调调用，不直接面向用户：

这种 “父级协调 + 子代理执行” 的模式，让每个代理的职责边界清晰，避免了”一个 Agent 什么都干”导致的范围膨胀问题。

七、16 种文档模板

别小看模板——在 AI 驱动的研发流程里，模板是结构化输出的保障。没有模板，AI 生成的文档就是一堆自由散文。

这套工作流提供了 16 种模板，覆盖从调研到归档的完整生命周期：

前期阶段

• • RESEARCH_FINDINGS_TEMPLATE.md — 调研结果
• • ANALYSIS_DOCUMENT_TEMPLATE.md — 正式分析文档（业务分析、可行性分析、差距分析等）
• • REQUIREMENTS_DOCUMENT_TEMPLATE.md — 需求文档
• • REQUIREMENT_CLARIFICATION_TEMPLATE.md — 需求澄清

设计阶段

• • TECHNICAL_SPIKE_TEMPLATE.md — 技术 Spike
• • TECHNICAL_DESIGN_TEMPLATE.md — 技术设计（平台/基础设施/跨服务）
• • SERVICE_DESIGN_TEMPLATE.md — 服务设计
• • API_CONTRACT_TEMPLATE.md — API 接口契约
• • EVIDENCE_TRACEABILITY_TEMPLATE.md — 证据追踪矩阵
• • DECISION_RECORD_TEMPLATE.md — 决策记录（可在任意阶段产出）

实施阶段

• • IMPLEMENTATION_PLAN_TEMPLATE.md — 实施计划
• • FEATURE_IMPLEMENTATION_BREAKDOWN_TEMPLATE.md — 功能拆解
• • STAGE_DELIVERY_TASK_LIST_TEMPLATE.md — 阶段任务清单
• • TEST_BREAKDOWN_TEMPLATE.md — 测试拆解

维护阶段

• • DOC_MAINTENANCE_CHECKLIST.md — 文档维护检查清单
• • REFERENCE_DOCUMENT_TEMPLATE.md — 参考文档

八、跨阶段工程能力

除了 12 个阶段的主线流程，execution-workflow 还内置了 5 种跨阶段工程能力，可以叠加到任何主阶段上：

1. 系统性调试 execution-workflow (debugging)

当测试失败或行为异常时：

• • 不猜——先复现、收集证据
• • 确认失败的层和边界
• • 形成一个假设 → 用最小变更验证 → 确认根因 → 修复 → 回归验证

2. 测试驱动开发 execution-workflow (tdd)

改动涉及行为变更且有自动化测试工具时：

• • 先写最窄的失败测试
• • 确认它因正确原因失败
• • 实现最小代码变更
• • 测试通过后才重构

3. E2E 测试与验收 execution-workflow (e2e-acceptance)

需要运行完整测试套件并做验收决策时：

• • 自动发现测试基础设施 → 验证环境 → 按层级顺序执行测试
• • 分析并分类失败 → 自动修复可修复问题
• • 输出验收决策报告

4. 并行代理调度 execution-workflow (parallel-agents)

当两个以上任务互不依赖时，可以安全并行：

• • 不共享文件、分支状态、或切片依赖
• • 不在一个计划内并行执行有序切片

5. 隔离工作区 execution-workflow (worktrees)

大范围实施前，用 Git worktree 创建隔离环境：

• • 不干扰当前工作区
• • 实施完成后合并回主分支

九、可视化资产生成

除了工程流程管控，这套模板还内置了两个可视化资产生成 Skill，让文档和文章里的图表不再靠手画：

1. Mermaid 图表渲染 generate-mermaid-flowchart

需要在文档或文章中插入流程图、时序图、类图？这个 Skill 会：

• • 根据你的描述（或直接提供的 Mermaid 语法）生成 .mmd 源文件
• • 调用本地 mmdc CLI 渲染成 PNG 或 SVG
• • 自动将图片引用插入目标文档

支持的图表类型包括：flowchart、sequenceDiagram、classDiagram、stateDiagram、erDiagram、gantt、pie、mindmap 等。

前置条件： 安装 @mermaid-js/mermaid-cli（npm install -g @mermaid-js/mermaid-cli），或运行仓库内的 scripts/install-agent-dev-tools 脚本一键安装。

💡 如果目标平台原生支持 Mermaid 渲染（如 GitHub Markdown），直接用内联代码块即可，不需要渲染成图片。

2. AI 图片生成 generate-ai-image

需要公众号封面图、文章插图、或其他精美的视觉素材？这个 Skill 由调用方直接编写图片生成提示词，然后调用生成脚本产出最终图片。如需用 LLM 优化提示词，可通过 -OptimizePrompt 参数显式触发。

支持两种尺寸风格：

• • cover：1792×1024 横版，适合微信公众号封面（满足最低 900×383 要求）
• • illustration：1024×1024 方形，适合文章内插图

前置条件： 仓库根目录的 .env 文件中配置 openrouter_url 和 openrouter_key。

💡 AI 生成的图片中文字通常会变形，建议只描述视觉元素，避免让 AI 在图中写字。

十、工作流决策树

不知道从哪里开始？按照以下决策树判断：

广泛话题需要调研？              → discovery-workflow (research)
调研结果需要提炼需求？          → discovery-workflow (requirements)
范围不清楚？                    → discovery-workflow (clarification)
需要建立证据映射？              → discovery-workflow (evidence)
有技术不确定性？                → discovery-workflow (spike)
服务需要从证据推进到设计闭环？  → design-workflow (service-delivery)
下一步是技术设计？              → design-workflow (technical-design)
需要设计 API 接口契约？         → design-workflow (api-contract)
设计完了要做计划？              → Plan Implementation
计划有了要拆切片？              → planning-workflow (feature-breakdown)
需要独立的验证计划？            → planning-workflow (test-breakdown)
有切片等着执行？                → execution-workflow (implementation)
需要完整 E2E 测试和验收？       → execution-workflow (e2e-acceptance)
文档需要维护？                  → document-lifecycle-workflow
测试挂了，原因不明？            → execution-workflow (debugging)
需要测试先行的开发方式？        → execution-workflow (tdd)
互不依赖的任务要并行？          → execution-workflow (parallel-agents)
需要隔离工作区？                → execution-workflow (worktrees)
需要 Mermaid 图表渲染？         → generate-mermaid-flowchart
需要 AI 生成封面图或插图？      → generate-ai-image
审评反馈需要处理？              → Process Review Feedback
准备提交评审？                  → Request Code Review

完整决策树见 .github/workflow-decision-tree.md。

十一、快速上手

1. 克隆模板

把这个模板仓库复制到你的新项目中。

2. 安装开发工具（可选）

运行 scripts/install-agent-dev-tools.ps1（Windows）或 scripts/install-agent-dev-tools.sh（macOS/Linux），一键安装 Mermaid CLI 等依赖。

3. 定制三个文件

4. 创建第一份设计文档

docs/design/my-service.md  ← 用 SERVICE_DESIGN_TEMPLATE.md

5. 开始使用 Prompt

在 VS Code 的 Copilot Chat 中直接使用内置 Prompt，例如：

• • Conduct Research — 启动调研
• • Clarify Scope — 澄清需求
• • Draft Technical Design — 开始设计
• • Design Service — 设计一个后端服务
• • Break Down Implementation — 拆解切片
• • Run Slice — 执行一个切片
• • Run E2E Acceptance — 运行完整 E2E 测试并自动验收

十二、适合谁？

这个模板适合以下场景：

• • ✅ 需要 AI 协助研发流程治理的团队
• • ✅ 希望把调研、需求、设计、实现、验证串成统一闭环的项目
• • ✅ 需要通过文档驱动实现边界、契约和可追溯性
• • ✅ 想把 Prompt / Skill / Agent / Template 组织成稳定工程方法的团队
• • ✅ 已经在用 GitHub Copilot 但觉得”光写代码不够”的开发者

十三、设计哲学

这套工作流的核心信念可以总结为三句话：

1. AI 需要工程方法，而不仅仅是更好的 Prompt。

单个 Prompt 能解决点状问题，但解决不了系统性的工程复杂度。Skill、Agent、Template 的分层组合才能形成可持续的工程方法。

2. 先设计，后编码；先验证，后提交。

每一行代码都应该能追溯到一个设计决策，每一次提交都应该经过验证。这不是在限制 AI，而是在放大 AI 的工程价值。

3. 职责边界清晰，一次只做一件事。

子代理只做执行，不做决策。每个切片一个 commit。每个阶段有明确的输入和输出。这种约束看似笨拙，实际上是工程可控性的根本保障。

结语

AI 编程的瓶颈早已不是”AI 能不能写代码”，而是**”AI 写出的代码能不能融入一个可控、可追溯、可验证的工程体系”**。

这套 Agent-Based Workflow Template 给出了一个答案：把 AI 写代码当作工程交付来管理，为 AI 赋予工作流、为工作流配备专业代理、为代理提供结构化模板。

不是让 AI 更聪明，而是让 AI 更专业。

项目开源地址：https://github.com/LazyWorkshopCreate/agent-based-workflow 。欢迎在评论区分享你在 AI 驱动研发中遇到的挑战和实践。