AI代码生成的PDCA框架实践指南

关键要点

• 将结构化目标设定循环应用于AI编码会话：运用计划-执行-检查-行动原则为每次会话设定明确、可观察的成功标准，并根据结果调整方向。
• 对AI使用结构化任务级规划：让代理分析代码库，并将大型功能分解为可在短迭代内完成的小型、可测试的代码块，以防止范围蔓延。
• 对AI代码生成应用红绿单元测试循环：让代理先编写失败的测试，然后编写通过测试的生产代码，创建一个结构化的反馈循环，以减少回归和意外后果。
• 建立验证检查点：执行“完成度分析”环节，在进入下一次迭代前，要求代理根据计划审查结果。
• 实施每日微型回顾：每次编码会话后，花五到十分钟与AI代理分析哪些做法有效，以及如何改进提示和互动。

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

代码生成尚未发挥其潜力

AI代码生成的快速采用正在增加产出，但尚未持续实现交付和成果方面的可衡量改进。某中心的DORA《2024年DevOps状况报告》得出结论，AI采用率每增加百分之二十五，交付稳定性就会下降7.2%。这种差距可能是由于增加的批处理规模超出了组织定义、审查、测试、部署和维护输出的能力。

更令人担忧的是质量问题的迹象。某机构对2.11亿行代码的分析显示，重复代码块增加了十倍，重复代码量首次超过了移动代码量。除了导致需要维护的代码量膨胀之外，克隆代码有百分之十七的缺陷率，并且其中18.42%的错误会传播到其他副本中。

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

行业尚未实现生产力和质量改进，因为AI工具及其使用方式都需要发展。工程师需要可重复的实践，利用他们的经验来指导代理进行经过测试验证的更改，同时利用现有的代码模式。这涉及引入结构化提示技术。

结构化提示在方法上优于临时方法，根据方法和任务复杂度的不同，优势在百分之一到百分之七十四之间。

PDCA通过一种经过验证的、包含持续改进和迭代交付原则的软件工程实践提供了结构，这些原则是过去二十年所追求的敏捷实践的基础。

一项对照研究发现，PDCA的应用使软件缺陷减少了百分之六十一。

PDCA框架概述

接下来是为与编码代理互动而制定的结构化PDCA循环。在团队用于规划、跟踪和接受工作的项目管理流程中，个人使用此流程。“计划”和“检查”步骤产生的工件会添加到用于跟踪工作的Jira故事中。这种做法以较低的开销创造了透明度和可解释性。

这个PDCA循环最适合一至三小时的编码任务，但也用它来将更大的工作范围分解为此类大小的单元。这种工作量既符合注意力持续时间，也符合所用模型的上下文长度。

该框架包括一个工作协议和结构化提示，引导人机协作完成循环的各个步骤。每个步骤都建立在前面的步骤之上，而“行动”步骤将持续改进融入循环。

• 工作协议：这些协议是开发者为按照质量标准参与和指导代理所做的承诺。人类阅读应只需一分钟。
• 规划分析：指示代理对要实现业务目标、代码中的现有模式以及解决问题的替代方法进行项目范围的分析。此步骤允许两到十分钟的人机交流，为项目跟踪提供一个工件。
• 规划任务分解：指示代理列出为实现业务目标将遵循的步骤。为代理设定路径，使其输出更专注于当前目标。此步骤应耗时约两分钟。
• 执行：以测试驱动的迭代周期实施计划。提供实施指南，为代理构建专注于期望行为并由单元测试验证的代码形成严格的约束。指示代理向开发者展示其推理过程，提供干预和指导代理的切入点。此步骤的持续时间取决于工作范围，最好控制在三小时以内。
• 检查：要求代理根据初始目标和实施指南，验证代码实现、内部文档和自述文本。此步骤有助于开发者审查工作，并为回顾提供数据。此步骤应进行五分钟的人机交互，并为项目跟踪提供一个工件。
• 行动：进行回顾，通过从会话中学习并改进提示和人机互动来持续改进。此步骤应进行两到十分钟的人机交互。

