为什么从OpenSpec切换到AIDLC？

梯形图转SCL | 博途AI辅助编程文档 | AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | PLC在线仿真器 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

到今年八月，我们团队用AI写代码已经半年多了。我最大的发现是，我们的开发速度上去了，但代码质量还是很粗糙。开发往往只需要半天，但找bug可能要花好几天。

所以最近我花了一个多月时间重构了团队的AI编码工作流。我用AIDLC工作流替代了OpenSpec，采用更详细的软件开发流程和更强的团队协作。代码质量终于大幅提升。

在今天的文章中，我想告诉你们我们是怎么做到的。

1、引言

AI编码已经存在一年多了。人们在这个领域的关注点已经慢慢从哪个模型更好、能提升多少效率，转向如何确保AI生成的代码真正高质量。

我最近注意到一件事。在社交媒体上，人们越来越多地讨论诸如"我如何真正确保AI编码输出具有高质量"和"谁应该为AI写的代码负责"这样的问题。

如果六个月前你问我，我会说这个问题的最佳答案是SDD（规范驱动开发）。基于SpecKit和OpenSpec等规则框架，你首先通过问答方式讨论，确定需求和实现规则。然后你将规范文件作为提示词提供给LLM，LLM严格遵循这些规范编写代码。这似乎是进行AI编码的最佳方式。

我甚至写了几篇关于使用OpenSpec技巧的文章。

直到我把我的方法推广到整个开发团队，我才意识到一些事情。SDD对于小项目效果很好。但一旦你的项目变大、跨越数年、需要跨多个团队协作，OpenSpec就撑不住了。

2、OpenSpec到底哪里出了问题

当我说它撑不住时，让我们看看像OpenSpec这样的SDD框架到底出了什么问题。

2.1 使用起来太复杂了

你还记得OpenSpec在GitHub文档中的多少命令吗？你知道什么时候用explore，什么时候用propose吗？

当我向团队推广OpenSpec时，我写了一整篇文档解释何时使用每个命令，并告诉每个人按照我制定的工作流程操作。

事情还是出了问题。explore应该在propose之前还是之后？为什么我不能直接跳到plan代理？我打赌你也回答不上来，对吧？

因为命令和它们的用例变得如此复杂，团队中每个人最终使用OpenSpec的方式都不同。有些人甚至一开始只是用OpenSpec装样子，之后就切换到纯氛围编码了。这表明额外的学习成本对开发者来说并不划算。

2.2 从未捕获原始意图

说到explore命令和plan代理之间的区别，这引出了另一个问题。OpenSpec编写的规范文件从未保存用户的原始意图或原始需求，也从未保留用户在plan阶段与AI进行的对话。

正因为如此，当我审查其他团队成员编写的规范文件时，我经常感到完全不知所措。这个用户故事为什么这样写？这个方法设计到底想解决什么问题？

时间一长，即使是编写代码的开发者也可能忘记为什么某个功能以某种方式设计。

一旦你失去原始意图，你的项目就会在每次迭代中离原始目标越来越远。

2.3 很难获得正确详细程度的需求

OpenSpec的explore模式，或其他SDD框架中的brainstorm模式，老实说相当强大。这可能会让你不知不觉地陷入基于愿望编码的陷阱。你开始希望一句话就够了，OpenSpec会和你聊天，一步步分解你的需求，然后逐渐为你构建一个完整的产品。

但AI目前还做不到。

当前这一代LLM非常擅长找捷径。如果你为项目描述一个模糊的目标，并期望OpenSpec将其分解为细粒度的需求和迭代，这很少能成功。你最终得到的只是一个具有主要功能的演示，其他什么都没有。所有详细的实现都缺失了，所以它实际上只是一个无法在生产系统中上线的半成品。

所以有经验的开发者知道，在做SDD开发时，最好的做法是将产品功能分解成小块，让OpenSpec一轮一轮地迭代。例如，第一轮构建项目骨架和技术栈，第二轮构建登录和认证系统，依此类推。只有这样，一个项目才能慢慢打磨成真正的产品。

但要控制这些需求分解的粒度真的很难。分解太粗，你的项目就变成了演示。分解太细，你的开发速度就会下降。有时开发者一开始甚至没有考虑到一些必要的功能，所以细节很容易被遗漏。

2.4 文档不再与现实匹配

接下来是文档一致性问题。你的团队成员首先使用OpenSpec编写规范文档，然后开始编码，边做边调整实现。但因为他们再也没有显式调用过OpenSpec命令，所以所有后续的调整都没有写回任何文档。

还有另一种情况。在生成规则工件时，你注意到tasks.md中的一个问题并修复了它，但除非你特别要求，否则AI不会主动去修改design.md。

随着项目在每次迭代中变得越来越大，这种不一致性到处都是。最终，规范文件完全失去了作为参考的价值。然后你最终得到一堆混乱的代码。

