AI 代码生成的计划 - 执行 - 检查 - 行动框架

AI 代码生成工具承诺加快开发速度，但常常导致质量问题、集成问题和交付延迟。在本文中，我描述了一个结构化的计划-执行-检查-行动（PDCA）框架，用于人与 AI 的协作。在过去六个月中，我一直在完善这个框架，之前我与智能体在非结构化流程中工作了一年多。通过使用这个 PDCA 循环，我相信我可以在利用 AI 能力的同时更好地保持代码质量。通过工作协议、结构化提示和持续反思，我使用这种实践来确保我对提交的代码负责，同时指导 AI 产生经过测试、可维护的软件。

代码生成未能实现其潜力

AI 代码生成的快速采用增加了产出，但尚未在交付和结果方面定期实现可衡量的改进。谷歌的 DORA DevOps 2024报告得出结论，AI 采用率每增加 25%，交付稳定性就会下降 7.2%。这种差距可能是由于批大小的增加超出了组织定义、审查、测试、部署和维护输出的能力。

更令人不安的是质量问题的迹象。 GitClear在2024年对2.11亿行代码的分析（需要注册才能下载）揭示了重复代码块增加了 10 倍，在他们的调查中，重复代码首次超过了移动代码。除了要维护的代码数量激增之外，克隆代码的缺陷率为 17%（代码克隆重要吗？Wagner等人，2017年），这些缺陷中有 18.42%传播到了其他副本（通过代码克隆传播缺陷的实证研究，Mondal等人，2019年）。

为什么需要结构化的计划-执行-检查-行动（PDCA）循环？

由于人工智能工具及其使用方式都需要发展，该行业没有实现生产力的提高和质量的改进。工程师需要可重复的实践，利用他们的经验来指导智能体在利用现有代码模式的同时进行经过测试验证的更改。这种智能体的使用涉及引入结构化提示技术。

根据方法和任务复杂性，结构化提示比临时方法高出 1%至 74%，大语言模型中的提示工程系统调查：技术和应用（Sahoo等人，2024年）。

PDCA 通过一个经过验证的软件工程实践来提供结构，该实践结合了持续改进和迭代交付的原则，这些原则是我已经追求了 20 年的敏捷实践的基础原则。

一项对照研究，PDCA过程在软件质量持续改进中的应用（Ning等人，2010年），发现 PDCA 将软件缺陷减少了 61%。

PDCA 框架概述

下面是一个我为与编码智能体互动组装的结构化 PDCA 循环。我在我的团队用来计划、跟踪和接受工作的项目管理过程中单独使用这个过程。计划和检查步骤产生的工件，我将它们添加到 Jira 故事中，用于跟踪工作。这种实践创造了透明度和可解释性，并且开销很低。

这个 PDCA 循环最适合一到三小时的编码任务，但我也用它来将更大范围的工作分解成这种大小的单位。这种努力的长度既符合我的注意力跨度，也符合我使用的模型的上下文大小。

该框架由工作协议和结构化提示组成，引导人类/AI 协作完成循环的步骤。每一步都建立在前一步的基础上，行动步骤（反思）将持续改进纳入循环。

• 工作协议：这些协议是开发人员根据质量标准对智能体所做的承诺和指导。对于人工通读来说，这一步应该需要一分钟。

• 计划分析：指导智能体对业务目标进行项目范围的分析，以实现现有代码中的模式和解决问题的替代方法。这一步允许两到十分钟的人类/AI 交流，为项目跟踪提供工件。

• 计划任务分解：指导智能体概述它将遵循的步骤以实现业务目标。为智能体设置一条路径，以便输出更好地集中在当前目标上。这一步大约需要两分钟。

• 执行：在测试驱动的迭代循环中实施计划。提供实现指南，严格保护智能体如何构建专注于期望行为的代码，并通过单元测试进行验证。指导智能体使其推理对开发人员可见，提供干预和指导智能体的接入点。这一步的持续时间取决于工作范围，最好保持在三小时以下。