此框架中包含的具体提示是通过使用所述回顾过程的实际编码会话开发和完善的。它们反映了一组特定的质量关注点，并在与某模型的互动中不断发展。它们是他人适应自身开发优先级和偏好AI工具的起点。当前的工作协议和PDCA提示已共享在一个代码仓库中。

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

工作协议是帮助团队提高一致性和维持代码质量的成熟实践，这些关注点即使是在个体工程师单独工作、贡献于共享代码库的情况下也直接适用。已将这种基于团队的方法适应于人机协作，使用结构化协议来锚定互动中的人类责任。

在使用不同的生成式AI代码工具和不断演变的模型的两年中，工作协议声明了认为对于在AI辅助下保持代码质量至关重要的最低规范。其目的是通过指导代理进行耦合更少、内聚性更好、代码重复更少的更改，来创建小批处理量、连贯的提交和独立的拉取请求。

协议包括原则（测试驱动开发、增量更改和尊重既定架构）和示例干预问题：“先写失败测试在哪？”或“你在修复多个问题，专注于一个失败测试好吗？”。这些协议强化了认为需要保持对AI生成代码负责的习惯。

以下是分析提示的摘录，用于强制执行代码仓库范围的检查：

分析前的要求交付物：

• 识别[两到三个]遵循类似模式的现有实现
• 记录已建立的架构层（哪些命名空间，哪些接口）
• 映射集成接触点（哪些现有方法需要修改）
• 列出已有的抽象（文件提供程序、接口、基类）

计划

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

高层分析：解决业务问题
前期分析强制在开始代码生成之前明确具体的业务问题和技术方法。这种做法对抗了AI倾向于在没有足够上下文的情况下进行实施，从而导致实施尝试失败、代码重复和不必要的回归。通过在代理自身建议下的迭代循环，扩展了分析提示，明确强制执行项目范围的代码搜索，以查找类似的实现、集成和配置模式。

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

在进入“计划”步骤的下一部分之前，通常会提出澄清问题并提供额外的上下文。将分析响应包含在Jira故事中以记录方法。

以下是规划提示的介绍：

规划阶段。 基于我们的分析，提供一个连贯的计划，纳入我们的改进，并针对您作为实施上下文的使用进行优化。
执行上下文。 该计划将按照TDD规范分步骤实施，并在人工监督下进行。每个步骤都标记了在同一线程上下文内的最佳模型选择。

详细规划：创建可观察和可测试的增量
一旦就方法达成一致，详细规划提示会要求代理准备一个初始执行计划。该计划将工作分解为一组原子化、可测试的清单项目，具有明确的停止/继续标准以及透明度要求，以便能够遵循代理的操作。

大语言模型在长时间互动中难以保持连贯的方向，特别是在具有既定模式、需要架构一致性的大型代码库中。详细规划提供了路线图和人机之间的契约，促进更投入和负责任的编码会话。

提示通过要求在任何代码更改之前进行失败测试来强制执行TDD规范，并将尝试限制在三次迭代，然后停止请求帮助。它强制要求带有明确验收标准和过程检查点的编号实施步骤。

与代理的互动鼓励它按计划逐步进行。如果工作足够复杂，现实将迫使我们偏离计划步骤。例如，可能需要解决回归测试失败，或者意识到误解或遗漏了某些内容，或者在工作过程中了解到改变方法的信息。此时，通常会要求代理从当前所在位置重新规划，或者处理完附带任务，然后要求代理从其完成的最后一步回到计划。

执行：具有人工监督的测试驱动实现

实施提示在允许将相关功能分组为并行更改批次并进行测试验证的同时强制执行TDD规范。红绿重构规范解决了AI倾向于创建过于复杂的场景或完全跳过测试优先的问题。批处理降低了推理成本，同时适应了AI在生成完整的工作代码块而非真正的红绿测试驱动所需的最小更改方面的优势。研究表明，使用AI的结构化TDD比非结构化编码方法能获得更好的成功率，但需要在整个过程中大量的人工指导。