2.5 你永远不知道什么时候开始流程

我曾经问一个队友，为什么他们仍然选择氛围编码，尽管每个人都知道SDD可以提高代码质量。

他们给我的一个原因是，命令映射到开发阶段的方式太复杂了，他们真的不知道什么时候启动流程。

举个例子。

在你用apply完成编写代码后，你突然在生成的内容中发现了一个bug。你是让AI直接修复，还是先运行proposed工件流程？

或者假设你正在修复一个bug，突然有了一个好主意来调整一个现有功能，或者你只是想删除这段代码并以不同的方式重写。你是先运行OpenSpec流程，还是直接修改？

2.6 团队协作崩溃

每个像OpenSpec这样的开源框架都假设同样的事情。在AI的帮助下，我们每个人都变成了可以独自处理从头到尾所有事情的超级开发者。

但我们团队中的每个人都有明确的角色。现代业务已经变得足够复杂，以至于没有单个人能独自处理所有事情。

在你完成编写需求分析文档和用户故事后，你不应该和产品团队一起检查吗？至少，你需要就如何计算指标达成一致，对吧？架构设计和编码计划也是一样。你不应该让其他开发者或架构师审查这些文档吗？如果设计方法在某个地方有错误怎么办？

但OpenSpec框架完全忽略了这类问题。从你开始使用propose编写规范工件到你完成编码，整个工作流只发生在你自己的环境中。除非你主动展示，否则没有人会查看你写的文档。OpenSpec也使得插入质量门控或审查机制进行控制变得非常困难。

当然，即使是最好的框架也有一些缺陷。但像OpenSpec这样的SDD框架的问题使得它们在企业开发团队中更难成功。

3、我的解决方案

那么我是如何解决这一团糟的呢？

起初，我像AI时代的大多数程序员一样思考。自己造一个新的轮子，让AI在我的指导下编写全新的工作流程。

但我很快意识到这行不通。一个没有经过大量开发团队测试的新开发流程只会变成另一个AI玩具。它没有企业开发环境所需的可靠性。

所以我记起了六个月前关于亚马逊AWS AI编码工作流的一条新闻。

亚马逊似乎遇到了和我们同样的问题。他们不可靠的AI开发流程在生产环境中造成了灾难。所以他们要求初级或中级工程师编写的任何代码都必须由团队中的另一个角色批准。嗯，这与我们遇到的情况完全吻合。

我当时想，这个回应可能只是权宜之计。六个月过去了，他们一定已经想出了更系统、更工程化的解决方案。

经过一番挖掘，我找到了他们想出的解决方案：aidlc-workflows。

注意：亚马逊已经发布了aidlc-workflows的2.0版本，但本文仍然基于1.0版本并进行了一些自定义修改。我认为1.0版本足够轻量级且易于扩展，使用起来更方便。试试我在本文末尾分享的自定义版本。

4、什么是AIDLC

AIDLC代表AI驱动开发生命周期。它是一个对应传统SDLC（软件开发生命周期）的软件开发流程。

传统SDLC将企业级软件开发分为六个或七个主要阶段：规划、需求分析、设计、开发、测试、部署和维护。

AIDLC在这七个阶段的基础上增加了两个新功能：动态工作流和动态团队协作。

它是如何实现的呢？

首先，AIDLC不仅继承了SDLC的七个阶段。它还将这七个阶段分为三大阶段。

初始阶段处理工作区检测、条件子阶段和工作流规划。这个阶段回答什么和为什么的问题。

构建阶段处理设计、实现、构建和测试等子阶段。这个阶段回答如何的问题。

看起来是这样的。

看起来有很多子阶段要经历，但别担心。不是每个新需求都要经历所有阶段。如图所示，标记为绿色的始终运行，而标记为黄色的只有在满足某些条件时才运行。

决定哪些运行、哪些不运行的就是AIDLC所谓的动态工作流规划能力。

5、什么是动态工作流规划

当我们提出一个新的开发需求时，AIDLC的工作方式与传统SDD框架不同，后者是先聊天、再写文档、然后实现。根据当前项目环境和用户在对话过程中做出的选择，AIDLC会分支到不同的条件路径，每个分支加载不同的子工作流。复杂的项目加载更多的子工作流阶段，而小项目加载更简单的阶段。

举个例子。

AIDLC第一次加载时，它会检查当前项目环境是全新的（绿地）还是已存在的（棕地）。如果是现有环境，它会加载reverse-engineering工作流来分析现有代码已经做了什么。如果是全新环境，它会完全跳过reverse-engineering子工作流。

当我们提出一个新需求时，AIDLC会检查它是否影响产品的最终用户。如果是，它会加载user-stories工作流进行用户故事分析。如果你的需求只是一个非功能性需求，或者纯粹是前端页面开发任务，它会跳过user stories，直接进入下一个子阶段。