• 检查：要求智能体根据初始目标和实现指南验证代码实现、内部文档和自述文件。这一步为开发人员审查工作和为反思提供数据提供了帮助。这一步应该需要五分钟的人类/AI 互动，并为项目跟踪提供工件。

• 行动：通过从会议中学习并完善提示和人类/AI 的互动来持续改进。这一步骤应该需要两到十分钟的人/AI 互动。

这个框架中包含的具体提示已经通过实际编码会议使用所描述的回顾性过程来开发和完善。它们反映了一组特定的质量关注点，并通过与 Anthropic 模型家族的互动不断演变。它们是其他人适应自己的开发优先事项和首选 AI 工具的起点。我在git仓库中分享了我当前的工作协议和 PDCA 提示。

工作协议：AI 协作中的人类责任

工作协议是一种确立的做法，帮助团队提高一致性并维持代码质量，这种关注即使在个人工程师单独工作、为共享代码库贡献代码的背景下也直接适用。我将这种基于团队的方法适应于人-AI 协作，使用结构化协议来锚定互动中的人类责任。

在两年内与不同的生成式 AI 代码工具和演变模型合作中，我的工作协议声明了我认为维持 AI 辅助代码质量所必需的最小规范集。我的意图是通过指导智能体以较少的耦合、更好的一致性和减少代码重复来做出改变，从而创建小批量、连贯的提交和隔离的拉取请求。

这些协议包括原则（测试驱动开发（TDD）、增量变更和尊重已建立的架构）和示例干预问题：“首先失败的测试在哪里？”或“你在修复多个问题，请专注于一个失败的测试？”这些协议强化了我认为我需要的习惯，以便对 AI 生成的代码负责。

以下是我分析提示的摘录，以强制执行整个仓库的检查：

分析前所需交付物：

* 识别[两到三个]遵循类似模式的现有实现

* 记录已建立的架构层（哪些命名空间、哪些接口）

* 映射集成接触点（哪些现有方法需要修改）

* 列出已有的可用抽象（文件提供程序、接口、基类）

计划

计划由两个活动组成：高层次分析和详细规划。

高层次分析：解决业务问题

前期分析在开始代码生成之前，迫使明确业务问题和技术方法。这种做法对抗了 AI 在没有足够上下文的情况下实施的趋势倾向，这种趋势导致实施尝试失败、代码重复和不必要的回归。通过智能体自己的建议，进行迭代周期，我扩展了分析提示，以明确执行整个项目代码搜索，以寻找类似的实现、集成和配置模式。

我的分析提示要求对代码库进行搜索，以识别类似的代码模式、系统依赖项和现有的数据结构。它要求提供解决业务问题的替代方法。提示将输出限制在以“什么”和“为什么”为重点的人类可读分析上，而不是实现细节。

在进入“计划”步骤的下一部分之前，我经常会问一些澄清问题，并建议额外的背景。我将分析响应包含在我的 Jira 故事中，以记录我的方法。

以下是我的计划提示的介绍：

计划阶段。根据我们的分析，提供一个包含我们改进的连贯计划，该计划针对你的使用进行了优化，作为实现的上下文。

 

执行上下文。这个计划将按照 TDD 规程分步骤实施，并在人类监督下进行。每个步骤都标记了在同一线程上下文中的最佳选择模型。

详细规划：创建可观测和可测试的增量

一旦我同意了方法，详细规划提示要求智能体准备一个初始执行计划。这个计划将工作分解为一组原子的、可测试的检查表项，具有明确的停止/继续标准和透明度要求，以便我可以跟踪智能体正在做的事情。

大语言模型（LLM）在扩展的互动中，尤其是在需要架构一致性的已建立模式的大型代码库中，很难保持连贯的方向。详细规划提供了人类和 AI 之间的路线图和合同，促进了更具参与感和责任感的编码会议。

