1. 项目概述：一个为AI Agent设计的专业开发工作流技能

最近在折腾一个叫OpenClaw的AI Agent开发平台，我发现一个挺有意思的现象：很多开发者（包括我自己）在让AI写代码时，常常会陷入“指令-生成-调试”的循环怪圈。你给AI一个模糊的需求，它给你生成一堆代码，然后你花大量时间去调试、重构，甚至重写。这个过程效率低下，而且代码质量参差不齐。

为了解决这个问题，我深入研究了 Cat-tj/dev-workflow 这个项目。它本质上不是一个独立的软件，而是一个为OpenClaw AI Agent设计的“技能包”。这个技能包的核心目标，是教会AI Agent如何像一个经验丰富的软件工程师一样去思考和执行开发任务。它强制AI遵循一套融合了“计划先行”、“测试驱动”和“子代理协同”的严谨工作流。

简单来说，这个工作流技能包就像给AI Agent配备了一位严格的“技术主管”。每当AI接到一个开发任务时，这位“主管”会先逼它停下来，别急着写代码，而是先想清楚：目标是什么？要分几步走？每一步具体改哪个文件？怎么验证？然后，在写每一行功能代码之前，必须先写好测试。对于复杂的、多步骤的任务，它还能学会“分身术”，派不同的“子代理”去并行处理独立模块，最后再进行严格的代码审查和合并。

这套方法特别适合处理那些非琐碎的、需要多步实现的特性开发，或者构建复杂的多模块项目。它把人类工程师在敏捷开发、极限编程中的最佳实践，封装成了AI可以理解和执行的标准化流程。接下来，我就结合自己实际集成和使用的经验，把这套工作流的精髓、实操细节以及我踩过的坑，给大家掰开揉碎了讲清楚。

2. 工作流核心三支柱解析

dev-workflow 技能的精髓在于它将三种成熟的软件开发范式进行了巧妙的融合与自动化。理解这三者的关系和各自扮演的角色，是有效使用它的前提。

2.1 写作计划：用蓝图取代即兴发挥

“写作计划”是整个工作流的起点，也是我认为最能体现其价值的部分。它的核心思想是 “谋定而后动” 。很多AI生成的代码之所以糟糕，根源在于需求模糊。一个模糊的指令（如“给用户系统加个角色权限功能”）会导致AI产生无数种可能的实现方式，结果往往南辕北辙。

这个阶段要求AI在动任何一行实现代码之前，必须产出结构化的计划文档。其步骤分解如下：

1. 定义目标 ：用一句话清晰描述“完成”的状态。这相当于产品的验收标准。例如，不是“优化性能”，而是“将用户列表API的响应时间从平均500ms降低到200ms以下”。
2. 列出任务 ：将宏大的目标拆解成可在30分钟内完成的“原子任务”。拆解能力直接决定了后续执行的效率和质量。一个“原子任务”的例子是：“在 UserService 类中，为 getUserList 方法添加数据库查询的索引提示。”
3. 指定文件 ：为每个任务明确关联到具体的文件路径。这强制AI进行依赖关系分析，避免天马行空的创造。它需要回答：“为了实现这个任务，我需要修改或创建哪几个文件？”
4. 排序任务 ：根据任务间的依赖关系确定执行顺序。没有依赖的任务可以被标记为可并行，这为后续使用子代理驱动开发奠定了基础。
5. 添加验证 ：为每个任务定义明确的验证方法。是写一个单元测试？是手动调用某个API并检查返回？还是运行一个性能基准测试？这确保了每个步骤都有明确的“完成”信号。

实操心得 ：我发现在让AI生成计划时，最需要警惕的是任务的“模糊性”。初期AI常会生成像“实现业务逻辑”这样的任务。这时，你需要引导它追问：“这个逻辑具体体现在哪个函数里？输入输出是什么？” 直到任务描述清晰到任何一个合格的开发者看到后，都能明确知道要写什么代码为止。计划的质量直接决定了整个项目的成败。

2.2 测试驱动开发：用失败测试指引正确方向

TDD是确保代码质量和正确性的基石。 dev-workflow 将经典的“红-绿-重构”循环内化为AI的强制动作。

• 红 ：首先编写一个描述期望行为的测试，并运行它。这个测试 必须失败 。如果它通过了，要么说明功能已经存在（那就不用开发了），要么说明你的测试写错了，没有检测到预期的行为。这个“失败”定义了我们的开发目标。
• 绿 ：编写 最简单 的、能让这个测试通过的代码。这里的关键是“最简单”。不要考虑扩展性、性能优化或代码美观。目的是用最小的代价让测试从红变绿，快速得到正向反馈。
• 重构 ：在测试保护网下，安全地改进代码。可以重命名变量、提取函数、消除重复，优化结构。每做一次小改动，就运行一次测试，确保它们始终是绿色的。