AIDLC还维护一个名为aidlc-state.md的文件。除了跟踪工作流当前处于哪个阶段外，这个文件还有另一个用途。如果你想进行基于愿望的开发，AIDLC会分解你的一句话需求，提取出最需要紧急处理的子需求，并启动该子需求的工作流。其他子需求被记录在aidlc-state.md中，等待下一轮工作流开始。这解决了需求粒度问题。

AIDLC的核心工作流就像一个始终留在对话中的管家。当你说的某些话或项目状态触发了某个条件时，管家会从柜子里取出匹配的子工作流文档，让该子流程接管。这样，你不需要记住什么时候使用哪个命令。管家会为你搞定。你不需要担心学习记不住的新命令，也不需要考虑什么时候启动流程。管家会处理所有这些。

6、什么是动态团队协作

AIDLC的动态团队协作有两个部分：需求分析日志记录和审批门控。

与主要将聊天历史保留在上下文中的传统问答对话不同，AIDLC会在子工作流需要时在流程中的任何时候启动对话并向开发者提问。开发者的每个问题和每个选择都会被记录到一个名为{current-phase}-questions.md的文件中。

在每个子阶段结束时，如果你想调整当前阶段的输出或有一些新的想法要分享，这些调整和AI的响应会被整理并保存到一个名为audit.md的文件中。这解决了原始意图从未被记录的问题。

在每个子阶段结束时，AIDLC会忠实记录你输入的内容、LLM的响应以及LLM如何总结该阶段的工作。然后工作流暂停并等待人工审查。

如果你是单独工作，你只需要检查所有文档看起来不错，然后回复"continue"。但如果你在团队中工作，需要另一个角色为你审查文档，你可以通过git提交代码并发送给你的队友审查。

你的队友的审查笔记和标记会被记录在audit.md中，然后发送回给你。你的AIDLC实例只有在看到当前阶段的批准标记后才会进入下一阶段。audit.md只支持增量更新，永远不会被编辑，所以你总是可以访问每个更改和每个审查记录。

AIDLC还允许你使用extensions文件夹扩展工作流。你可以设置哪些关键阶段需要哪些角色的审查，你可以设置每轮审查记录审查者的信息以供将来参考。所以，与OpenSpec相比，AIDLC更加重视团队协作。

好的，这涵盖了AIDLC能做什么的细节。我打赌你很想知道这在我们团队的实际开发中效果如何。

7、我们如何在团队中应用AIDLC

由于每个人关心的事情不同，介绍我的具体项目不会给你太多参考。所以在这一节中，我不会介绍具体项目。相反，我想根据我们团队开发的实际需要，带你了解我做的本地自定义。

为了使事情更容易使用，我已经将所有这些自定义重写为技能。你只需要在本文末尾获取源代码，将其放在正确的位置，然后让你的编码代理加载它。之后它会自动生效。

7.1 将AIDLC转变为技能

AIDLC的核心位于两个文件夹中。aws-aidlc-rules文件夹保存核心工作流定义，aws-aidlc-rule-details文件夹保存按需加载的子工作流文件。

默认情况下，它支持亚马逊自己的编码代理Kiro。对于其他常见的编码代理，官方网站给出的设置步骤太复杂了，没有人有耐心读完。

但从本质上讲，AIDLC确实只是由十几个Markdown文件组成。这意味着你完全可以将其转变为技能。

转换也非常简单。只需在.agents/skills下创建一个名为aidlc-workflows的文件夹，将aws-aidlc-rules/core-workflow.md复制到该文件夹中，并将其重命名为SKILL.md。然后，按照Agent技能规范，将aws-aidlc-rule-details中的每个文件复制到aidlc-workflows/references文件夹中。最后，让你的编码代理修复所有文件路径，使其指向正确的位置。

7.2 扩展AIDLC工作流

正如我之前提到的，AIDLC的工作流非常容易扩展。除了已经在reference文件夹下为现有inception、construction和operations阶段定制的子工作流外，它还支持extensions文件夹，允许你添加可选的自定义工作流，这些工作流会动态加载。测试、安全和弹性部署都属于这一类。

扩展工作流通常分为两个文件：核心工作流文件{workflow-name}.md，以及一个带有opt-in.md后缀的引导文件{workflow-name}.opt-in.md。

{workflow-name}.opt-in.md文件包含一个需要用户澄清的问题。该问题的答案决定了扩展工作流{workflow-name}.md适用于哪些阶段。

opt-in文件在需求分析阶段加载，根据用户的回答，它决定扩展工作流是否稍后加载。如果你的自定义扩展工作流只有{workflow-name}.md文件而没有opt-in文件，则该工作流始终加载。此机制确保多个扩展可以动态加载，因此你可以维护无限的扩展而不会使上下文爆炸。

