OpenSpec与Superpowers结合：实现SDD规范驱动开发的AI编码工作流

1. 项目概述当OpenSpec遇上SuperpowersAI编码的“最后一公里”终于打通如果你和我一样在过去一两年里深度折腾过各种AI编码助手从早期的GitHub Copilot到后来的Cursor、Claude再到各种本地部署的大模型那你一定经历过一个典型的“分裂”状态一边是AI生成的代码片段像雪花一样飞来速度飞快另一边是你自己得手动把这些片段拼凑起来理解上下文调试边界条件最后还得写测试和文档。整个过程就像是一个蹩脚的接力赛AI跑完第一棒把接力棒也就是生成的代码往地上一扔剩下的九棒还得你自己气喘吁吁地捡起来跑完。效率提升了吗确实有但远没有达到“工作流自洽”的质变。直到我最近把OpenSpec和Superpowers这两个工具“焊死”在一起整个局面才豁然开朗。这感觉就像是给AI编码这辆跑车终于装上了自动导航和底盘稳定系统让它不仅能跑直线还能自己过弯、超车甚至处理突发路况。简单来说OpenSpec负责定义“做什么”和“做成什么样”即规范与契约而Superpowers则赋予AI“如何做”的上下文与执行能力。当它们紧密结合就形成了一套从意图到可交付代码的完整、闭环的AI驱动开发工作流也就是最近在开发者圈子里热议的SDDSpecification-Driven Development规范驱动开发。这套组合拳最适合谁我认为是三类人一是中小型团队的Tech Lead或架构师你们需要快速将设计落地并保证代码质量的一致性二是独立开发者或小型工作室资源有限必须最大化AI的杠杆效应三是任何对“如何让AI真正理解业务并生成可靠代码”这个命题感到好奇的实践者。接下来我就把自己踩坑、调试、最终跑通这套工作流的全过程拆解给你看这不仅仅是一篇教程更是一次关于未来开发模式的实地勘探。2. 核心理念拆解为什么是SDD而不仅仅是TDD或DDD在深入工具之前我们必须先统一思想SDD究竟是什么以及它为何能成为AI编码时代的“杀手级”方法论我们都很熟悉TDD测试驱动开发和DDD领域驱动设计。TDD的核心是“红-绿-重构”用测试用例来驱动功能实现确保代码正确性。DDD则关注通过统一的语言和模型来应对复杂业务逻辑。它们都很优秀但在AI辅助编码的语境下都面临一些挑战TDD的挑战让AI直接根据一个失败的测试用例红来生成代码绿效果往往不佳。因为AI缺乏对“为什么这个测试会失败”以及“这个功能在整个系统中的角色”的宏观理解。它生成的代码可能仅仅是通过了当前测试却破坏了其他隐式契约。DDD的挑战DDD的概念聚合根、值对象、领域服务等对于AI来说过于抽象和依赖上下文。如果没有极其精确的限定和示例AI很容易生成结构混乱、不符合领域模型的代码。SDD规范驱动开发正是在此背景下被提出的一个演进思路。它的核心主张是将人类最高级、最明确的意图——即“规范”Specification——作为开发流程的唯一源头和真理。这个“规范”不是一份冗长的Word文档而是一份结构化、机器可读、无歧义的描述文件。它明确规定了接口契约API的端点、方法、输入输出数据的精确结构JSON Schema、错误码。业务规则数据验证逻辑、状态转换条件、权限规则。非功能性需求性能指标、安全要求、兼容性说明。SDD的工作流可以概括为编写规范 - AI基于规范生成代码 - 验证代码符合规范 - 迭代。这里的“验证”不仅包括传统的单元测试更重要的是通过规范本身对生成的代码进行静态校验和契约测试。OpenSpec和Superpowers的组合恰好完美地支撑了SDD。OpenSpec是规范的“书写语言”和“校验器”而Superpowers则为AI提供了理解这份规范并据此行动的“超级上下文”。两者结合确保了从“人类意图”到“机器代码”的转换路径是直接、可控且高保真的。3. 工具深度解析OpenSpec与Superpowers如何各司其职3.1 OpenSpec你的机器可读“产品需求说明书”OpenSpec不是一个具体的软件而是一种规范格式和一套工具链。你可以把它想象成针对API和组件的“TypeScript类型定义”但功能强大得多。它的核心是一个YAML或JSON格式的文件通常命名为openapi.yaml或spec.yaml但这个文件遵循了OpenAPI Specification标准的一个超集或特定扩展。它的核心价值在于单一事实来源前端、后端、测试、文档都基于同一份OpenSpec文件彻底消除沟通歧义。机器可读与可执行工具可以读取它来生成代码、模拟服务器、验证请求、创建测试用例。面向AI优化结构化的数据比自然语言描述更能被AI准确理解。一个定义良好的schema能直接告诉AI“user对象必须包含id(整数)、name(字符串必填) 和email(字符串符合邮箱格式)”。一个极简的OpenSpec片段示例openapi: 3.0.0 info: title: 用户管理系统API version: 1.0.0 paths: /users/{userId}: get: summary: 获取用户详情 parameters: - name: userId in: path required: true schema: type: integer responses: 200: description: 成功 content: application/json: schema: $ref: #/components/schemas/User 404: description: 用户不存在 components: schemas: User: type: object required: - id - name properties: id: type: integer format: int64 name: type: string email: type: string format: email这份规范明确无误地定义了一个GET接口。AI拿到它就能毫无歧义地生成对应的控制器代码、数据库查询逻辑、乃至前端调用的Service函数。实操心得不要试图一开始就写一个完整的、庞大的OpenSpec文件。应该采用迭代方式为当前正在开发的核心功能模块先定义规范。从一个简单的、独立的端点开始让AI生成代码验证跑通再逐步扩展规范。这比先花一周写完所有接口规范再开发要高效、务实得多。3.2 Superpowers赋予AI“场景化记忆”的上下文增强器如果说OpenSpec给了AI“图纸”那么Superpowers就是给AI配了一个“资深架构师助理”这个助理记得项目里所有的细节和约定。Superpowers通常以IDE插件如VS Code扩展或CLI工具的形式存在。它的核心功能是项目管理与上下文注入。它不仅仅是一个聊天窗口而是一个智能的“项目感知”系统。它主要解决以下痛点上下文遗忘普通的AI对话你每次都要重新解释项目结构、技术栈、编码风格。Superpowers会主动维护一个持久的项目上下文通过扫描项目文件、读取配置文件如package.json、.gitignore、README.md等。指令碎片化你需要反复说“参考/utils/helper.js里的格式”、“遵循我们项目的ESLint规则”。Superpowers可以预设这些规则并在每次交互中自动带入。操作断层AI生成的代码你需要手动复制、粘贴、创建文件。Superpowers可以直接在IDE中操作文件系统根据指令创建、修改、移动文件甚至执行终端命令。Superpowers的典型工作流程你打开项目Superpowers插件自动加载分析项目结构。你在聊天框输入“基于openapi.yaml里/users的POST规范在src/routes/下创建对应的Express.js路由处理器并连接到UserService。”Superpowers会做以下几件事读取openapi.yaml找到对应的规范。理解你项目的结构src/routes/目录存在使用的是Express.js。知晓UserService的位置和接口。生成完全符合上下文的代码。直接在src/routes/userRoutes.js中创建或插入代码块。你审查生成的代码几乎无需修改因为它已经遵循了项目的所有约定。注意事项Superpowers的强大依赖于你项目本身的“整洁度”。一个结构混乱、没有清晰约定的项目会让Superpowers也无从下手。在引入Superpowers之前建议先花点时间规范项目结构、统一编码风格配置好Prettier、ESLint这能极大提升后续AI协作的效率。4. 实战构建自洽的AI编码工作流理论说再多不如亲手搭一遍。下面我以构建一个简单的“待办事项TodoAPI”为例展示如何将OpenSpec和Superpowers“焊死”形成一个流畅的工作流。4.1 环境准备与初始化首先确保你的开发环境已经就绪安装Node.js这是运行JavaScript工具链的基础。安装VS Code并安装以下插件Superpowers插件在VS Code扩展商店搜索“Superpowers”或其具体发行名称如“Qoder”、“Claude for VS Code”等具体名称可能因版本而异并安装。安装后通常需要在插件设置中配置你的AI API密钥如OpenAI、Anthropic等。OpenAPI (Swagger) Editor用于高亮和校验OpenSpec文件。ESLint和Prettier用于代码风格统一。创建项目目录mkdir ai-todo-api cd ai-todo-api npm init -y安装基础依赖npm install express npm install -D nodemon4.2 第一步用OpenSpec定义“宪法”在项目根目录创建openapi.yaml文件。这是我们工作流的起点也是“宪法”。我们先定义最核心的创建和列取Todo的接口。openapi: 3.0.0 info: title: AI驱动待办事项API version: 1.0.0 description: 这是一个演示SDD工作流的简单API。 servers: - url: http://localhost:3000/api description: 本地开发服务器 paths: /todos: get: summary: 获取所有待办事项 operationId: getTodos responses: 200: description: 成功 content: application/json: schema: type: array items: $ref: #/components/schemas/Todo post: summary: 创建新的待办事项 operationId: createTodo requestBody: required: true content: application/json: schema: $ref: #/components/schemas/TodoInput responses: 201: description: 创建成功 content: application/json: schema: $ref: #/components/schemas/Todo 400: description: 输入参数无效 components: schemas: Todo: type: object required: - id - title - completed properties: id: type: string format: uuid description: 待办事项的唯一标识符 title: type: string description: 待办事项标题 example: 学习OpenSpec completed: type: boolean description: 是否已完成 default: false createdAt: type: string format: date-time TodoInput: type: object required: - title properties: title: type: string description: 待办事项标题 example: 学习OpenSpec completed: type: boolean description: 是否已完成 default: false这份规范清晰地定义了数据模型Todo,TodoInput和两个端点GET/todos, POST/todos。operationId是关键它将作为生成代码时函数名的依据。4.3 第二步用Superpowers生成骨架代码现在打开VS Code确保Superpowers插件已激活并正确配置了API密钥。在项目根目录打开终端输入code .在VS Code中打开项目。操作1生成Express应用骨架在Superpowers的聊天面板中输入基于当前目录的package.json这是一个Node.js项目。请为我创建一个基本的Express.js服务器文件 app.js。要求 1. 监听3000端口。 2. 添加必要的中间件解析JSON的body-parser。 3. 为 /api 路径添加一个路由器。 4. 导出一个可供测试的app实例。Superpowers会生成类似下面的代码并可能直接创建app.js文件const express require(express); const app express(); // 中间件 app.use(express.json()); // 解析 application/json // 路由 const apiRouter express.Router(); app.use(/api, apiRouter); // 根路径 app.get(/, (req, res) { res.json({ message: Todo API is running }); }); const PORT process.env.PORT || 3000; app.listen(PORT, () { console.log(Server is running on port ${PORT}); }); module.exports app; // 导出供测试使用操作2根据OpenSpec生成路由和控制器这是核心步骤。在聊天框输入更具体的指令将OpenSpec作为上下文请阅读项目根目录下的 openapi.yaml 文件。根据其中的规范 1. 在 src 目录下创建以下结构src/routes/todoRoutes.js 和 src/controllers/todoController.js。 2. 在 todoRoutes.js 中实现 /todos 的GET和POST路由它们应调用 todoController.js 中对应的 getTodos 和 createTodo 函数。 3. 在 todoController.js 中暂时用内存数组模拟数据层实现这两个函数。请严格遵循 openapi.yaml 中定义的请求和响应格式特别是 Todo 和 TodoInput 的schema。 4. 最后修改 app.js将 apiRouter 挂载上 todoRoutes。Superpowers会执行以下动作读取并理解openapi.yaml。创建src目录及子目录。生成高度符合规范的路由文件。例如src/routes/todoRoutes.jsconst express require(express); const router express.Router(); const todoController require(../controllers/todoController); router.get(/todos, todoController.getTodos); router.post(/todos, todoController.createTodo); module.exports router;生成控制器文件src/controllers/todoController.js其中包含模拟数据和严格的输入验证基于OpenSpec的schema精神// 模拟数据库 let todos []; let nextId 1; const todoController { getTodos: (req, res) { // 直接返回模拟数据格式符合Todo schema res.status(200).json(todos); }, createTodo: (req, res) { const { title, completed false } req.body; // 基础验证 (对应OpenSpec中TodoInput的required: title) if (!title || typeof title ! string) { return res.status(400).json({ error: Invalid input: title is required and must be a string }); } // 创建新的Todo对象格式严格遵循Todo schema const newTodo { id: todo-${nextId}, // 模拟uuid title, completed: Boolean(completed), createdAt: new Date().toISOString(), }; todos.push(newTodo); res.status(201).json(newTodo); // 返回创建的对象 }, }; module.exports todoController;自动更新app.js添加const todoRoutes require(./src/routes/todoRoutes);和apiRouter.use(todoRoutes);。整个过程你几乎没有手动编写业务逻辑代码只是给出了精确的指令和规范。Superpowers基于OpenSpec这个“宪法”生成了完全合规的代码骨架。4.4 第三步验证与迭代——工作流的闭环生成代码后工作流并未结束验证是确保“自洽”的关键。运行与测试修改package.json的scriptsdev: nodemon app.js运行npm run dev。使用Postman或curl测试GET http://localhost:3000/api/todos和POST http://localhost:3000/api/todos。观察响应是否符合OpenSpec的定义状态码、JSON结构。规范变更驱动代码更新 这是SDD最强大的地方。假设产品经理要求为Todo增加一个priority优先级字段。第一步更新“宪法”修改openapi.yaml在Todo和TodoInput的schema里添加priority属性枚举类型low,medium,high。第二步指令AI同步更新在Superpowers中输入我更新了 openapi.yaml为Todo模型添加了 priority 字段枚举值low, medium, high。请相应地更新 1. src/controllers/todoController.js 中的 createTodo 函数使其能接收并验证 priority 字段默认值为 medium。 2. 同时更新内存模拟数据中已有的todo对象为它们添加一个默认的 priority: medium。 3. 确保GET请求返回的数据也包含此字段。Superpowers会分析openapi.yaml的变更并精准地修改控制器代码更新数据初始化逻辑。你只需要审查变更即可。生成接口文档与客户端SDK 利用OpenSpec的机器可读性我们可以轻松生成其他产物进一步自动化。生成API文档使用swagger-ui-express库可以瞬间将openapi.yaml变成漂亮的交互式API文档页面。生成前端TypeScript类型或API客户端使用openapi-generator等工具可以直接从规范生成前端调用所需的类型定义和请求函数保证前后端类型安全。至此一个完整的、基于OpenSpec规范和SuperpowersAI执行的SDD工作流就形成了修改规范 - AI同步代码 - 验证 - 生成衍生资产。这个循环是高度自洽且高效的。5. 进阶技巧与避坑指南将两个工具“焊死”意味着更深度的集成和更高效的操作。以下是一些我实践中总结的进阶技巧和常见问题的解决方案。5.1 如何设计对AI友好的OpenSpecAI不是人它需要清晰、无歧义的结构化信息。一份对AI友好的OpenSpec应具备完整的operationId为每个路径操作都设置一个唯一的、语义化的operationId如getUserById,createOrder。这将是AI生成函数名的最佳依据。详尽的Schema定义尽量使用$ref引用可复用的组件但确保每个schema都定义了type、required、properties以及example。example字段能给AI提供极其重要的上下文范例。清晰的描述description在每个路径、操作、参数旁边用简单的英语描述其业务目的。例如description: “根据用户ID获取用户详情仅限管理员或用户本人访问。”这能帮助AI理解业务上下文生成更合理的代码比如加入权限校验。使用枚举enum和格式format对于有限集合的值如状态、类型务必使用enum。对于邮箱、日期、UUID等使用标准的format。这能让AI生成更精确的验证逻辑。5.2 最大化Superpowers效能的配置与提示词工程Superpowers的能力上限取决于你如何配置和与它对话。项目级配置在项目根目录创建一个.superpowers或.cursor/rules文件取决于具体工具。在这个文件里你可以预设{ project_context: 这是一个基于Node.js和Express的RESTful API项目使用ES模块语法。代码风格遵循Airbnb JavaScript规范。, default_tasks: { create_route: 请参考 src/routes/userRoutes.js 的模式创建新的路由文件。, create_controller: 控制器函数应放在 src/controllers/ 目录下遵循 todoController.js 的异常处理模式。 }, files_to_ignore: [node_modules, .git, *.log] }这相当于给了AI一个项目的“员工手册”。精准的提示词避免模糊指令。对比以下两种差“做个用户登录。”优“在openapi.yaml中POST /auth/login路径下我已定义了请求体username, password和响应体token, userInfo。请在src/routes/下创建authRoutes.js并在src/controllers/下创建authController.js实现登录逻辑。密码验证请使用bcrypt库对比哈希值成功则使用jsonwebtoken库生成一个24小时过期的JWT token返回。” 后者的指令包含了位置、依据、技术细节和库依赖AI生成的代码会非常接近生产要求。善用“”引用文件大多数Superpowers类工具支持在提示词中用引用特定文件。例如“请参考src/models/User.js中的字段定义来生成更新用户信息的API。” 这能确保AI使用的上下文是最新的。5.3 常见问题与排查实录问题1AI生成的代码不符合项目编码风格如缩进、分号。原因Superpowers没有获取到项目的风格配置。解决方案确保项目根目录存在.eslintrc.js和.prettierrc配置文件。在第一次与AI进行重大项目交互前可以在聊天框发送这些配置文件的内容并说“这是本项目的代码风格配置请后续所有代码生成都严格遵守此风格。” 之后AI会记住。问题2AI总是忘记之前定义的接口或数据结构。原因对话上下文长度有限或AI没有主动去读取最新文件。解决方案在关键指令中总是明确指向源文件。例如“基于当前最新的openapi.yaml文件请生成...”。对于复杂项目可以分模块进行每次只处理一个紧密相关的功能集减少上下文负担。问题3生成的代码有逻辑错误或安全漏洞。原因AI毕竟不是人它可能生成有问题的逻辑如不充分的输入验证、错误的错误处理。解决方案AI生成人类审查。永远不要盲目信任生成的代码。必须将AI视为一个强大的“初级程序员”它的产出需要资深开发者你进行严格审查特别是业务逻辑、数据验证和安全性相关的部分。建立代码审查环节即使是AI生成的代码。问题4OpenSpec文件变得庞大难以维护。原因所有接口定义挤在一个文件里。解决方案利用OpenAPI的$ref语法将不同的组件拆分到多个文件中。# openapi.yaml paths: /users: $ref: ./paths/users.yaml components: schemas: User: $ref: ./components/schemas/User.yaml这样你可以用Superpowers指令AI“请更新./components/schemas/User.yaml为其添加phoneNumber字段。” 维护性大大提升。6. 工作流扩展连接更多自动化环节一个真正“焊死”的、自洽的工作流不应止步于代码生成。我们可以利用OpenSpec的机器可读性将其作为源头触发更多的自动化任务。自动化测试生成使用如swagger-test-templates或openapi-generator的测试模板可以从OpenSpec自动生成接口集成测试的骨架代码你只需要填充一些模拟数据即可。CI/CD集成在GitHub Actions或GitLab CI中可以添加一个步骤每当openapi.yaml文件发生变更时自动运行脚本重新生成客户端SDK并发布到内部的npm仓库确保前后端契约同步。API监控与告警可以将OpenSpec导入到API网关或监控工具如Postman Monitor、Datadog中自动配置监控的端点、请求方法和预期的成功响应码实现监控即代码。这套以OpenSpec为单一事实来源以SuperpowersAI为主要执行者串联起开发、测试、部署、监控的完整流程才是“AI编码工作流自洽”的终极形态。它不仅仅提升了写代码的速度更重要的是它建立了一种可靠、可重复、高质量的价值交付机制。