为什么这对AI特别重要？ AI在生成代码时，容易过度设计或引入无关逻辑。TDD的“最小实现”原则像一根缰绳，勒住了AI的“想象力”，让它聚焦于解决当前具体问题。同时，AI生成的测试用例本身，就是一份活的、可执行的文档，清晰地记录了该功能的设计意图和行为边界。

注意事项 ：要确保AI理解“测试行为，而非实现”。例如，测试应该断言“调用 calculateDiscount(100, ‘VIP’) 返回85”，而不是断言“ calculateDiscount 方法内部调用了 userRepository.getLevel() 三次”。后者会导致实现僵化，一旦重构内部逻辑，无关紧要的测试就会失败，形成维护负担。

2.3 子代理驱动开发：AI的“分而治之”之术

这是工作流中最具“智能感”的部分。当计划被拆解成多个独立任务后，主AI Agent可以像项目经理一样，动态地创建多个“子代理”来并行处理。

其工作流程是一个典型的监督式协作循环：

1. 任务解析与分发 ：主Agent分析计划，识别出可以并行执行的独立任务（通常是修改不同文件或模块的任务）。
2. 子代理孵化 ：为每个独立任务，主Agent通过 session_spawn 创建一个全新的、上下文纯净的子代理。这个子代理只接收与它任务相关的信息：任务描述、涉及的文件内容、验收标准。这种上下文隔离非常重要，可以防止任务间的干扰和“思维污染”。
3. 独立执行与提交 ：子代理在其隔离环境中完成任务，并提交更改。
4. 两阶段审查 ：主Agent扮演评审者角色，进行严格审查：
   • 阶段一：规范符合性审查 。提交的代码是否100%符合任务说明书的要求？有没有做多余的事情？有没有遗漏的要求？
   • 阶段二：代码质量审查 。代码是否整洁、可读？是否添加了恰当的测试并且通过？是否引入了新的编译警告或错误？是否符合项目的编码规范？
5. 反馈与合并 ：如果审查失败，主Agent会将具体的修改意见反馈给子代理，要求其修订。这是一个迭代过程。只有通过审查的代码才会被合并到主工作区。

核心价值 ：这种方法极大地提升了复杂项目的开发效率，并且通过严格的审查机制保障了代码质量。它模拟了人类团队中“开发-提交-代码评审-合并”的协作流程，使得AI能够处理远超单次对话上下文限制的大型项目。

3. 工作流选择与实战决策树

在实际使用中，并非所有任务都需要启动全套“计划-TDD-子代理”流程。机械地套用只会增加不必要的开销。 dev-workflow 内置了一个非常实用的决策逻辑，我将其细化成了下面的实战决策树，这能帮你和AI一起做出最高效的选择。

接到一个开发任务
│
├── 判断：这是一个10分钟内能解决的“快速修复”吗？（例如：修一个拼写错误、改个常量值）
│   │
│   ├── 是 → 采用“精简版TDD”流程。
│   │      1. 快速写一个测试（如果是逻辑修改）或直接查看变更。
│   │      2. 实施修改。
│   │      3. 运行相关测试集，确保无回归。
│   │      *跳过完整的计划阶段和子代理，避免杀鸡用牛刀。*
│   │
│   └── 否 → 进入下一级判断。
│
├── 判断：这是一个需要多步骤才能完成的“新特性”或“复杂修改”吗？
│   │
│   ├── 是 → **强制进入“写作计划”阶段**。产出详细计划后：
│   │      │
│   │      ├── 判断：计划中的任务是否彼此独立？（修改不同文件，无依赖）
│   │      │   │
│   │      │   ├── 是 → 启用 **子代理驱动开发**。主Agent创建子代理并行处理。
│   │      │   │
│   │      │   └── 否 → 采用 **顺序TDD**。主Agent自己按照任务顺序，对每个任务严格执行“红-绿-重构”循环。
│   │      │
│   │      └── 判断：单个任务是否非常复杂且隔离？（例如，实现一个独立的算法模块）
│   │          │
│   │          ├── 是 → 即使顺序执行，也考虑为该任务单独孵化一个子代理，保持上下文专注。
│   │          │
│   │          └── 否 → 顺序TDD即可。
│   │
│   └── 否 → 进入最后一种情况判断。
│
└── 判断：这是一个“Bug修复”吗？
    │
    ├── 是 → 建议先结合“系统化调试”技能。
    │      1. 定位Bug根本原因（例如，使用日志分析、单元测试复现、二分排查法）。
    │      2. 根本原因明确后，将其视为一个“开发任务”，再套用上述决策树（通常是快速修复或小型特性）。
    │
    └── 否 → 这可能是一个重构、文档更新等任务。可参考“多步骤特性”流程，但侧重设计和影响分析。