好的，现在你了解了AIDLC的工作流扩展机制是如何工作的，让我带你了解我自定义的一些扩展。

7.3 保持文档一致性

此扩展要求AIDLC在每次发生代码更改时更新每个相关的工作流文档。这保持了文档与代码的一致性，因此你永远不会遇到SDD中代码更改但规范文档不同步的问题。

7.4 将批准与执行分离

在默认的AIDLC流程中，一旦你批准了某个阶段，工作流就会自动继续并运行。

如果你单独工作，这没问题，但当你需要审查同事的文档时，它就失效了。假设你是产品经理。你不能在需求文档获得批准的那一刻就让AI在你自己的计算机上生成代码，对吧？

所以我将"批准"的含义分为两个独立的操作：批准和继续。一旦你在某个阶段批准了文档，工作流不会自动进入下一步。相反，你应该将文档发送给负责下一阶段的人。一旦你的同事看到你批准了文档，他们说"continue"，然后工作流才会继续。

这种分离将批准和行动分开，确保不同的角色处理软件开发过程的不同阶段。它让每个队友的专长在最重要的地方发挥作用。

7.5 审计跟踪签署

此扩展解决了谁应该为AI写的代码负责的问题。

在默认流程中，AIDLC在audit.md中记录用户和AI之间的每一轮对话。这使得审计需求来源和跟踪每个阶段的审批历史变得容易。

但默认的audit.md文件从未记录谁提出了需求或更改，也从未记录谁批准了文档。当你的项目需要团队协作时，仅通过阅读audit.md的历史记录很难确定具体该和谁沟通。

所以我使用此扩展修改了audit.md，添加了两个键：User和Email。我使用git config user.name和git config user.email来填写这两个键。这样我总是知道每个历史记录属于谁。

7.6 使用question工具

AIDLC的原始版本是为Kiro构建的工作流模块，因此它与其他AI IDE的配合不是很好。它向用户提问的问题被写入一个名为{phase-name}-questions.md的文件中，并期望用户进入该文件回答并记录他们的响应。

但自从我开始使用AI IDE以来，我已经很久没有接触VS Code等传统编辑器了。我真的不想为了回答几个问题而打开整个IDE。那太麻烦了。

由于我主要使用OpenCode，我构建了一个扩展，让AIDLC在生成问题后直接使用OpenCode的question工具向用户提问，然后将用户的答案写回文档。这样，我永远不需要离开OpenCode去另一个IDE中编辑文件。

7.7 测试和其他最佳实践

接下来的几项是AIDLC中的默认扩展，不是我自己构建的，但我认为它们值得讨论。

为什么我们选择亚马逊的AIDLC而不是又一个开源SDD框架？除了这个工作流经过大型科技公司软件开发流程的测试外，我们还想通过AIDLC学习顶级科技公司的软件工程经验。

AIDLC确实做到了这一点。在extensions文件夹下，testing、security和resiliency子文件夹分别包含该公司在软件测试、安全以及持续集成和部署方面的最佳实践。

举个例子。

过去，当AI为我们编写单元测试时，它有时会更改源代码或稍后调整测试，只是为了让覆盖率数字看起来更好。基本上，AI编写了考试题目，然后更改自己的答案来欺骗指标。

但AIDLC的做法不同。它要求使用基于属性的测试（PBT）。PBT不是检查单个固定输入，而是随机生成大量输入条件，使代码很难提前"记住答案"。AI不知道下一个输入是什么，所以它无法调整代码来操纵测试。

对于很多初创团队来说，这些实践是日常工作中难以获得的宝贵经验。如果有机会，我建议开启相关选项并尝试一下。

8、结束语

这涵盖了我如何使用AIDLC重新设计我们团队的AI编码流程。

根据我们的使用情况，这个工作流确实效果很好。基本上没有学习曲线，你可以立即上手使用。

而且由于这来自一家大型科技公司的最佳实践，这个工作流非常重视动态工作流和动态团队协作。它非常方便根据团队开发流程的实际需要进行自定义。

它还使澄清每个团队成员在开发每个阶段的职责变得更容易。如果生产环境中出现问题，更容易追踪根本原因、找出谁负责并进行修复。

值得注意的一点是，这个工作流非常强调软件生命周期管理风格的开发。对话中需要澄清的问题也变得更加技术性。你可能需要学习更多的软件工程知识才能完全掌握这个工作流。但软件工程是每个开发者都应该学习的基础知识，所以我认为这不是什么大问题。

这个工作流给我们的团队带来了巨大的提升，无论是开发效率还是代码质量。所以我建议你自己试试。如果在这个过程中遇到任何问题，请给我留言，我会尽快回复。

原文链接：From OpenSpec to AIDLC: How I Improved My Team's AI Code Quality

汇智网翻译整理，转载请标明出处