我的提示通过要求在任何代码更改之前进行失败测试来执行 TDD 原则，并在停止寻求帮助之前将尝试限制为三次迭代。它要求带编号的实施步骤，具有明确的接受标准和过程检查点。

我与智能体的互动鼓励它逐步按照计划进行。如果工作足够复杂，现实将迫使我偏离计划步骤。例如，我可能需要解决回归测试失败，或者意识到我误解或遗漏了某些内容，或者在工作过程中学到了一些改变方法的东西。在那时，我经常要求智能体从我们所在的位置重新计划，或者处理旁支任务，然后要求智能体从它最后完成的步骤返回计划。

执行：在人类监督下的测试驱动实现

实施提示强制执行 TDD 规则，同时允许将相关功能分组为并行变更批次，并同时进行测试验证。红绿重构原则解决了 AI 倾向于创建过于复杂的场景或完全跳过测试优先的问题。批量处理减少了推理成本，同时适应了 AI 在生成完整代码块方面的优势，而不是真正的红绿测试驱动所要求的仅足够变更。研究表明，结构化的 TDD 结合 AI 比无结构的编码方法取得了更好的成功率，但在整个过程中需要大量的人类指导（LLM4TDD：使用大语言模型进行测试驱动开发的的最佳实践，Piya & Sullivan，2023）。

我的实施提示包括了智能体和我都可以跟踪的检查表，强调行为测试失败而不是语法错误，以及实际组件而不是模拟。分步骤的过程可能比无结构的方法一开始就使用更多的词元，但允许更积极的人类监督和隔离且连贯的提交。我遵循智能体的推理，并在我看到我可以纠正的推理错误、我可以补充的上下文空白或上下文漂移时进行干预。上下文漂移的迹象包括偏离主题、重复代码或忽略既定模式。

以下是我实施提示中的 TDD 规则示例：

TDD 实现

* ❌ 不要测试接口——测试具体的实现

* ❌ 不要使用编译错误作为红色阶段——使用行为失败

* ✅ 要创建可以编译但行为失败的桩实现

* ✅ 尽可能使用实际组件而不是模拟组件

 

编译错误不是有效的红色。红色测试发生在调用不符合预期时。因此，这意味着项目可以编译，方法桩存在，但行为尚未完全实现。

检查：完成度分析

完成度分析要求智能体审查聊天会话记录和生成的代码，以确认变更产生预期的输出，并标记与原始计划和实施指南的偏差。这次审查创建了一个明确的完成定义，它超越了功能测试，包括过程依从性和架构一致性。

具体来说，审查确认所有测试都通过了，如果需要，复杂输出已通过端到端测试进行验证。智能体审查新代码以确保内部文档准确和良好的测试覆盖率。然后，它审计会话，看看我们是否解决了原始计划中的所有待办事项，以及我们是否始终遵循了测试优先的方法。这些结果以叙述形式和检查表的形式总结，并附有任何未完成事项的列表，以及对工作是否准备好关闭的结论。

这种输出加速了人类代码审查，并提供了开发者可以审查、纠正、补充并添加到工作跟踪系统的工件。结果还为最后一步，即回顾，提供了数据。

这是我的完整性提示：

完整性检查

根据我们的执行情况，回顾我们最初的目标结果和计划。

 

验证：

所有测试通过

完成手动测试（如果需要）

文档已更新

未引入回归

没有 TODO 实现剩余，由这次测试驱动创建

 

流程审计：

测试方法始终如一地遵循

维护 TDD 规程（如果选择）

测试覆盖率足够且适当

没有提交未经测试的实现

简单的测试场景是有效的

 

状态：[已完成/还需工作]

未完成事项：[任何剩余的任务]

准备结束：[是/否，附上理由]

行动：回顾以持续改进

回顾步骤分析会话，以突出合作模式，识别成功的人类干预，并建议改进提示和开发者使用工具的方法。通过回顾进行持续改进，通过系统地识别哪些人类干预和提示模式产生更好的结果，减轻了 AI 不一致的表现。