实施提示包括代理和都可以跟踪的清单，强调行为测试失败而非语法错误，以及真实组件而非模拟。逐步过程可能比非结构化方法在一开始使用更多的标记，但允许更积极的人工监督和独立且连贯的提交。遵循代理的推理，并在看到可以纠正的推理错误、可以补充的上下文差距或上下文漂移时进行干预。上下文漂移的迹象包括偏离主题、重复代码或忽略既定模式。

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

TDD实施

• ❌ 不要测试接口 - 测试具体实现
• ❌ 不要使用编译错误作为红阶段 - 使用行为失败
• ✅ 要创建能够编译但行为上失败的存根实现
• ✅ 尽可能使用真实组件而非模拟

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

检查：完成度分析

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

具体而言，审查确认所有测试都已通过，并且必要时通过端到端测试验证了复杂输出。代理审查新代码的准确内部文档和良好的测试覆盖率。然后，它审计会话以查看是否解决了原始计划中的所有待办事项，以及是否始终遵循了测试优先的方法。这些结果以叙述和清单形式总结，并附上任何未完成项目的列表，以及关于工作是否准备关闭的结论。

此输出加快了人工代码审查的速度，并提供了一个开发者可以审查、纠正、补充并添加到工作跟踪系统中的工件。结果也为最后一步——回顾——提供了数据。

以下是完整性提示：

完整性检查
根据我们的执行情况，审查我们最初的目标结果和计划。
验证：

• 所有测试通过
• 手动测试完成（如需要）
• 文档已更新
• 未引入回归
• 没有由此测试驱动创建的剩余待办实现
  过程审计：
• 测试方法得到一致遵循
• TDD规范得以保持
• 测试覆盖率充分且适当
• 没有未经测试的实现被提交
• 简单的测试场景有效
  状态：[完成/需要工作]
  未完成项目：[任何剩余任务]
  准备关闭：[是/否，附理由]

行动：为持续改进而回顾

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

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

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

关键时刻分析：

• 哪两到三个时刻中我们的方法对成功/失败影响最大？
• 哪些具体决策或干预是改变游戏规则的？

技术和过程洞察：

• 我们的协作模式中哪些对效率影响最大？
• 什么可以加速进展？
• 哪些过程要素运作良好，哪些需要改进？

衡量成功

持续改进不仅限于单个PDCA循环，还能从独立的质量衡量中受益。某中心的API为创建早期预警系统提供了钩子。使用git操作来测量五个质量代理指标：

• 大型提交百分比：包含超过一百行更改的提交，目标低于百分之二十
• 蔓延提交百分比：涉及超过五个文件的提交，目标低于百分之十
• 测试优先规范率：同时修改测试和生产文件的提交百分比，目标大于百分之五十
• 每次提交平均更改文件数：目标少于五个文件
• 每次提交平均更改行数：目标少于一百行

git操作可在github上获取；在拉取请求和每三十天对整个代码仓库运行一次操作。

插图：PR分析github操作的部分输出
对于有兴趣使用更复杂指标的企业，有商业解决方案可用，例如某机构、某中心和某机构。没有直接使用过任何这些工具的经验，但正在试用某机构的免费层级来评估结果。

实验结果

为了比较PDCA与非结构化方法，使用某中心的模型以不同方法实现了同一个故事。收集了定量数据和定性指标：标记消耗、代码行数、主观开发者体验和代码质量评估。对一个需要复杂系统交互的故事使用了这种方法：

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

按活动划分的标记使用量（非结构化）

活动	标记使用量
代码	264767
故障排除	1221217
总计	1485984

按活动划分的标记使用量（PDCA）

活动	标记使用量
分析	106587
详细计划	20068
执行	1191521
检查	6079
行动	7383
总计	1331638

结果表明了前期规划成本与故障排除效率之间的权衡。在非结构化会话中，百分之八十的标记是在代理宣布任务完成后花费的。这部分额外工作涉及对实现的故障排除：调试失败、解决不完整的实现以及纠正关于现有代码模式的假设。虽然不会将这种级别的故障排除描述为典型情况，但在处理复杂集成时并不少见。