工具选型背后的逻辑 ：这个决策树的核心是 “效率与质量的平衡” 。子代理有创建、上下文加载、通信、审查的开销，对于小任务不划算。TDD的测试编写也有成本，但对于快速修复，如果项目本身测试覆盖率高，直接修改后跑一遍测试集可能更快。写作计划虽然看似耗时，但对于复杂任务，它能提前暴露设计缺陷和依赖问题，避免后期更大的返工成本，是典型的“磨刀不误砍柴工”。

4. 深度集成与配置实践

将 dev-workflow 技能安装到OpenClaw只是第一步，要让其发挥最大威力，需要根据你的项目和团队习惯进行深度集成和配置。以下是我在多个项目中总结的实践要点。

4.1 环境安装与技能激活

安装过程很简单，本质上是将技能文件复制到OpenClaw的技能目录下，使其能被Agent识别和调用。

# 假设你已经克隆了 Cat-tj/dev-workflow 仓库
# 将技能目录复制到OpenClaw的技能库中
cp -r /path/to/dev-workflow/ ~/.openclaw/workspace/skills/

# 确保你的OpenClaw Agent配置中，加载了dev-workflow技能
# 通常这需要在Agent的配置文件或初始化提示词中声明

关键配置点 ：

• 技能触发词 ：你需要明确告诉AI Agent，在什么情况下应该使用这个工作流。通常是在你的Agent系统提示词中加入：“当接到涉及代码编写、功能开发、bug修复或复杂项目构建的任务时，你应主动启用 dev-workflow 技能。”
• 上下文管理 ：确保你的OpenClaw环境有足够大的上下文窗口来处理计划文档、多个文件内容以及子代理之间的通信。对于大型项目，可能需要启用或优化其代码库的索引和检索功能，以便AI能准确获取“指定文件”的内容。

4.2 定制化计划与审查模板

项目自带的模板是一个很好的起点，但为了让它更贴合你的项目，强烈建议进行定制。

计划模板定制 ： 你可以修改 references/writing-plans.md 中的示例，或者创建你自己项目的专属模板。我会为我的项目添加以下字段：

• 数据库变更 ：如果任务涉及数据库，需明确是新建表、修改字段还是创建索引，并附上SQL迁移脚本草案。
• API契约 ：如果任务涉及API，需明确端点URL、请求/响应体格式（可以用JSON Schema示例）。
• 前端影响 ：对于全栈任务，需说明前端需要做的对应修改。
• 回滚方案 ：对于高风险变更，简要说明如果出现问题如何快速回滚。

审查清单强化 ： references/subagent-dev.md 中的审查清单是通用的。你应该根据项目技术栈加入更具体的检查项，例如：

• [ ] 对于JavaScript/TypeScript项目 ：ESLint检查通过，类型定义完整（无 any ）。
• [ ] 对于Python项目 ：通过 black 和 isort 格式化， mypy 类型检查无严重错误。
• [ ] 对于API修改 ：更新了对应的OpenAPI/Swagger文档。
• [ ] 对于数据库修改 ：提供了向前/向后兼容的迁移脚本。
• [ ] 性能影响 ：对于关键路径代码，是否进行了简单的性能考量或添加了基准测试？

4.3 与版本控制系统（如Git）的协作流程

一个理想的AI开发工作流应该与Git无缝集成。我设计的流程如下：

1. 分支策略 ：当AI开始一个基于计划的新特性开发时，它应该从主分支（如 main ）创建一个新的特性分支（如 feat/ai-add-user-role ）。
2. 原子提交 ：每个通过审查的“任务”或一组紧密关联的小任务，应该形成一个独立的Git提交。提交信息应规范化，例如： feat: add user role validation middleware [task-2] 。
3. 子代理与分支 ：在子代理驱动开发中，每个子代理可以在自己的临时分支上工作，完成并通过审查后，由主Agent将更改 cherry-pick 或合并到特性分支。这需要OpenClaw Agent具备操作Git的基本能力。
4. 最终合并 ：所有任务完成后，在特性分支上运行完整的测试套件，然后生成合并请求的描述（包含计划概要和测试结果），等待人类工程师进行最终复核和合并。

