1. 项目概述当“规范”成为AI开发的“方向盘”最近和几个技术团队的朋友聊天大家普遍有个共鸣现在用AI辅助写代码、生成文档、甚至设计架构效率确实上来了但心里总有点不踏实。生成的东西今天一个样明天一个样同一个需求问两遍AI可能给出两种完全不同的实现。项目规模稍微一大或者需要多人协作时这种“不确定性”就成了噩梦——你永远不知道队友用AI跑出来的代码和你理解的“需求”是不是一回事。这种失控感恰恰是阻碍我们将AI从“玩具”升级为“生产级工具”的最大障碍。“Spec-Driven Development”规范驱动开发简称SDD就是在这种背景下被越来越多前沿团队提及和实践的一种方法论。它的核心思想异常简单却直击要害在让AI动手写任何一行代码之前我们必须先和它更重要的是和我们自己就“要做什么”以及“做成什么样”达成一份清晰、无歧义、可验证的“契约”。这份“契约”就是“规范”Specification。你可以把它理解为给AI开发者的“超级详细的产品需求文档PRD 技术设计文档”只不过这份文档的读者不仅是人类更是AI。简单来说SDD不是要取代敏捷开发、测试驱动开发TDD或行为驱动开发BDD而是为它们尤其是为AI辅助编程这个新场景提供了一个更前置、更结构化的“输入层”。它试图解决的核心矛盾是如何在不牺牲AI带来的巨大生产力提升的前提下确保产出的确定性、一致性和可维护性。这不仅仅是技术问题更是工程管理和协作范式的问题。无论你是独立开发者、创业团队的技术负责人还是大厂里探索效能提升的工程师理解并实践SDD都可能成为你驾驭AI、而非被AI“带偏”的关键。2. 核心理念与价值为什么“先规范后生成”如此重要2.1 从“提示词工程”到“规范工程”的范式升级早期我们使用AI编程基本停留在“提示词工程”阶段在聊天框里输入一段自然语言描述比如“写一个Python函数计算两个日期的差值”。这种方法对于简单、孤立的任务有效但弊端明显模糊性“日期差值”是指天数、工作日数还是包含时分秒的精确时长时区如何处理上下文缺失AI不知道你的项目用了什么框架、遵循什么编码规范、有哪些现有的工具函数可以复用。不可重复同样的提示词不同模型版本、甚至同一模型的不同时间可能产生差异巨大的代码。难以集成生成的代码块如何融入现有项目结构接口如何定义错误如何处理这些都需要人工二次加工和判断。SDD倡导的“规范工程”则是将这种临时的、模糊的“对话”升级为一份正式的、结构化的“设计文档”。这份规范至少应包含以下几个维度功能性需求输入是什么输出是什么边界条件有哪些等同于BDD中的Given-When-Then。非功能性需求性能指标如响应时间100ms、安全性要求如输入验证、防SQL注入、兼容性要求等。接口契约函数/方法的签名名称、参数类型、返回值类型、抛出的异常类型。代码约束必须使用的库/框架版本、禁止使用的语法/模式、代码风格如PEP 8、必须包含的日志或监控点。验收标准一组具体的、可自动执行的测试用例输入和预期输出这是规范中最关键的部分它让“符合规范”变得可衡量。注意规范不是越详细越好而是要在“清晰无歧义”和“维护成本”之间找到平衡。一个好的规范应该让一个不了解背景的合格开发者或AI能独立实现出符合要求的功能。2.2 SDD带来的核心价值可控、高效与可协作实践SDD短期内看似增加了“写规范”的额外步骤但长期来看它从多个维度带来了显著的回报提升产出的确定性与质量规范是唯一的事实来源。AI基于明确的规范生成代码其输出的一致性、正确率会大幅提高。因为模糊空间被压缩了AI“自由发挥”导致跑偏的概率降低。同时由于规范中包含了验收测试我们可以立即对生成代码进行验证快速发现偏差。实现人机与人人之间的高效对齐在团队中规范成为一个中立的、可讨论的媒介。产品经理、架构师、开发者可以围绕规范进行评审和修改确保所有人对需求的理解一致。之后无论是资深工程师还是AI来执行实现都基于同一份蓝图减少了沟通误解和返工。赋能自动化与持续集成结构化的规范特别是机器可读的格式如OpenAPI Spec、Protobuf、或自定义的DSL可以直接作为自动化工具的输入。我们可以构建流水线提交规范 - AI生成代码草案 - 自动运行规范中的验收测试 - 生成报告或自动合并。这极大地压缩了从设计到可测试代码的周期。积累可复用的领域知识资产规范本身是项目宝贵的知识库。它们记录了系统为什么这样设计、某个业务规则的具体含义。这些规范可以被新加入的成员学习也可以被复用于类似的新功能开发甚至可以作为训练专属领域AI模型的优质数据。降低对特定AI工具或提示词的依赖你的核心资产是“规范”而不是针对某个AI模型如ChatGPT-4、Claude-3精心调校的提示词。只要AI模型能理解你的规范格式你就可以切换模型或工具而不会对生产流程造成颠覆性影响。3. 实践框架如何落地Spec-Driven Development理论说再多不如看看具体怎么操作。SDD不是一个僵化的流程而是一套可以适配不同团队习惯的实践框架。下面我以一个常见的后端API开发场景为例拆解一个完整的SDD循环。3.1 第一步编写机器与人皆可读的规范这是SDD的起点也是最需要投入智慧的一步。规范的形式可以多样自然语言增强文档在Markdown或Wiki中用结构化的段落描述需求并明确标出输入/输出示例、错误案例和验收条件。关键是要严格避免“可能”、“大概”、“通常”这类词汇。结构化数据格式对于API直接使用OpenAPI Specification (Swagger)或AsyncAPI。它们能精确定义路径、方法、参数、请求/响应体、状态码本身就是一份极佳的规范。测试代码即规范这是TDD/BDD的延伸。在写实现代码前先写出完整的、会失败的验收测试例如用Pytest、JUnit、Cucumber。这些测试用例就是对功能行为最精确的规范。自定义DSL领域特定语言对于复杂或特有的业务逻辑可以设计一套简单的DSL来描述规则。DSL更贴近业务语言且易于被解析和转换为其他形式。实操示例创建一个“用户注册”API端点我们选择“自然语言增强文档 OpenAPI片段”作为规范载体。首先在项目的/specs/目录下创建一个user_registration.md文件# 规范用户注册API **功能描述**接收用户提供的邮箱、密码和用户名在系统中创建新用户账户。 **约束与规则** 1. 邮箱必须符合RFC 5322标准且在全系统唯一。 2. 密码长度至少8位必须包含大写字母、小写字母和数字。 3. 用户名长度在3-20字符之间只能包含字母、数字和下划线且唯一。 4. 注册成功后需向用户邮箱发送一封验证邮件邮件发送可异步处理不影响API主流程返回。 5. 所有用户输入必须进行清理防止XSS攻击。 **接口契约OpenAPI 3.0.0片段** yaml paths: /api/v1/users: post: summary: 注册新用户 requestBody: required: true content: application/json: schema: $ref: #/components/schemas/UserRegistrationRequest responses: 201: description: 用户创建成功 content: application/json: schema: $ref: #/components/schemas/UserResponse 400: description: 请求参数无效如邮箱格式错误、密码强度不足、用户名重复等 content: application/json: schema: $ref: #/components/schemas/ErrorResponse 409: description: 资源冲突如邮箱已被注册 content: application/json: schema: $ref: #/components/schemas/ErrorResponse components: schemas: UserRegistrationRequest: type: object required: - email - password - username properties: email: type: string format: email example: userexample.com password: type: string format: password minLength: 8 example: Str0ngPss username: type: string minLength: 3 maxLength: 20 pattern: ^[a-zA-Z0-9_]$ example: new_user_123 UserResponse: type: object properties: id: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 email: type: string username: type: string createdAt: type: string format: date-time ErrorResponse: type: object properties: error: type: string example: EMAIL_ALREADY_EXISTS message: type: string example: The provided email is already registered.验收测试用例Gherkin语法示例Feature: 用户注册 Scenario: 使用有效信息成功注册 Given 系统数据库是空的 When 我向 /api/v1/users 发送POST请求JSON体为 { email: testexample.com, password: ValidPass123, username: testuser } Then 响应状态码应为 201 And 响应体应包含一个有效的UUID id And 响应体中的 email 字段应为 testexample.com And 响应体中的 username 字段应为 testuser And 数据库应存在一条对应的用户记录且密码已被哈希存储 And 邮件发送队列中应有一封发给 testexample.com 的验证邮件 Scenario: 使用已注册邮箱注册应失败 Given 系统中已存在邮箱为 existingexample.com 的用户 When 我尝试用同一邮箱注册 Then 响应状态码应为 409 And 响应体的 error 字段应为 EMAIL_ALREADY_EXISTS这份规范已经足够清晰无论是人类开发者还是AI都能明确知道要构建什么。 ### 3.2 第二步将规范转化为AI提示 有了规范下一步就是引导AI基于它来生成代码。这里的关键是**构造一个包含完整上下文的提示Prompt**。你不能只把规范扔给AI说“实现它”。你需要告诉AI你的技术栈、项目结构、以及你期望的代码风格。 **给AI的提示词示例**你是一个经验丰富的Python后端工程师使用FastAPI框架和SQLAlchemy ORM。请根据以下规范实现用户注册API端点。项目上下文项目使用Python 3.11 FastAPI SQLAlchemy 2.0 Pydantic V2。数据库模型位于app/models/user.py其中User模型已有字段id (UUID), email (String, unique), username (String, unique), hashed_password (String), is_active (Boolean), created_at (DateTime)。密码哈希使用passlib库的bcrypt算法。依赖项get_db会话依赖已定义在app/dependencies.py中。工具函数app/utils/security.py中有verify_password和get_password_hash函数。邮件服务app/services/email.py中有EmailService类其send_verification_email(user_id: UUID)方法会将任务推送到Redis队列。错误处理使用app/exceptions.py中自定义的HTTPException子类如ConflictException。请严格遵循以下规范文件中的要求 这里粘贴或附上user_registration.md中的全部内容特别是OpenAPI schema和验收用例你的任务在app/api/v1/endpoints/users.py中创建register_user路由函数。在app/schemas/user.py中创建对应的Pydantic模型UserRegistrationRequest, UserResponse。确保实现所有业务规则邮箱格式、密码强度、唯一性校验等。实现规范的错误处理400 409。代码需包含适当的日志记录使用app/core/logging中的logger。生成的代码必须能通过提供的验收测试用例你可以描述如何验证。请输出完整的、可运行的代码文件内容。这个提示词提供了丰富的上下文将AI的“创造力”引导到解决具体问题的正确方向上大大减少了它做出不合理假设或使用错误技术栈的概率。 ### 3.3 第三步生成、审查与迭代 AI会根据你的提示生成代码。**你绝不能直接复制粘贴** 生成的代码需要经过严格的审查 1. **功能审查**快速阅读代码看其逻辑是否完全符合规范。重点检查边界条件处理、错误处理、安全措施如密码哈希、输入清理。 2. **集成审查**检查生成的代码是否与你的项目现有结构、命名约定、导入风格无缝集成。AI可能会用错依赖项版本或忽略项目特定的配置。 3. **运行验收测试**这是最关键的一步。立即运行规范中定义的验收测试或根据AI生成的代码描述编写对应的自动化测试。如果测试失败分析原因是规范有歧义还是AI理解有误 4. **迭代优化**如果测试失败或审查发现问题不要直接手动修改代码。首先**回头修改你的规范或提示词**。可能是规范描述不清也可能是提示词遗漏了关键约束。修正后让AI重新生成。这个过程本身就是在打磨你的规范和提示工程能力。 **实操心得**在这个阶段我习惯把AI当成一个“超级实习生”。它出活很快但经验不足需要你导师给出极其明确、无歧义的指令规范并仔细检查它的作业。几次迭代后你和AI的配合会越来越默契你写的规范质量也会越来越高。 ### 3.4 第四步将规范与代码同步纳入CI/CD 理想的SDD流程应该是自动化的。我们可以通过工具将规范文件与代码库关联起来。 * **规范即代码**将OpenAPI spec、测试用例文件等纳入版本控制如Git。 * **生成代码的验证**在CI/CD流水线中添加一个步骤每当规范文件/specs/目录发生变化时自动触发AI代码生成或更新并自动运行关联的验收测试。如果测试失败流水线报错阻止合并。 * **反向同步**如果因为其他原因直接修改了实现代码需要有机制如通过测试、或人工检查来确保代码仍然符合原始规范必要时更新规范文档以反映实际实现。 这套机制确保了“规范”永远是权威来源避免了代码与设计文档逐渐脱节的经典问题。 ## 4. 工具链与最佳实践让SDD事半功倍 SDD的理念不依赖于特定工具但合适的工具能极大提升效率。 ### 4.1 规范编写与管理工具 * **Swagger Editor / Stoplight Studio**用于可视化编辑和验证OpenAPI规范非常适合API优先的开发模式。 * **Cucumber / Behave**支持用Gherkin语言编写可执行的验收测试规范非常适合BDD团队。 * **Notion / Confluence 自定义模板**用团队协作平台管理规范文档通过模板来强制要求包含必要章节如接口契约、验收标准、非功能需求。 * **定制化的DSL与解析器**对于规则引擎、配置系统等可以开发简单的内部DSL并用脚本将其转换为API文档或测试用例。 ### 4.2 AI提示与生成工作流工具 * **Claude Desktop / Cursor IDE / Windsurf**这些新一代的AI编程IDE支持将项目文件作为上下文能更好地处理复杂的、多文件的生成任务。你可以将规范文件直接拖入对话上下文。 * **自制脚本**编写一个Python脚本读取规范文件按照预设模板组装成结构化的提示词然后调用OpenAI或Anthropic的API并将结果输出到指定文件位置。这可以实现一定程度的自动化。 * **GitHub Copilot with Context**在代码库中精心编写 SPEC.md 或 README.md 文件Copilot在给出建议时会参考这些上下文。 ### 4.3 最佳实践与避坑指南 1. **从简单功能开始**不要一开始就试图用SDD设计整个微服务架构。从一个独立的API端点、一个工具函数、一个数据处理脚本开始积累编写有效规范的经验。 2. **规范要可测试**这是黄金法则。如果你写的规范无法转化为一个或多个具体的、可自动验证的测试用例那么它很可能还不够清晰。“系统应该高性能”是模糊的“API在95%的请求下响应时间应低于200ms”是可测试的。 3. **人是最终的责任人**AI是强大的执行者但规范的质量、架构的决策、代码的最终审核责任永远在人类工程师。SDD是增强你的能力而不是取代你的判断。 4. **警惕“规范膨胀”**避免过度设计。规范应该描述“做什么”和“做成什么样”而不是详细规定“每一步怎么做”。给AI和有经验的开发者留出合理的实现自由度。 5. **建立团队共识**SDD需要团队共同接受这种“先设计后实现”的文化。特别是产品经理和QA他们需要参与到规范的编写和评审中确保业务需求被准确转化。 6. **处理模糊地带**有些复杂业务逻辑确实难以用结构化语言完全厘清。这时可以在规范中标注“决策点”并附上几个可能的实现方案及其利弊分析让AI生成多个选项供人类选择。 ## 5. 常见问题与挑战 在实践中你肯定会遇到一些挑战以下是我和团队踩过的一些坑以及应对思路 **Q1写规范的时间比直接写代码还长这不是降低了效率吗** **A**对于极其简单、一次性的任务确实可能如此。但对于任何有维护需求、需要协作、或逻辑复杂的功能前期在规范上的投入会在后期成倍收回成本。它减少了返工、调试、扯皮的时间。更重要的是规范是可复用的资产下次类似功能可以直接修改复用而代码则很难直接复制。 **Q2AI生成的代码质量参差不齐还是需要大量修改怎么办** **A**这通常意味着你的规范或提示词不够好。把每次修改都看作对规范和提示词的反馈。分析AI在哪里出了错是漏了约束还是上下文不足迭代优化你的“输入”而不是总去修补“输出”。同时将生成的代码与高质量代码库对比总结模式并把这些模式比如错误处理模板、日志格式明确写入规范或提示词。 **Q3如何保证生成的代码符合项目特定的架构和设计模式** **A**在提示词中提供最强的上下文。包括 * 关键架构文件的示例如展示一个现有的、符合标准的API端点是怎么写的。 * 项目依赖注入是如何工作的。 * 日志、监控、配置管理的标准做法。 * 直接给出“请模仿 app/api/v1/endpoints/products.py 中 create_product 函数的风格和结构来实现”。 **Q4非功能性需求如性能、安全如何在规范中体现** **A**对于性能可以在规范中定义明确的SLI/SLO如延迟、吞吐量并说明压力测试场景。对于安全必须明确列出安全要求如“所有用户输入必须经过XSS过滤”、“数据库查询必须使用参数化绑定防止SQL注入”、“密码必须使用bcrypt哈希存储”。更好的做法是在项目中有统一的安全中间件或工具函数并在提示词中要求AI使用它们。 **Q5SDD适合前端UI开发吗** **A**当然适合但规范的形式会不同。对于UI组件规范可以是 * **Storybook stories**描述组件在不同状态加载、空数据、错误下的样子。 * **Figma设计稿标注**提供精确的尺寸、颜色、字体、间距、交互状态。 * **交互原型**定义用户操作流点击A弹出B提交后跳转C。 * **可访问性A11y要求**明确ARIA标签、键盘导航、屏幕阅读器支持等。 然后你可以用提示词让AI如GPT-4V结合Figma或Claude根据设计稿生成对应的React/Vue组件代码并确保满足可访问性规范。 Spec-Driven Development 不是银弹但它为混乱的AI辅助开发提供了一条通往秩序和可控性的路径。它的本质是将软件工程中久经考验的“设计先行”原则适配到了人机协作的新时代。当你开始习惯为每个功能先写下一份清晰的“契约”时你会发现AI不再是那个偶尔会给出惊喜但更多是带来惊吓的“黑盒”而是一个真正可靠、高效的执行伙伴。控制权始终在你手中。
规范驱动开发：AI编程时代提升代码确定性与协作效率的工程实践
发布时间：2026/5/27 4:54:47
1. 项目概述当“规范”成为AI开发的“方向盘”最近和几个技术团队的朋友聊天大家普遍有个共鸣现在用AI辅助写代码、生成文档、甚至设计架构效率确实上来了但心里总有点不踏实。生成的东西今天一个样明天一个样同一个需求问两遍AI可能给出两种完全不同的实现。项目规模稍微一大或者需要多人协作时这种“不确定性”就成了噩梦——你永远不知道队友用AI跑出来的代码和你理解的“需求”是不是一回事。这种失控感恰恰是阻碍我们将AI从“玩具”升级为“生产级工具”的最大障碍。“Spec-Driven Development”规范驱动开发简称SDD就是在这种背景下被越来越多前沿团队提及和实践的一种方法论。它的核心思想异常简单却直击要害在让AI动手写任何一行代码之前我们必须先和它更重要的是和我们自己就“要做什么”以及“做成什么样”达成一份清晰、无歧义、可验证的“契约”。这份“契约”就是“规范”Specification。你可以把它理解为给AI开发者的“超级详细的产品需求文档PRD 技术设计文档”只不过这份文档的读者不仅是人类更是AI。简单来说SDD不是要取代敏捷开发、测试驱动开发TDD或行为驱动开发BDD而是为它们尤其是为AI辅助编程这个新场景提供了一个更前置、更结构化的“输入层”。它试图解决的核心矛盾是如何在不牺牲AI带来的巨大生产力提升的前提下确保产出的确定性、一致性和可维护性。这不仅仅是技术问题更是工程管理和协作范式的问题。无论你是独立开发者、创业团队的技术负责人还是大厂里探索效能提升的工程师理解并实践SDD都可能成为你驾驭AI、而非被AI“带偏”的关键。2. 核心理念与价值为什么“先规范后生成”如此重要2.1 从“提示词工程”到“规范工程”的范式升级早期我们使用AI编程基本停留在“提示词工程”阶段在聊天框里输入一段自然语言描述比如“写一个Python函数计算两个日期的差值”。这种方法对于简单、孤立的任务有效但弊端明显模糊性“日期差值”是指天数、工作日数还是包含时分秒的精确时长时区如何处理上下文缺失AI不知道你的项目用了什么框架、遵循什么编码规范、有哪些现有的工具函数可以复用。不可重复同样的提示词不同模型版本、甚至同一模型的不同时间可能产生差异巨大的代码。难以集成生成的代码块如何融入现有项目结构接口如何定义错误如何处理这些都需要人工二次加工和判断。SDD倡导的“规范工程”则是将这种临时的、模糊的“对话”升级为一份正式的、结构化的“设计文档”。这份规范至少应包含以下几个维度功能性需求输入是什么输出是什么边界条件有哪些等同于BDD中的Given-When-Then。非功能性需求性能指标如响应时间100ms、安全性要求如输入验证、防SQL注入、兼容性要求等。接口契约函数/方法的签名名称、参数类型、返回值类型、抛出的异常类型。代码约束必须使用的库/框架版本、禁止使用的语法/模式、代码风格如PEP 8、必须包含的日志或监控点。验收标准一组具体的、可自动执行的测试用例输入和预期输出这是规范中最关键的部分它让“符合规范”变得可衡量。注意规范不是越详细越好而是要在“清晰无歧义”和“维护成本”之间找到平衡。一个好的规范应该让一个不了解背景的合格开发者或AI能独立实现出符合要求的功能。2.2 SDD带来的核心价值可控、高效与可协作实践SDD短期内看似增加了“写规范”的额外步骤但长期来看它从多个维度带来了显著的回报提升产出的确定性与质量规范是唯一的事实来源。AI基于明确的规范生成代码其输出的一致性、正确率会大幅提高。因为模糊空间被压缩了AI“自由发挥”导致跑偏的概率降低。同时由于规范中包含了验收测试我们可以立即对生成代码进行验证快速发现偏差。实现人机与人人之间的高效对齐在团队中规范成为一个中立的、可讨论的媒介。产品经理、架构师、开发者可以围绕规范进行评审和修改确保所有人对需求的理解一致。之后无论是资深工程师还是AI来执行实现都基于同一份蓝图减少了沟通误解和返工。赋能自动化与持续集成结构化的规范特别是机器可读的格式如OpenAPI Spec、Protobuf、或自定义的DSL可以直接作为自动化工具的输入。我们可以构建流水线提交规范 - AI生成代码草案 - 自动运行规范中的验收测试 - 生成报告或自动合并。这极大地压缩了从设计到可测试代码的周期。积累可复用的领域知识资产规范本身是项目宝贵的知识库。它们记录了系统为什么这样设计、某个业务规则的具体含义。这些规范可以被新加入的成员学习也可以被复用于类似的新功能开发甚至可以作为训练专属领域AI模型的优质数据。降低对特定AI工具或提示词的依赖你的核心资产是“规范”而不是针对某个AI模型如ChatGPT-4、Claude-3精心调校的提示词。只要AI模型能理解你的规范格式你就可以切换模型或工具而不会对生产流程造成颠覆性影响。3. 实践框架如何落地Spec-Driven Development理论说再多不如看看具体怎么操作。SDD不是一个僵化的流程而是一套可以适配不同团队习惯的实践框架。下面我以一个常见的后端API开发场景为例拆解一个完整的SDD循环。3.1 第一步编写机器与人皆可读的规范这是SDD的起点也是最需要投入智慧的一步。规范的形式可以多样自然语言增强文档在Markdown或Wiki中用结构化的段落描述需求并明确标出输入/输出示例、错误案例和验收条件。关键是要严格避免“可能”、“大概”、“通常”这类词汇。结构化数据格式对于API直接使用OpenAPI Specification (Swagger)或AsyncAPI。它们能精确定义路径、方法、参数、请求/响应体、状态码本身就是一份极佳的规范。测试代码即规范这是TDD/BDD的延伸。在写实现代码前先写出完整的、会失败的验收测试例如用Pytest、JUnit、Cucumber。这些测试用例就是对功能行为最精确的规范。自定义DSL领域特定语言对于复杂或特有的业务逻辑可以设计一套简单的DSL来描述规则。DSL更贴近业务语言且易于被解析和转换为其他形式。实操示例创建一个“用户注册”API端点我们选择“自然语言增强文档 OpenAPI片段”作为规范载体。首先在项目的/specs/目录下创建一个user_registration.md文件# 规范用户注册API **功能描述**接收用户提供的邮箱、密码和用户名在系统中创建新用户账户。 **约束与规则** 1. 邮箱必须符合RFC 5322标准且在全系统唯一。 2. 密码长度至少8位必须包含大写字母、小写字母和数字。 3. 用户名长度在3-20字符之间只能包含字母、数字和下划线且唯一。 4. 注册成功后需向用户邮箱发送一封验证邮件邮件发送可异步处理不影响API主流程返回。 5. 所有用户输入必须进行清理防止XSS攻击。 **接口契约OpenAPI 3.0.0片段** yaml paths: /api/v1/users: post: summary: 注册新用户 requestBody: required: true content: application/json: schema: $ref: #/components/schemas/UserRegistrationRequest responses: 201: description: 用户创建成功 content: application/json: schema: $ref: #/components/schemas/UserResponse 400: description: 请求参数无效如邮箱格式错误、密码强度不足、用户名重复等 content: application/json: schema: $ref: #/components/schemas/ErrorResponse 409: description: 资源冲突如邮箱已被注册 content: application/json: schema: $ref: #/components/schemas/ErrorResponse components: schemas: UserRegistrationRequest: type: object required: - email - password - username properties: email: type: string format: email example: userexample.com password: type: string format: password minLength: 8 example: Str0ngPss username: type: string minLength: 3 maxLength: 20 pattern: ^[a-zA-Z0-9_]$ example: new_user_123 UserResponse: type: object properties: id: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 email: type: string username: type: string createdAt: type: string format: date-time ErrorResponse: type: object properties: error: type: string example: EMAIL_ALREADY_EXISTS message: type: string example: The provided email is already registered.验收测试用例Gherkin语法示例Feature: 用户注册 Scenario: 使用有效信息成功注册 Given 系统数据库是空的 When 我向 /api/v1/users 发送POST请求JSON体为 { email: testexample.com, password: ValidPass123, username: testuser } Then 响应状态码应为 201 And 响应体应包含一个有效的UUID id And 响应体中的 email 字段应为 testexample.com And 响应体中的 username 字段应为 testuser And 数据库应存在一条对应的用户记录且密码已被哈希存储 And 邮件发送队列中应有一封发给 testexample.com 的验证邮件 Scenario: 使用已注册邮箱注册应失败 Given 系统中已存在邮箱为 existingexample.com 的用户 When 我尝试用同一邮箱注册 Then 响应状态码应为 409 And 响应体的 error 字段应为 EMAIL_ALREADY_EXISTS这份规范已经足够清晰无论是人类开发者还是AI都能明确知道要构建什么。 ### 3.2 第二步将规范转化为AI提示 有了规范下一步就是引导AI基于它来生成代码。这里的关键是**构造一个包含完整上下文的提示Prompt**。你不能只把规范扔给AI说“实现它”。你需要告诉AI你的技术栈、项目结构、以及你期望的代码风格。 **给AI的提示词示例**你是一个经验丰富的Python后端工程师使用FastAPI框架和SQLAlchemy ORM。请根据以下规范实现用户注册API端点。项目上下文项目使用Python 3.11 FastAPI SQLAlchemy 2.0 Pydantic V2。数据库模型位于app/models/user.py其中User模型已有字段id (UUID), email (String, unique), username (String, unique), hashed_password (String), is_active (Boolean), created_at (DateTime)。密码哈希使用passlib库的bcrypt算法。依赖项get_db会话依赖已定义在app/dependencies.py中。工具函数app/utils/security.py中有verify_password和get_password_hash函数。邮件服务app/services/email.py中有EmailService类其send_verification_email(user_id: UUID)方法会将任务推送到Redis队列。错误处理使用app/exceptions.py中自定义的HTTPException子类如ConflictException。请严格遵循以下规范文件中的要求 这里粘贴或附上user_registration.md中的全部内容特别是OpenAPI schema和验收用例你的任务在app/api/v1/endpoints/users.py中创建register_user路由函数。在app/schemas/user.py中创建对应的Pydantic模型UserRegistrationRequest, UserResponse。确保实现所有业务规则邮箱格式、密码强度、唯一性校验等。实现规范的错误处理400 409。代码需包含适当的日志记录使用app/core/logging中的logger。生成的代码必须能通过提供的验收测试用例你可以描述如何验证。请输出完整的、可运行的代码文件内容。这个提示词提供了丰富的上下文将AI的“创造力”引导到解决具体问题的正确方向上大大减少了它做出不合理假设或使用错误技术栈的概率。 ### 3.3 第三步生成、审查与迭代 AI会根据你的提示生成代码。**你绝不能直接复制粘贴** 生成的代码需要经过严格的审查 1. **功能审查**快速阅读代码看其逻辑是否完全符合规范。重点检查边界条件处理、错误处理、安全措施如密码哈希、输入清理。 2. **集成审查**检查生成的代码是否与你的项目现有结构、命名约定、导入风格无缝集成。AI可能会用错依赖项版本或忽略项目特定的配置。 3. **运行验收测试**这是最关键的一步。立即运行规范中定义的验收测试或根据AI生成的代码描述编写对应的自动化测试。如果测试失败分析原因是规范有歧义还是AI理解有误 4. **迭代优化**如果测试失败或审查发现问题不要直接手动修改代码。首先**回头修改你的规范或提示词**。可能是规范描述不清也可能是提示词遗漏了关键约束。修正后让AI重新生成。这个过程本身就是在打磨你的规范和提示工程能力。 **实操心得**在这个阶段我习惯把AI当成一个“超级实习生”。它出活很快但经验不足需要你导师给出极其明确、无歧义的指令规范并仔细检查它的作业。几次迭代后你和AI的配合会越来越默契你写的规范质量也会越来越高。 ### 3.4 第四步将规范与代码同步纳入CI/CD 理想的SDD流程应该是自动化的。我们可以通过工具将规范文件与代码库关联起来。 * **规范即代码**将OpenAPI spec、测试用例文件等纳入版本控制如Git。 * **生成代码的验证**在CI/CD流水线中添加一个步骤每当规范文件/specs/目录发生变化时自动触发AI代码生成或更新并自动运行关联的验收测试。如果测试失败流水线报错阻止合并。 * **反向同步**如果因为其他原因直接修改了实现代码需要有机制如通过测试、或人工检查来确保代码仍然符合原始规范必要时更新规范文档以反映实际实现。 这套机制确保了“规范”永远是权威来源避免了代码与设计文档逐渐脱节的经典问题。 ## 4. 工具链与最佳实践让SDD事半功倍 SDD的理念不依赖于特定工具但合适的工具能极大提升效率。 ### 4.1 规范编写与管理工具 * **Swagger Editor / Stoplight Studio**用于可视化编辑和验证OpenAPI规范非常适合API优先的开发模式。 * **Cucumber / Behave**支持用Gherkin语言编写可执行的验收测试规范非常适合BDD团队。 * **Notion / Confluence 自定义模板**用团队协作平台管理规范文档通过模板来强制要求包含必要章节如接口契约、验收标准、非功能需求。 * **定制化的DSL与解析器**对于规则引擎、配置系统等可以开发简单的内部DSL并用脚本将其转换为API文档或测试用例。 ### 4.2 AI提示与生成工作流工具 * **Claude Desktop / Cursor IDE / Windsurf**这些新一代的AI编程IDE支持将项目文件作为上下文能更好地处理复杂的、多文件的生成任务。你可以将规范文件直接拖入对话上下文。 * **自制脚本**编写一个Python脚本读取规范文件按照预设模板组装成结构化的提示词然后调用OpenAI或Anthropic的API并将结果输出到指定文件位置。这可以实现一定程度的自动化。 * **GitHub Copilot with Context**在代码库中精心编写 SPEC.md 或 README.md 文件Copilot在给出建议时会参考这些上下文。 ### 4.3 最佳实践与避坑指南 1. **从简单功能开始**不要一开始就试图用SDD设计整个微服务架构。从一个独立的API端点、一个工具函数、一个数据处理脚本开始积累编写有效规范的经验。 2. **规范要可测试**这是黄金法则。如果你写的规范无法转化为一个或多个具体的、可自动验证的测试用例那么它很可能还不够清晰。“系统应该高性能”是模糊的“API在95%的请求下响应时间应低于200ms”是可测试的。 3. **人是最终的责任人**AI是强大的执行者但规范的质量、架构的决策、代码的最终审核责任永远在人类工程师。SDD是增强你的能力而不是取代你的判断。 4. **警惕“规范膨胀”**避免过度设计。规范应该描述“做什么”和“做成什么样”而不是详细规定“每一步怎么做”。给AI和有经验的开发者留出合理的实现自由度。 5. **建立团队共识**SDD需要团队共同接受这种“先设计后实现”的文化。特别是产品经理和QA他们需要参与到规范的编写和评审中确保业务需求被准确转化。 6. **处理模糊地带**有些复杂业务逻辑确实难以用结构化语言完全厘清。这时可以在规范中标注“决策点”并附上几个可能的实现方案及其利弊分析让AI生成多个选项供人类选择。 ## 5. 常见问题与挑战 在实践中你肯定会遇到一些挑战以下是我和团队踩过的一些坑以及应对思路 **Q1写规范的时间比直接写代码还长这不是降低了效率吗** **A**对于极其简单、一次性的任务确实可能如此。但对于任何有维护需求、需要协作、或逻辑复杂的功能前期在规范上的投入会在后期成倍收回成本。它减少了返工、调试、扯皮的时间。更重要的是规范是可复用的资产下次类似功能可以直接修改复用而代码则很难直接复制。 **Q2AI生成的代码质量参差不齐还是需要大量修改怎么办** **A**这通常意味着你的规范或提示词不够好。把每次修改都看作对规范和提示词的反馈。分析AI在哪里出了错是漏了约束还是上下文不足迭代优化你的“输入”而不是总去修补“输出”。同时将生成的代码与高质量代码库对比总结模式并把这些模式比如错误处理模板、日志格式明确写入规范或提示词。 **Q3如何保证生成的代码符合项目特定的架构和设计模式** **A**在提示词中提供最强的上下文。包括 * 关键架构文件的示例如展示一个现有的、符合标准的API端点是怎么写的。 * 项目依赖注入是如何工作的。 * 日志、监控、配置管理的标准做法。 * 直接给出“请模仿 app/api/v1/endpoints/products.py 中 create_product 函数的风格和结构来实现”。 **Q4非功能性需求如性能、安全如何在规范中体现** **A**对于性能可以在规范中定义明确的SLI/SLO如延迟、吞吐量并说明压力测试场景。对于安全必须明确列出安全要求如“所有用户输入必须经过XSS过滤”、“数据库查询必须使用参数化绑定防止SQL注入”、“密码必须使用bcrypt哈希存储”。更好的做法是在项目中有统一的安全中间件或工具函数并在提示词中要求AI使用它们。 **Q5SDD适合前端UI开发吗** **A**当然适合但规范的形式会不同。对于UI组件规范可以是 * **Storybook stories**描述组件在不同状态加载、空数据、错误下的样子。 * **Figma设计稿标注**提供精确的尺寸、颜色、字体、间距、交互状态。 * **交互原型**定义用户操作流点击A弹出B提交后跳转C。 * **可访问性A11y要求**明确ARIA标签、键盘导航、屏幕阅读器支持等。 然后你可以用提示词让AI如GPT-4V结合Figma或Claude根据设计稿生成对应的React/Vue组件代码并确保满足可访问性规范。 Spec-Driven Development 不是银弹但它为混乱的AI辅助开发提供了一条通往秩序和可控性的路径。它的本质是将软件工程中久经考验的“设计先行”原则适配到了人机协作的新时代。当你开始习惯为每个功能先写下一份清晰的“契约”时你会发现AI不再是那个偶尔会给出惊喜但更多是带来惊吓的“黑盒”而是一个真正可靠、高效的执行伙伴。控制权始终在你手中。
相关文章
Day03｜用生产硬核笔记逆向解构《DDIA》第三章：从存储引擎走向分布式状态机
文章目录 Day03｜用生产硬核笔记逆向解构《DDIA》第三章：从存储引擎走向分布式状态机 0. 案例原文 / 关联原文链接映射 1. Day03 总纲：Storage and Retrieval 的真正主线 2. 案例一：WAL / binlog / redo / archive log —— 日志是状态机复制的唯一可信输入 2.1 案例原文链接…
Claude Mythos事件：AI自动化漏洞挖掘如何重塑安全攻防格局
1. 从“营销噱头”到行业警钟：Claude Mythos事件深度解析 昨天，Anthropic的一则公告在安全圈和AI圈投下了一颗重磅炸弹。如果放在一年前，这听起来绝对像是某种精心策划的营销炒作：他们发布了一个名为Claude Mythos的新模型&#x…
告别理论！用Python+NetworkX实战5种图采样算法（附完整代码与避坑指南）
告别理论！用PythonNetworkX实战5种图采样算法（附完整代码与避坑指南）在社交网络分析、推荐系统或生物信息学领域，处理大规模图数据时，直接操作整个图结构往往效率低下且资源消耗巨大。图采样技术就像一把精准的手术刀&…
《重构：改善既有代码的设计》阅读笔记
重构：改善既有代码的设计序言原著作者和我——也就是写这篇阅读笔记的人的观点并不完全相同。比如作者认为只要函数名取得好就不需要注释，甚至以此认为只要是需要注释的代码就可以封装成一个函数哪怕只有一行代码，我却认为英文的函数名再好也…
OPC中国是什么？
一文读懂AI智能体时代的一人公司开源社区随着 ChatGPT、DeepSeek、Claude、Gemini 等 AI 大模型的快速发展，越来越多人开始意识到，一个全新的时代正在到来。过去，人们讨论的是互联网、电商、自媒体，而现在，越来越多的人…
用单文件驱动AI实现代码自治：从任务分解到闭环执行的工程实践
1. 项目概述：一个文件如何让AI代码“活”起来最近在折腾AI编程助手时，我一直在思考一个问题：我们每天让Claude、GPT这类模型生成大量代码片段，但这些代码往往只是躺在编辑器里的“死文本”。它们需要你手动复制、粘贴、创建文件、…
SMBGhost (CVE-2020-0796) 复现命令速查表
一、核心信息漏洞名称：SMBGhost / CVE-2020-0796目标系统：Windows 10 1903/1909 x64（10.0.18362.x，未打 KB4551762 补丁）权限结果：直接获取 NT AUTHORITY\SYSTEM 最高权限关键环境：Metasploit F…
C2000 SCI -异步串口模块学习笔记
1. SCI 是什么SCI 全称 Serial Communications Interface，可以理解为 TI C2000 里的 UART 串口模块。STM32：USART / UART TI C2000：SCI常见引脚：SCITXD：发送 SCIRXD：接收2. SCI 系统框图3. SCI 常用功能功能…
从零构建本地语音AI助手：架构设计、模型选型与实战优化
1. 项目概述：为什么我们需要一个本地语音AI助手？最近几年，AI助手已经无处不在，从手机里的语音助手到智能音箱，它们确实方便。但用久了，你可能会发现一些问题：你的对话数据去了哪里？为…
LVGL绘制平滑曲线避坑指南：为什么你的贝塞尔函数有毛刺？
LVGL绘制平滑曲线避坑指南：为什么你的贝塞尔函数有毛刺？ 在嵌入式GUI开发中，贝塞尔曲线是实现流畅动画和优雅界面的核心工具。但许多开发者在使用LVGL绘制曲线时，总会遇到令人头疼的锯齿和毛刺问题。这背后隐藏着嵌入式设备特有的…
告别手动输入！用Burpsuite插件captcha-killer-modified+ddddocr，5分钟搞定登录爆破验证码
自动化验证码识别实战：Burpsuite与ddddocr的高效联动方案验证码机制作为现代Web应用的基础安全防线，其对抗自动化攻击的能力直接影响系统安全性。但在安全测试领域，验证码往往成为效率瓶颈——传统手工识别方式让渗透测试人员每天浪费数小时在…
中国AI岗位暴涨12倍，13种你没听过的AI岗位
2026年，中国AI岗位数量同比增长12倍，AI科学家月薪高达13.7万，高性能计算工程师出现“7个岗位抢1个人”的荒诞场面。与此同时，数据录入、基础财务分析、一线客服等岗位大幅下降。全球范围内，AI/ML岗位招聘量同比增长88%…
施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录
更多请点击： https://codechina.net 第一章：施工现场安全事故预警准确率达94.6%？——解密某央企AI Agent边缘计算部署架构与3个月落地实录 在华北某大型地铁盾构施工现场，一套轻量化AI Agent系统于2024年Q2完成全栈部署ÿ…
附录 B：术语表
本术语表面向“从 MM 到 HMM”专栏阅读过程中的快速查阅。它不是内核 API 手册，而是把文章中反复出现的概念放到同一张地图上：先给出直观含义，再说明它在 Linux MM/HMM 语境里的作用。建议阅读方式： 初读专栏时，把它当…
Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表·行业首曝）
更多请点击： https://kaifayun.com 第一章：Midjourney渐变美学的神经渲染原理（附RGB-HSV-LCH三空间渐变映射对照表行业首曝） Midjourney 的渐变美学并非传统插值实现，而是由其隐式神经渲染器（Implicit Neu…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…