回顾提示要求智能体总结发生的事情，标记浪费的努力或错误路径，提出可以做得更好的事情，并建议我下次可以做出的最有价值的改变，以改进编码会话。我专注于我可以改变的提示语言、流程和行为，因为这些是我唯一可以控制以改善结果的杠杆。

以下是我回顾提示中评估点的一个示例：

关键时刻分析：

* 我们的方法对成功/失败影响最大的 2-3 个时刻是什么？

* 哪些具体决策或干预是改变游戏规则的？

 

技术与流程洞察：

* 在我们的合作中，什么模式对效率影响最大？

* 什么可以加速进展？

* 哪些流程元素运作良好，哪些需要改进？

衡量成功

持续改进超越了单独的 PDCA 循环，并从独立的质量度量中受益。GitHub 的 API 提供了一个钩子，用于创建早期预警系统。我有五个度量质量智能体的 git 操作：

• 大提交百分比：包含超过 100 行变更的提交，目标是少于 20%

• 庞大的提交百分比：触及超过 5 个文件的提交，目标是少于 20%

• 测试优先原则率：修改测试和生产文件的提交百分比，目标是大于 50%

• 每次提交平均变更文件数：目标是少于 5 个文件

• 每次提交平均变更行数：目标是少于 100 行

我的 git 动作可以在github上找到；我在拉取请求上运行一个操作，并且每 30 天在完整仓库上运行一次。

插图：PR 分析 github 操作的部分输出

对于对更复杂度量感兴趣的企业，有像 GitClear、DX 和 LinearB 这样的商业解决方案。。我对其中任何一个都没有直接的经验，但我正在试用 GitClear 的免费版本来评估结果。

实验结果

为了比较 PDCA 与非结构化方法，我在 Cursor 中使用不同的方法使用 Anthropic 模型实现了相同的故事。我收集了定量数据和定性度量：token 消耗、代码行数、主观开发者体验和代码质量评估。我使用这种方法来处理需要复杂系统交互的故事：

总体目标是使 @Tracer.cs 能够接受的类、方法或文件作为入口点，并基于在设置 json 中配置的 @TracerOption.cs，而不是运行基于 Rosaly 的代码路径跟踪来检查 kuzu 数据库以确定包含的 dll 是否已被分析，然后使用现有的 @KuzuDepedencyGraphReader.cs 和 @DatabaseDependencyGraphBuilder.cs 从 kuzu 检索子图作为 @ScoredOutputNodeGraph.cs，使结果图在功能上等同于通过基于方法和类的跟踪创建的映射图。

按活动分的 token 使用情况 非结构化

按活动分的 token 使用情况 PDCA

结果表明，前期规划成本与故障排除效率之间存在权衡。在非结构化会话中，80%的 token 在智能体声明任务完成后被消耗。这些额外的工作涉及故障排除实现：调试失败、解决不完整的实现和纠正对现有代码模式的假设。虽然我不认为这种级别的故障排除是典型的，但在处理复杂集成时，这种情况并不少见。

代码输出度量

PDCA 方法产生了更少的产品代码行、更全面的测试覆盖率和更多的原子提交。PDCA 中更高的文件计数反映了其对较小、专注变更的强调，而不是反映在离散的代码和测试文件中的广泛修改。虽然两种方法都获得了有效的解决方案，但非结构化方法在初始实现后需要更广泛的调试，而 PDCA 的测试驱动增量更早地捕获问题。

从定性上讲，PDCA 创造了更好的开发者体验。在 PDCA 中，人类互动贯穿于规划和编码过程中，而在非结构化方法中，互动堆积在最后，主要侧重于审查和故障排除。

我知道这些结果是基于一个单一的实验。我提出它们不是作为证据，而是作为支持我继续在我的实践中发展这种方法的方向性数据。