注意事项 ：目前这需要较高的Agent配置和自定义脚本支持。一个更简单的起步方案是：让AI在完成所有开发后，生成一份清晰的变更总结和手动应用Git命令的步骤说明，由开发者来执行Git操作。

5. 常见问题、排查技巧与效能提升

在实际使用中，你肯定会遇到各种问题。下面是我遇到的一些典型情况及其解决方案，以及如何让这套工作流更高效。

5.1 计划阶段常见问题

问题1：AI生成的计划过于空泛，任务拆解不到位。

• 现象 ：任务描述仍然是“实现用户管理模块”，没有具体文件和验证方法。
• 排查与解决 ：
  • 引导提问 ：向AI追问：“要实现这个模块，第一个必须完成的、最小的、可验证的子任务是什么？它具体修改哪个文件？”
  • 提供范例 ：直接给它看你项目中一个写得好的计划案例。
  • 设定约束 ：在指令中强调：“每个任务必须关联不超过2个具体文件，且验证方法必须可自动执行（如运行一个特定测试）。”

问题2：AI低估或高估了任务复杂度。

• 现象 ：一个任务被预估为15分钟，但实际上涉及复杂的第三方库集成，可能需要数小时。
• 解决 ：在计划阶段鼓励AI“标记风险和未知数”。如果AI识别出某个任务依赖它不熟悉的外部API或复杂逻辑，它应该在计划中将其标为“高风险”，并建议先做一个“技术调研”或“概念验证”的微型任务。

5.2 TDD与子代理阶段常见问题

问题3：测试通过了，但功能实际运行不正确。

• 现象 ：AI写的单元测试逻辑有误，或者Mock过度，导致测试绿了，但集成测试或手动测试失败。
• 排查 ：
  • 审查测试断言 ：检查测试是否真正验证了核心业务逻辑，而不仅仅是调用了某个方法。让AI解释测试用例的意图。
  • 运行集成测试 ：在子代理的代码合并后，主Agent应运行更广泛的集成测试套件，而不仅仅是单元测试。
  • 引入契约测试 ：对于模块间交互，可以指导AI编写基于接口契约的测试，而不仅仅是基于实现的测试。

问题4：子代理生成的代码与项目整体风格或架构不符。

• 现象 ：子代理完美完成了孤立任务，但引入了一个新的状态管理库，而项目使用的是另一个库。
• 解决 ：
  • 强化上下文 ：在孵化子代理时，除了任务文件，还应提供项目关键的架构文档、技术选型说明或 README 。
  • 完善审查清单 ：在代码质量审查阶段，明确加入“符合项目架构模式”和“使用统一的公共库/工具”等检查项。
  • 主Agent仲裁 ：对于技术选型等决策性问题，应由主Agent在计划阶段确定，子代理只负责执行，无权做架构级决策。

5.3 效能提升技巧

1. 建立项目知识库 ：将你项目的编码规范、API设计指南、常用工具函数说明等整理成文档，并让OpenClaw将其索引。这样，AI在规划和编码时能随时参考，大幅提升输出的合规性。
2. 迭代反馈循环 ：将每次AI开发过程中出现的问题（如计划不细、测试不全）记录下来，并转化为对系统提示词或技能模板的优化。这是一个持续训练和提升AI助手能力的过程。
3. 人类监督节点 ：对于非常关键或核心的模块，不要在完全自动化的模式下信任AI。可以在计划评审后、或核心代码合并前，设置“人工检查点”。让AI生成一份供人类Review的摘要，你快速过目后再让它继续。
4. 度量与优化 ：记录使用工作流后，完成同类任务的时间、代码评审通过率、Bug数量的变化。用数据来证明其价值，并发现流程中的瓶颈（例如，是否审查阶段耗时太长？），进而进行针对性优化。

这套 dev-workflow 技能的价值，不在于完全取代人类开发者，而在于将人类从繁琐、重复、模式化的编码劳动中解放出来，让我们能更专注于更高层次的架构设计、问题定义和创造性工作。它要求开发者从“写代码的工人”转变为“设计蓝图并管理AI执行的架构师”。这个转变本身，就是一次巨大的效能升级。刚开始集成时会觉得有些繁琐，但一旦习惯这种严谨的、计划驱动的开发节奏，你会发现项目的可控性和代码质量都会有质的提升。