破局 AI 编码乱象：SDD 规范驱动 + OpenSpec+SuperPowers 双框架，让 AI 写对每一行可追溯代码

在AI编码助手飞速迭代的今天越来越多的开发者习惯把需求丢给AI看着屏幕上瞬间生成的几百行代码难免会产生一种“开发效率翻倍”的错觉。但只有真正上手落地才会发现“写代码”从来都不是软件开发中最难的环节写对代码、写出符合设计意图、覆盖所有场景且无冗余的代码才是困扰大多数团队的核心痛点。AI能快速响应需求输出代码却无法自动理解项目的设计边界、业务场景和技术规范更不会主动规避潜在的技术债。如果没有一套完善的规范驱动工作流来约束AI的行为所谓的“AI写代码”最终很可能变成“AI制造技术债”不仅无法提升效率反而会在后期维护中投入更多的时间和人力成本。这就是规范驱动开发SDDSpec-Driven Development应运而生的原因。它的核心逻辑很简单就是“先想清楚再动手”在让AI写代码之前先明确需求规范、设计标准和验收条件用规范文档约束AI的每一步行为再通过验证环节确保代码符合预期。今天我们就来详细拆解两个落地SDD理念的核心框架OpenSpec和Superpowers看看它们如何解决AI编码的“不规范”痛点以及如何在实际开发中灵活运用。一、先搞懂什么是规范驱动开发SDD在聊具体框架之前我们先厘清SDD的核心逻辑以及它和传统AI辅助编码的本质区别。很多开发者之所以用不好AI编码助手核心问题就在于没有建立“先规范后编码”的意识陷入了“需求→写代码→返工”的恶性循环。1.1 传统AI辅助编码的痛点传统的AI辅助编码流程非常简单粗暴大致可以分为四步用户模糊描述需求AI直接输出代码用户手动检查代码发现不符合预期后重新提交需求让AI改写。这个流程看似高效却存在三个致命问题。首先是需求传递偏差。用户对需求的描述往往是碎片化的比如“写一个后台服务启动检查功能”没有明确启动失败的处理逻辑、是否需要阻塞主程序、兼容哪些服务类型等细节。AI只能根据字面意思猜测输出的代码很可能偏离实际需求。其次是缺乏可追溯性。如果代码出现问题无法追溯到最初的设计意图不知道为什么要这么写也不知道当时的技术选型逻辑后期维护时只能逐行排查代码效率极低。最后是技术债积累。AI生成的代码可能存在冗余、不规范、兼容性差等问题一次两次的返工或许可以接受但长期下来这些不规范的代码会不断积累形成难以清理的技术债严重影响项目的可扩展性和稳定性。1.2 SDD的核心逻辑与优势SDD的思路完全颠覆了传统AI辅助编码的模式它把“规范”放在了编码之前形成了一套闭环工作流用户描述需求生成规范文档AI按规范实现代码最后按规范验证代码。整个流程的核心就是“用文档约束行为用验证确保正确”。相比于传统模式SDD有三个非常明显的优势。第一需求传递更精准。规范文档会把模糊的需求拆解成明确的目标、场景、验收条件AI只需严格按照文档执行就能减少需求偏差。第二开发过程可追溯。每一步变更都有规范文档支撑后期出现问题时能快速定位到设计环节找到问题根源。第三减少技术债。规范文档会明确代码标准、技术选型和测试要求AI生成的代码更规范后期维护成本大幅降低。简单来说SDD不是否定AI的效率而是用规范给AI“立规矩”让AI的高效发挥在正确的轨道上实现“高效且规范”的开发目标。而OpenSpec和Superpowers就是将SDD理念落地的两个核心工具它们虽然侧重点不同但都能有效解决AI编码不规范的问题。二、OpenSpec规格驱动的变更管理框架OpenSpec是一个结构化的开发工作流框架它的核心思想是“每次变更都有完整的设计文档可追溯”。需要注意的是它不是一个独立的工具而是一套可以嵌入在任何AI编码助手中的工作流规范通过简单的命令就能驱动整个开发流程尤其适合需要长期维护、注重变更追溯的项目。2.1 OpenSpec快速上手安装与初始化OpenSpec基于Node.js开发安装和初始化过程非常简单只需两步就能完成。首先是安装打开终端执行以下命令全局安装最新版本的OpenSpecnpminstall-gfission-ai/openspeclatest安装完成后进入你的项目目录执行初始化命令生成OpenSpec所需的基础目录结构cdyour-project openspec init初始化完成后项目根目录会生成一个名为“openspec”的文件夹里面包含了规范文档、变更记录等核心目录后续所有的规范编写和变更管理都将在这个文件夹中进行。2.2 核心概念Artifact链让每一步变更都可追溯OpenSpec的核心是一条“Artifact依赖链”所谓Artifact就是每一个环节生成的规范文档这些文档相互关联、层层细化形成了一套完整的变更追溯体系。这条依赖链的完整流程如下proposal.md → design.md → specs/*.md → tasks.md → 代码实现 → 归档这条链条上的每一个Artifact都有明确的职责缺一不可我们逐个拆解它们的核心作用。1proposal.md变更提案明确“为什么做”proposal.md是整个变更的起点核心作用是阐述“为什么要做这次变更”相当于变更的“立项报告”。它不需要太复杂的技术细节重点包含三个核心内容变更的原因、变更的目标与非目标、变更的影响范围。比如我们要做“启动时检查并拉起后台服务”的变更proposal.md中就需要明确当前后台服务可能存在未启动的情况导致核心功能无法正常使用这是变更的原因变更的目标是启动项目时自动检查服务状态未启动则自动拉起非目标是不改变服务本身的运行逻辑影响范围是项目启动流程、后台服务依赖模块不影响其他业务模块。2design.md设计决策明确“怎么做”有了提案之后就需要明确“怎么做”这就是design.md的核心作用。它主要记录技术方案的选择、替代方案的对比以及潜在的风险评估确保技术选型的合理性和可行性。还是以“启动时检查并拉起后台服务”为例design.md中需要明确选择复用项目中已有的ServiceUtils工具类减少代码冗余替代方案是重新编写检查逻辑对比后发现复用工具类更高效、更稳定潜在风险是ServiceUtils版本兼容问题解决方案是先验证工具类的可用性必要时进行版本适配。3specs/*.md需求规格明确“做成什么样”specs目录下的文件是整个规范的核心它明确了变更的具体需求和验收条件也是AI实现代码的主要依据。每个spec文件都采用“Requirements Scenarios”的格式其中Scenarios用“WHEN/THEN”的句式明确不同场景下的预期行为。比如针对后台服务启动检查的spec文件会包含4个核心场景WHEN后台服务未注册THEN提示服务未注册不执行拉起操作WHEN后台服务已运行THEN不执行任何操作输出服务正常提示WHEN后台服务未运行但已注册THEN自动拉起服务输出拉起成功提示WHEN服务拉起失败THEN输出失败提示不阻塞主程序启动。4tasks.md任务清单明确“分几步做”specs文件明确了“做成什么样”而tasks.md则将需求拆解成可执行的具体任务每个任务都是一个可勾选的checkbox确保AI能按步骤实现不遗漏任何细节。比如后台服务启动检查的tasks.md会拆解成3个核心任务第一步在项目启动入口添加服务检查逻辑调用ServiceUtils工具类第二步实现4个场景的判断逻辑对应specs中的场景要求第三步添加日志输出记录服务检查和拉起的结果。5代码实现与归档确保变更可追溯完成上述所有Artifact文档后就可以让AI按tasks.md中的任务逐步实现代码。代码实现完成后通过验证环节确认符合specs要求最后进行归档将所有Artifact文档和代码变更归档到指定目录形成完整的变更历史方便后续查询和追溯。2.3 OpenSpec工作流程用命令驱动全流程OpenSpec提供了一组简单的命令无需复杂操作就能驱动整个SDD流程从需求探索到变更归档每一步都有对应的命令支撑我们整理了常用命令的作用和说明方便大家快速查阅。命令作用说明/opsx:explore探索模式自由讨论需求、技术方案不写代码只聚焦于“为什么做”和“怎么做”/opsx:propose提案生成proposal.md并自动规划后续需要的所有Artifact文档/opsx:ff快速通道一次性生成所有Artifact文档适合简单需求节省时间/opsx:apply实现按照tasks.md中的任务逐一步骤实现代码每完成一个任务自动验证/opsx:verify验证对照所有Artifact文档检查代码是否符合规范和需求/opsx:archive归档将完成的变更所有Artifact文档代码归档形成可追溯的历史记录2.4 典型使用流程以“启动时检查并拉起后台服务”为例理论不如实践我们以“启动时检查并拉起UniCloudService后台服务”为例完整演示OpenSpec的使用流程让大家更直观地理解如何用它约束AI编码。第一步快速生成所有Artifact文档由于这个需求相对简单我们可以使用快速通道命令一次性生成所有规范文档。在AI编码助手中输入以下命令/opsx:ff 启动时检查并拉起 UniCloudService 后台服务执行命令后AI会自动在openspec/changes目录下生成一个活跃变更文件夹里面包含了4个核心Artifact文档proposal.md阐述为什么需要这个变更比如“当前UniCloudService可能存在未启动状态导致依赖该服务的功能无法正常使用需要在项目启动时自动检查并拉起提升系统稳定性”。design.md确定技术方案比如“复用项目中已有的ServiceUtils工具类调用其checkService和startService方法启动失败时不阻塞主程序仅输出日志提示替代方案为重新编写工具类对比后选择复用提升开发效率”。specs/unicloud-service-startup/spec.md明确4个核心场景覆盖未注册、已运行、未运行、启动失败四种情况每个场景都用WHEN/THEN句式描述预期行为。tasks.md拆解3个可执行任务每个任务都有明确的执行要求比如“任务1在项目启动入口src/index.js导入ServiceUtils添加服务检查触发逻辑任务2实现场景判断逻辑对应specs中的4个场景任务3添加日志输出记录检查结果和拉起状态”。第二步让AI按任务实现代码生成所有规范文档后输入以下命令让AI按tasks.md中的任务逐步实现代码/opsx:apply执行这个命令后AI会逐个处理tasks.md中的任务每个任务完成后会自动对照specs文件中的场景要求进行验证确保代码符合预期。比如完成任务2场景判断逻辑后AI会自动检查是否覆盖了所有4个场景是否符合每个场景的预期行为若有遗漏或错误会自动修正。第三步变更归档形成可追溯记录代码实现和验证完成后输入以下命令进行归档/opsx:archive执行命令后OpenSpec会将当前的活跃变更文件夹归档到openspec/changes/archive目录下并以“日期-变更描述”的格式命名比如“2026-03-25-start-unicloud-service”。归档完成后这个变更的所有规范文档、代码实现都被完整保存后续如果需要查询这个变更的设计思路、实现步骤直接查看归档目录即可实现了变更的全流程可追溯。2.5 独特设计主spec delta spec体系实现知识积累OpenSpec最具特色的设计就是它的“主spec delta spec”体系这套体系能实现项目级规格知识库的长期积累让规范文档越用越完善避免重复编写。我们先来看一下它的目录结构openspec/ ├── specs/# 主 specs项目级知识库│ └── disk-mount/spec.md │ └── changes/# 变更目录├── start-unicloud-service/# 活跃变更│ ├── proposal.md │ ├── design.md │ ├── specs/# delta specs变更级│ │ └── unicloud-service-startup/spec.md │ └── tasks.md │ └── archive/# 已归档变更└──2026-03-25-start-unicloud-service/从目录结构可以看出OpenSpec的spec分为两类主spec和delta spec。主spec位于openspec/specs目录下是项目级的规格知识库按功能模块组织比如disk-mount磁盘挂载、user-auth用户认证等包含了项目中所有核心功能的规范是团队共享的基础规范。delta spec位于每个变更的specs目录下是针对本次变更新增或修改的规范只包含与本次变更相关的内容不需要重复编写主spec中已有的规范。当变更归档时OpenSpec会自动将delta spec中的内容同步到主spec中更新项目级知识库。这种体系的优势非常明显一方面每次变更只需编写与自身相关的delta spec节省规范编写时间另一方面主spec会随着每次变更不断完善形成可查询、可复用的知识积累后续新的开发需求可以直接参考主spec避免重复设计提升团队协作效率。三、Superpowers多代理协作的完整开发工作流如果说OpenSpec侧重“变更追溯和知识积累”那么Superpowers则侧重“执行质量和自动化审查”。Superpowers是由Jesse Vincent开发的开源项目它为AI编码代理提供了一套完整的软件开发工作流支持Claude Code、Cursor、Codex、Gemini CLI等多个平台核心特色是“子代理驱动开发”和“强制TDD”能让AI像有纪律的开发团队一样工作。3.1 核心概念Skills组合定义AI的每一步行为Superpowers的核心是“Skills组合”所谓Skills就是一组可组合的指令文件每个Skill都是一份Markdown格式的文档定义了AI在特定开发阶段应该做什么、怎么做。这些Skills按功能分类相互配合构成了完整的开发工作流。我们整理了Superpowers的核心Skills分类、具体内容和职责方便大家快速理解类别Skills职责协作brainstorming通过苏格拉底式对话提问引导需求梳理对比不同方案输出完整设计文档规划writing-plans将需求拆分为2-5分钟可完成的bite-sized tasks确保任务可执行、无遗漏执行subagent-driven-development为每个task派遣独立子代理负责代码实现和自审查测试test-driven-development强制遵循RED-GREEN-REFACTOR循环确保代码有完善的测试覆盖审查requesting-code-review两阶段审查先检查Spec合规性再审查代码质量Gitusing-git-worktrees创建隔离工作空间验证编译基线避免影响主分支收尾finishing-a-development-branch负责分支合并、创建PR、保留或丢弃分支完成开发收尾这些Skills可以根据需求灵活组合比如简单需求可以组合brainstorming、writing-plans、subagent-driven-development三个Skills复杂需求则可以添加test-driven-development、requesting-code-review等Skills确保开发质量。3.2 Superpowers完整工作流程从需求到收尾的全闭环Superpowers的工作流程非常清晰从需求梳理到分支收尾每个阶段都有对应的Skill驱动形成了完整的闭环。我们用流程图的形式直观展示整个流程brainstorming → using-git-worktrees → writing-plans → subagent-driven-dev → finishing-branch下面我们逐个拆解每个阶段的核心工作让大家清楚AI在每个阶段的具体行为。1brainstorming苏格拉底式对话梳理需求与设计这是整个流程的起点核心目的是梳理清楚需求和设计方案。AI会以苏格拉底式对话的方式不断向用户提问引导用户明确需求细节、技术选型、潜在风险等内容。比如用户提出“实现一个用户登录接口”AI会依次提问登录方式有哪些账号密码、短信验证码、是否需要记住密码功能、密码是否需要加密存储、登录失败的错误提示有哪些、是否需要防刷机制等。通过一系列提问逐步完善需求细节最终输出一份完整的设计文档明确接口的请求参数、响应格式、业务逻辑、异常处理等内容。2using-git-worktrees创建隔离工作空间确保基线稳定需求梳理完成后AI会执行using-git-worktrees Skill创建一个隔离的Git工作空间git worktree。这个工作空间独立于主分支不会影响主分支的代码同时AI会验证当前工作空间的编译基线确保依赖安装完整、代码可正常编译为后续开发做好准备。这种隔离工作空间的设计能有效避免开发过程中对主分支的污染尤其是在多人协作项目中每个开发者的变更都在独立工作空间中进行测试通过后再合并到主分支提升代码稳定性。3writing-plans拆分bite-sized tasks确保可执行设计文档确定后AI会执行writing-plans Skill将需求拆分为多个“2-5分钟可完成”的bite-sized tasks。这种拆分方式的核心是“小步快跑”每个任务都足够小能快速完成和验证避免出现大任务无法推进、难以验证的问题。比如实现用户登录接口会拆分为以下几个tasks第一步定义登录接口的路由2分钟第二步编写请求参数校验逻辑3分钟第三步实现密码加密比对逻辑4分钟第四步编写登录成功和失败的响应逻辑3分钟第五步编写单元测试5分钟。每个task都有明确的时间预估和执行目标AI能按步骤逐步完成。4subagent-driven-dev子代理隔离实现提升执行质量这是Superpowers最核心的阶段也是它与其他框架的最大区别——子代理驱动开发。AI会扮演“Controller编排者”的角色为每个task派遣独立的子代理每个子代理负责特定的工作且拥有独立的上下文避免上下文污染。每个task的执行过程如下Controller派遣Implementer子代理负责代码实现首先会检查当前task的需求细节如有疑问会向用户提问确认后开始编写代码同时按照TDD要求编写测试用例完成后进行自审查最后向Controller报告状态DONE/ DONE_WITH_CONCERNS/ BLOCKED/ NEEDS_CONTEXT。Controller派遣Spec Reviewer子代理负责对照plan和设计文档检查Implementer子代理的实现是否符合需求重点关注需求覆盖、场景遗漏、过度实现等问题。如果通过就进入下一阶段如果发现问题会反馈给Implementer子代理让其修复后重新审查。Controller派遣Code Quality Reviewer子代理负责审查代码质量重点关注代码规范、架构合理性、安全性、测试覆盖率等问题将问题分为Critical严重、Important重要、Minor次要三个等级反馈给Implementer子代理修复修复完成后重新审查直到通过。这种子代理隔离的设计最大的优势是“客观性”。Implementer子代理负责实现Reviewer子代理负责审查审查者不会有“这是我写的代码”的心理包袱能更客观地发现问题同时独立的上下文能避免长对话导致的AI逻辑漂移提升代码实现质量。5finishing-branch收尾工作完成变更合并所有tasks完成并通过审查后AI会执行finishing-a-development-branch Skill完成开发收尾工作。具体包括检查分支代码是否通过所有测试创建PRPull Request填写PR描述包含变更内容、测试结果、影响范围根据项目要求决定保留或丢弃当前分支确保变更能顺利合并到主分支。3.3 核心特色1强制TDD确保代码可测试Superpowers的一大核心特色是“强制TDD测试驱动开发”它会在Plan阶段就把TDD的步骤写进每个task中要求Implementer子代理必须遵循“RED-GREEN-REFACTOR”循环不先写测试就无法开始编写代码。每个task中的TDD步骤如下Step 1: 写失败测试RED编写单元测试此时代码未实现测试会失败Step 2: 运行确认失败执行测试用例确认测试失败确保测试用例有效Step 3: 写最小实现代码编写能让测试通过的最小代码不添加多余功能Step 4: 运行确认通过GREEN执行测试用例确认测试通过Step 5: 提交将代码和测试用例一起提交完成该task。如果Implementer子代理没有先写测试就开始编写代码Spec Reviewer子代理会直接拒绝审查要求其补充测试用例。这种强制TDD的设计能确保每一行代码都有测试覆盖减少线上bug提升代码的可维护性。3.4 核心特色2两阶段审查双重保障代码质量Superpowers的另一大特色是“两阶段审查”每个task完成后必须经过两轮独立审查才能进入下一个task确保代码既“做对了”又“做好了”。我们用表格清晰展示两阶段审查的细节阶段审查者关注点输出第一阶段Spec Reviewer子代理做对了吗需求覆盖、场景遗漏、过度实现、是否符合设计文档✅ 通过 / ❌ 问题 具体修改建议第二阶段Code Quality Reviewer子代理做好了吗代码规范、架构合理性、安全性、测试覆盖率Critical / Important / Minor 分级问题 修改建议需要注意的是第二阶段审查必须在第一阶段通过后才能开始。因为如果代码做的事情本身就不符合需求即使代码质量再高也没有意义这种先后顺序的设计能避免无效审查提升审查效率。四、OpenSpec与Superpowers深度对比该选哪个OpenSpec和Superpowers都是SDD理念的优秀实践但它们的侧重点、核心能力和适用场景有很大差异很多开发者会纠结该选择哪个框架。下面我们从多个维度进行深度对比帮大家快速找到适合自己项目的框架。4.1 核心定位与哲学对比两者的核心定位和设计哲学有本质区别这也决定了它们的侧重点不同维度OpenSpecSuperpowers一句话定位规格驱动的变更管理框架多代理协作的完整开发工作流核心理念先写Spec再实现变更可追溯先设计再编码TDD 子代理分工哲学Proposal → Design → Spec → TasksBrainstorm → Plan → TDD Subagent → Review侧重点决策追溯 知识积累执行质量 自动化审查4.2 工作流程对比两者的工作流程虽然都遵循SDD理念但每个阶段的具体内容和侧重点有很大差异OpenSpec流程explore → proposal → design → specs → tasks → apply → verify → archiveSuperpowers流程brainstorming → git-worktree → writing-plans → subagent-dev → finishing-branch我们进一步拆解每个阶段的差异阶段OpenSpecSuperpowers探索/需求explore proposal明确变更原因和目标brainstorming苏格拉底式一问一答梳理需求和设计设计design.md记录技术方案决策和风险评估融合在design doc中通过对话确定技术方案规格独立specs/目录有主spec delta spec同步体系无独立spec融合在design doc和plan中任务拆分tasks.md按功能粒度拆分Plan按2-5分钟/step拆分含完整测试步骤实现单代理逐task实现自验证子代理隔离实现 两阶段审查测试不强制TDD以编译通过和行为验证为准强制TDDRED-GREEN-REFACTOR循环审查自审查checklist独立子代理审查上下文隔离Git不强制分支策略强制git worktree隔离收尾archive归档所有Artifact文档finishing-branch合并/PR/丢弃分支4.3 核心能力差异对比除了流程差异两者在核心能力上也有明显区别主要集中在代理模式、Spec管理和测试策略三个方面。1子代理 vs 单代理维度Superpowers子代理OpenSpec单代理执行模式Controller Implementer Reviewer × 2分工明确同一个AI全程负责从规范生成到代码实现上下文每个子代理独立上下文精确裁剪避免漂移共享上下文长对话可能出现逻辑漂移审查客观性高审查者与实现者分离无心理包袱中需要AI角色切换模拟审查者平台依赖高需要支持子代理派遣如Claude Code低任何AI编码助手均可使用2Spec管理维度OpenSpecSuperpowers独立Spec体系✅ 主spec delta spec 自动同步❌ 无独立spec融合在design doc和plan中长期积累specs按功能组织可查询、可复用形成知识库plan/design平铺在docs目录难以长期积累和查询变更追溯archive按日期归档含完整Artifact文档追溯性强依赖Git历史追溯性较弱3测试策略维度SuperpowersOpenSpecTDD强制严格遵循RED-GREEN-REFACTOR循环不强制以编译通过和行为验证为准Plan中的测试每个step包含完整测试代码和执行步骤tasks中不含测试代码需单独编写4.4 适用场景对比选对框架才是关键没有最好的框架只有最适合的框架。结合两者的核心差异我们整理了不同场景下的框架推荐帮大家快速决策场景推荐框架原因全新项目 / 绿地开发SuperpowersTDD git worktree 子代理协作端到端自动化能快速搭建规范的开发流程确保代码质量大型企业项目改动OpenSpecspec追溯 变更归档适合团队review能清晰记录每一次变更的设计思路和实现过程满足企业合规要求需要长期维护specsOpenSpec主spec delta spec 自动同步 归档能形成项目级知识库长期维护更高效有严格测试要求Superpowers内置强制TDD每个step都包含测试能确保代码有完善的测试覆盖减少线上bug不支持子代理的平台OpenSpec天然单代理模式无需子代理支持任何AI编码助手都能使用多代理协作环境Superpowers核心设计就是子代理驱动分工明确能提升执行质量和审查客观性五、总结SDD的终极目标让AI写对每一行代码通过对OpenSpec和Superpowers的详细介绍和对比我们不难发现两者虽然侧重点不同但都围绕SDD的核心理念——“先规范后编码”解决AI编码不规范、不可追溯、质量参差不齐的痛点。OpenSpec的核心优势在于“Spec驱动 变更追溯 知识积累”它能让每一次变更都有完整的设计文档可追溯形成项目级的规格知识库适合需要长期维护、注重变更管理的项目Superpowers的核心优势在于“子代理隔离 TDD强制 自动化审查”它能让AI像有纪律的开发团队一样工作确保代码执行质量适合全新项目、有严格测试要求的项目。需要强调的是OpenSpec和Superpowers并不是竞争关系而是互补关系。在实际开发中我们可以将两者结合使用发挥各自的优势用OpenSpec做spec管理和变更追溯确保每一次变更都有据可查从Superpowers中提取审查和git worktree能力强化spec合规审查提升代码执行质量。在AI编码普及的今天越来越多的开发者开始依赖AI提升效率但我们不能忘记AI只是工具规范才是保证开发质量的核心。SDD的终极目标从来不是否定AI的效率而是用规范给AI“立规矩”让AI的高效发挥在正确的轨道上让AI写的每一行代码都有据可查、有规可循。