代码输出指标

指标	非结构化	PDCA
生产代码行数	534	350
测试代码行数	759	984
实现的方法数	16	9
创建的类数	1	1
修改/创建的文件数	5	14

PDCA方法导致了更少的的生产代码行数、更全面的测试覆盖率和更原子化的提交。PDCA中较高的文件数量反映了其强调更小、更集中的更改，而不是体现在独立代码和测试文件中的广泛修改。虽然两种方法都实现了可行的解决方案，但非结构化方法在初始实施后需要进行更广泛的调试，而PDCA的测试驱动增量更早地发现了问题。

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

意识到这些结果基于单个实验。展示它们不是作为证据，而是作为方向性数据，支持继续在自己的实践中发展和改进这种方法。

有待进一步发展的领域

协议、提示模板和成功衡量标准相对较新，并且与AI工具本身的能力一样在不断演变。以下是当前细化和实验学习的重点领域：

使流程规范性与任务复杂度相匹配
PDCA框架的结构化方法提供了价值，但需要根据所执行工作的复杂性和风险进行调整。规划提示需要大量的标记使用，并正在寻求为隔离良好的更改（例如在已存在具体示例的情况下实现接口）尝试更轻量级的分析和规划步骤。在这种情况下以及其他潜在情况下，现有代码为AI遵循提供了足够的上下文和模式，无需广泛的前期分析。

在敏捷方法发展的早期，有人提出了某方法，即流程严格程度应随项目关键性和团队规模而扩展。这表明应为低复杂度场景制定不太正式的规划和实施提示版本，同时仍进行模式分析、强制执行足够的透明度和进行回顾。

涉及架构决策、跨系统集成或新颖问题领域的复杂更改受益于更结构化的PDCA循环。前期对分析和详细规划的投资，可以防止AI工具在没有足够上下文的情况下操作时产生的返工、回归和技术债务的复合成本。

纳入模型选择策略
结构化的分析和规划为基于任务复杂度优化执行成本提供了机会，通过切换模型选择来实现。已经开始在分析和规划中纳入复杂度评估，并要求AI估计实施难度、模式清晰度和每个提议解决方案的范围。然后要求它就执行过程中的每个点（例如，在某中心内使用某模型和某模型）推荐使用哪个模型。它形成推荐的标准是有用的，但推荐并非基于经验证据，而且模型的实际行为比其训练数据更新。在这种情况下，也在等待某中心发布更新的小模型，并将试验其他系列的小模型。

初始分析和规划阶段需要能力更强的模型来处理模糊的需求和架构推理。然而，在遵循明确规范的实施阶段，特别是在代码库包含强模式且更改范围明确的情况下，使用成本较低的模型可能同样有效。在人工参与的过程中解决这个问题的优势在于，人类能够主动降级模型，并在模型遇到困难时迅速干预。

结论

研究表明，由于质量下降和集成挑战，AI代码生成尚未发挥其生产力潜力。PDCA框架通过对人机协作应用结构来弥补这一差距，在更好地保持代码质量的同时利用AI能力。

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

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

AI披露

根据InfoQ对贡献者的AI政策，在保持人类专业知识作为内容主导的前提下，使用生成式AI工具作为支持工具。具体来说，使用某模型进行头脑风暴和构思以制定初始大纲，进行反馈和提出反对意见以识别论点中的不足，以及通过起草辅助来改善多次修订中的清晰度、流畅度和语法。本文中包含的提示示例是与某模型共同创作的，代表了实际工作中的真实提示。亲自检索和审查了所有研究来源，撰写了分析和框架，并做出了所有最终内容决策。对所有内容的准确性、原创性和质量承担全部责任，并在采纳任何AI生成的建议前进行了严格核实。
更多精彩内容 请关注我的个人公众号 公众号（办公AI智能小助手）或者 我的个人博客 https://blog.qife122.com/
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）