进一步发展的领域

我的协议、提示模板和成功的衡量标准都是相对较新的和不断发展的，就像 AI 工具的能力一样也在不断发展。以下是我目前关注的改进和实验学习领域：

将流程形式与任务复杂性相匹配

PDCA 框架的结构化方法提供了价值，但需要进行校准，以匹配所执行工作的复杂性和风险。规划提示需要大量的 token 使用，我希望试验轻量级的分析和计划步骤，以进行良好隔离的更改，例如实现已经存在具体示例的接口。在这种情况下，可能还有其他情况，现有代码提供了足够的上下文和模式供 AI 遵循，而无需广泛的前期分析。

在敏捷方法的发展初期，Alistair Cockburn 提出了 Crystal 方法（见幻灯片概述链接），在这种方法中，过程的严格程度应该随着项目的重要性和团队的规模而调整。这种方法建议为低复杂性场景开发规划和实施提示的非正式版本，同时仍然执行模式分析，确保足够的透明度，并进行回顾。

涉及架构决策、跨系统集成或新颖问题领域的复杂变更，将从更结构化的 PDCA 循环中受益。在分析和详细规划方面的前期投资可以防止当 AI 工具在没有足够上下文的情况下运行时出现的返工、回归和技术债的复合成本。

包括模型选择策略

结构化的分析和规划为根据任务复杂性切换模型选择来优化执行成本提供了机会。我已经开始在分析和规划中包括复杂度评估，并要求 AI 估计实施难度、模式清晰度和每个提出的解决方案的范围。然后，我要求它就我所选择的家族中的哪个模型在执行的每个点上提出建议（例如，在 Anthropic Claude 中使用 Sonnet 和 Haiku）。它形成建议的标准是有用的，但这些建议不是基于经验证据的，而且模型的实际行为比它的训练数据更近。在这种情况下，我也在等待 Anthropic 发布更新的小型模型，并会尝试其他家族的更小型模型。

初始分析和规划阶段需要更强大的模型来处理模糊的要求和架构推理。然而，遵循清晰规范的实施阶段可能有效地使用成本较低的模型，特别是当代码库包含强大的模式且变更范围良好时。人类参与循环过程的力量在于人类能够主动降级模型，并在它们挣扎时迅速介入。

结论

研究表明，由于质量退化和集成挑战，AI 代码生成没有实现其生产力潜力。PDCA 框架通过将结构应用于人类-AI 协作，更好地保持代码质量，同时利用 AI 能力，从而弥补了这一差距。

该框架提供了五个关键实践：通过分析和规划阶段的结构化目标设定，任务级规划以产生原子提交，红绿测试周期及早发现问题，验证检查点以确保完整性，以及微回顾以持续改进。实验结果表明存在核心权衡；PDCA 需要更多的前期规划投资，以减少故障排除和维护，提高开发人员体验。

采用 AI 代码生成的组织需要可扩展的系统实践，但允许个人偏好。PDCA 框架提供了结构，同时保持对不同上下文的适应性。随着 AI 能力的快速发展，对人类-AI 协作的规范方法对于可持续软件开发至关重要。

AI 披露

根据 InfoQ 对贡献者的 AI 政策，我使用了生成式 AI 工具（Claude）作为支持工具，同时保留了人类专业知识作为内容的驱动因素。具体来说，我使用 Claude 进行头脑风暴和构思，以制定我的初步大纲，反馈和魔鬼倡导者审查，以确定我的论点中的差距，并在多次修订中帮助起草以提高清晰度、流程和语法。本文中包含的提示示例是与 Claude 共同撰写的，代表了我工作中的实际提示。我亲自检索和审查了所有的研究资料，撰写了分析和框架，并做出了所有最终的内容决定。我对所有内容的准确性、原创性和质量承担全部责任，并在采用前请严格验证任何 AI 生成的建议。

原文链接：

https://www.infoq.com/articles/PDCA-AI-code-generation/