Claude Code规范驱动编程

Amazon 在 2025.7.14 发布了kiro预览版。与Cursor、Trae（AI编程IDE）或者Claude Code、Gemini CLI（AI控制台编程工具）有所不同，这款新的AI编程工具最大的特色是集成了所谓的“规范驱动编程”（Spec-Driven Programming）。即：开发前先编写好需求、设计、任务文档，再基于文档进行代码生成。与之对应的，则是“氛围编程”（Vibe Coding）。这篇文章将简要描述一下两者的不同，以及在Claude Code中实现规范驱动编程的步骤。

氛围编程及其问题

所谓的“一句话需求”，即属于“氛围编程”的一种，因为需求提的比较随意，所以得到的结果也比较随意。AI会按照自认为最优的方式去处理，而结果可能不符合项目的技术栈、代码规范、目录结构等。这种方式的工作流，是一个类似下面这样的迭代过程：

1. 提出一个粗略的需求，例如：帮我实现一个用户评论功能。
2. AI给出一个自己的实现方案
3. 开发者对于最终的代码结果不满意，然后针对上一步的结果提出修改要求
4. AI再次根据修改要求，去优化第2步生成的代码
5. 如此往复...

造成的结果是：效率不稳定，有时候可以快速、高效地得到预期结果；有时候又需要进行反复地调优和修改。很多人在尝试了此种编程方式后，经历了不少挫败，甚至很快地得出了：“AI的编程效率还不如自己编码来得快”的结论。

我也意识到了这个问题，要想AI编程跑得更顺，那么简明扼要、清晰的需求说明文档则很有必要。上一篇文章：Claude Code提示词模板.html，就是想要一定程度上解决这个问题。但这篇文章提供的解决方式比较初级和简单，仅仅是个人使用过程中的一点总结。

Amazon 则想要更系统地解决这个问题，于是推出了 Kiro 这款AI编程IDE，它的解决方案便是：规范驱动编程。

规范驱动编程

简单来说，有点类似软件开发中的瀑布流工作模式，将需求从想法到实现分为三个阶段：需求、设计、任务。并且在每个阶段都生成对应的文档。有了这些具体的文档之后，AI基于这些详细的文档进行代码编写，就不容易跑偏，能够更好地保证代码质量。

这三个阶段，对应了具体的三个文档。假设我们需要开发一个 文章评论 功能，那么就会在 specs/文章评论 文件夹下，创建对应的三个文件：

需求阶段：requirements.md

将模糊需求（如“添加评论功能”）转化为结构化用户故事与验收标准，采用 ​​EARS语法​​（Easy Approach to Requirements Syntax）消除歧义。

简单来说，就是用户或产品经理视角，文档主要表达的是：想要做什么

# 用户故事：创建待办 WHEN 用户输入标题并点击“添加” THEN 系统生成带时间戳的新待办项，状态为“未完成”

设计阶段：design.md

主要包括了 技术架构、时序图及实现注意事项等。例如：数据流图、API端点设计、数据库Schema及错误处理机制 等。

简单来说，就是软件架构师视角，文档主要表达的是：如何做，要做成什么样子

## API设计 POST /api/todos Request: { title: string } Response: { id: string, status: "open" }

实现计划阶段：tasks.md

将工作分解为独立且可追踪的任务，确保每个任务都有明确的描述和预期结果。

简单来说，就是开发工程师视角，文档主要表达的是：分成哪些具体可量化的步骤去做

- [ ] 实现文章评论接口 - [ ] 编写控制器 - [ ] 添加单元测试

编码执行阶段

这一阶段，文档规范都已经就绪，可以让LLM进行编码了，同时，可以根据需要更新和完善前面的3个规范文档。

在 Claude Code 中集成规范驱动编程

本来想体验一下kiro，但遗憾的是：kiro现在还只是预览版，并且已经结束了新用户的注册，只能加入到watilist中。不过好在，已经有人将这一套工作流集成到了Claude Code中，其 Github 地址在这里：claude-code-spec-workflow（后面简称 spec-workflow）。

除了集成需求处理流程以外，spec-workflow 还集成了 steering（导航系统），通俗来说，就是更高维度的，关于项目的概览，并且在后续的代码生成任务中，将这些项目概览包含在上下文中。执行 /spec-steering-setup 将会向你提出一系列关于项目的问题，基于你的回复，会生成3个文件：product.md（产品定位）、tech.md（技术选型）、structure.md（项目结构）。

除了需求的处理，spec-workflow 还包含了bug的处理，同样是基于bug处理的流程：bug汇报、bug分析和定位、bug修复、bug验证。对应3个规范文件：bug-report.md、bug-analysis.md 和 bug-verification.md 。

claude-code-spec-workflow 试用体验

不得不说，如果说我自己我编撰的文档太过简略，那么按照claude-code-spec-workflow 的工作流进行开发，又过于繁琐，spec-workflow 基于 commands 和 templates 来生成文档，而这些commands和templates本身又非常详尽（包含了很多的步骤）。最终容易造成下面的几个效应：

1. 花费过多时间编写或修改文档（毕竟很多文档也是生成的），且部分文档内容可能重复
2. 需要处理的步骤和上下文增多，Claude Code响应的周期变长（需要往复和LLM进行交互），进而整体的开发周期变长
3. 消耗大量的tokens，完成任务的成本显著提高

所以，我打算采用一种折中的方式，做几方面的改变：

1. 不使用spec-workflow的命令来执行工作流和生成文档，但会参考这些命令中的要求，来编写文档
2. 对于项目层级的三个文档：product.md（产品定位）、tech.md（技术选型）、structure.md（项目结构），我将其整合进CLAUDE.md中（也就是执行/init后生成的文件）
3. 对于需求和Bug，我提出需求描述，然后结合模板文件，生成出最终文档，然后再对文档进行二次修改，以减少文档编写的工作。

模板文件

claude-code-spec-workflow 提供了一系列的模板文件。位于 .claude/templates 下，除了模板文件，其 commands 文件也值得一看，可以窥见其是通过哪些提示词来引导LLM进行工作。这部分，我将展示部分的文件内容。

spec-create.md 命令文件

因为我们不再使用spec-create命令来执行完整的工作流，但是这个命令里包含的内容，在我们后续自己编写AI提示词时还是可以起到很大的参考作用的，所以值得仔细阅读一下。其实不止是 spec-create 命令，commands目录下的所有其他命令，都值得一读，而且它们也都是纯文本格式的markdown文件。

# Spec 创建命令 按照完整的规范驱动工作流创建新的功能规范。 ## 使用方法 ``` /spec-create <feature-name> [description] ``` ## 工作流理念 您是专门从事规范驱动开发的AI助手。您的角色是引导用户通过系统化的功能开发方法，确保质量、可维护性和完整性。 ### 核心原则 - **结构化开发**: 遵循顺序阶段，不跳过步骤 - **需要用户批准**: 每个阶段必须在继续之前得到明确批准 - **原子化实施**: 在实施期间一次执行一个任务 - **需求可追溯性**: 所有任务必须引用特定需求 - **测试驱动重点**: 在整个过程中优先考虑测试和验证 ## 完整工作流序列 **关键**: 严格遵循此序列 - 不要跳过步骤： 1. **需求阶段** (第1阶段) - 使用模板创建 requirements.md - 获得用户批准 - 进入设计阶段 2. **设计阶段** (第2阶段) - 使用模板创建 design.md - 获得用户批准 - 进入任务阶段 3. **任务阶段** (第3阶段) - 使用模板创建 tasks.md - 获得用户批准 - **询问用户是否要生成任务命令** (是/否) - 如果是：运行 `claude-code-workflow generate-task-commands {spec-name}` 4. **实施阶段** (第4阶段) - 使用生成的任务命令或单独执行任务 ## 指导说明 您正在通过完整工作流帮助创建新的功能规范。按顺序遵循这些阶段： **工作流序列**: 需求 → 设计 → 任务 → 生成命令 **不要**在所有阶段完成并批准之前运行任务命令生成。 ### 初始设置 1. **创建目录结构** - 创建 `.claude/specs/{feature-name}/` 目录 - 初始化空的 requirements.md、design.md 和 tasks.md 文件 2. **一次性加载所有上下文（分层上下文加载）** 在开始时加载完整上下文 - 这将在整个创建过程中使用： ```bash # 加载指导文档（如果可用） claude-code-workflow get-steering-context # 加载规范模板以获取结构指导 claude-code-workflow get-template-context spec ``` **存储此上下文** - 您将在所有阶段中引用它而不重新加载。 3. **分析现有代码库** (在开始任何阶段之前) - **搜索类似功能**: 查找与新功能相关的现有模式 - **识别可重用组件**: 查找可以利用的工具、服务、钩子或模块 - **审查架构模式**: 了解当前项目结构、命名约定和设计模式 - **与指导文档交叉引用**: 确保发现与记录的标准一致 - **查找集成点**: 确定新功能将与现有系统连接的位置 - **记录发现**: 记录可以重用的内容 vs 需要从头构建的内容 ## 第1阶段：需求创建 **遵循的模板**: 使用上面预加载上下文中的需求模板（不要重新加载）。 ### 需求过程 1. **生成 requirements.md 文档** - 精确使用需求模板结构 - **与 product.md 保持一致**: 确保需求支持产品愿景和目标 - 以"作为[角色]，我想要[功能]，以便[获得收益]"格式创建用户故事 - 以 EARS 格式编写验收标准（WHEN/IF/THEN 语句） - 考虑边缘情况和技术约束 - **引用指导文档**: 注明需求如何与产品愿景保持一致 ### 需求模板使用 - **阅读并遵循**: 使用以下方式加载需求模板： ```bash # Windows: claude-code-workflow get-content "C:\path\to\project\.claude\templates\requirements-template.md" # macOS/Linux: claude-code-workflow get-content "/path/to/project/.claude/templates/requirements-template.md" ``` - **使用精确结构**: 遵循模板的所有部分和格式 - **包含所有部分**: 不要省略任何必需的模板部分 ### 需求验证和批准 - **自动验证**: 使用 `spec-requirements-validator` 代理验证需求： ``` 使用 spec-requirements-validator 代理验证 {feature-name} 规范的需求文档。 代理应该： 1. 使用 get-content 脚本读取需求文档： # Windows: claude-code-workflow get-content "C:\path\to\project\.claude\specs\{feature-name}\requirements.md" # macOS/Linux: claude-code-workflow get-content "/path/to/project/.claude/specs/{feature-name}/requirements.md" 2. 根据所有质量标准（结构、用户故事、验收标准等）进行验证 3. 检查与指导文档（product.md、tech.md、structure.md）的一致性 4. 提供具体的反馈和改进建议 5. 将整体质量评为 PASS、NEEDS_IMPROVEMENT 或 MAJOR_ISSUES 如果验证失败，使用反馈在呈现给用户之前改进需求。 ``` - **仅在验证通过或改进后呈现给用户** - **呈现已验证的需求文档和代码库分析摘要** - 询问："需求看起来好吗？如果是，我们可以进入设计阶段。" - **关键**: 在进入第2阶段之前等待明确批准 - 只接受明确的肯定回答："是"、"批准"、"看起来不错"等 - 如果用户提供反馈，进行修订并再次请求批准 ## 第2阶段：设计创建 ... 太长了，这里仅示范一部分

requirements.md 需求模板

这个模板是需求的核心模板。

# 需求文档 ## 介绍 [提供功能的简要概述、其目的以及对用户的价值] ## 与产品愿景的一致性 [解释此功能如何支持product.md中概述的目标] ## 需求 ### 需求1 **用户故事**: 作为[角色]，我想要[功能]，以便[获得收益] #### 验收标准 1. 当[事件]发生时，[系统]应该[响应] 2. 如果[前提条件]，那么[系统]应该[响应] 3. 当[事件]发生并且[条件]满足时，[系统]应该[响应] ### 需求2 **用户故事**: 作为[角色]，我想要[功能]，以便[获得收益] #### 验收标准 1. 当[事件]发生时，[系统]应该[响应] 2. 如果[前提条件]，那么[系统]应该[响应] ## 非功能性需求 ### 性能 - [性能需求] ### 安全性 - [安全需求] ### 可靠性 - [可靠性需求] ### 可用性 - [可用性需求]

design.md 设计模板

针对需求的设计文档，这里面部分内容，例如 项目结构 和 tech.md 中的内容是重复的。

# 设计文档 ## 概述 [功能的高级描述及其在整体系统中的位置] ## 指导文档对齐 ### 技术标准 (tech.md) [设计如何遵循文档化的技术模式和标准] ### 项目结构 (structure.md) [实施将如何遵循项目组织约定] ## 代码重用分析 [现有代码将被利用、扩展或与此功能集成] ### 要利用的现有组件 - **[组件/工具名称]**: [如何使用] - **[服务/助手名称]**: [如何扩展] ### 集成点 - **[现有系统/API]**: [新功能将如何集成] - **[数据库/存储]**: [数据将如何连接到现有架构] ## 架构 [描述使用的整体架构和设计模式] ```mermaid graph TD A[组件A] --> B[组件B] B --> C[组件C] ``` ## 组件和接口 ### 组件1 - **目的:** [此组件的作用] - **接口:** [公共方法/API] - **依赖:** [它依赖什么] - **重用:** [它构建的现有组件/工具] ### 组件2 - **目的:** [此组件的作用] - **接口:** [公共方法/API] - **依赖:** [它依赖什么] - **重用:** [它构建的现有组件/工具] ## 数据模型 ### 模型1 ``` [用您的语言定义Model1的结构] - id: [唯一标识符类型] - name: [字符串/文本类型] - [根据需要添加其他属性] ``` ### 模型2 ``` [用您的语言定义Model2的结构] - id: [唯一标识符类型] - [根据需要添加其他属性] ``` ## 错误处理 ### 错误场景 1. **场景1:** [描述] - **处理:** [如何处理] - **用户影响:** [用户看到什么] 2. **场景2:** [描述] - **处理:** [如何处理] - **用户影响:** [用户看到什么] ## 测试策略 ### 单元测试 - [单元测试方法] - [要测试的关键组件] ### 集成测试 - [集成测试方法] - [要测试的关键流程] ### 端到端测试 - [E2E测试方法] - [要测试的用户场景]

task.md 任务模板

# 实施计划 ## 任务概述 [实施方法的简要描述] ## 指导文档合规性 [任务如何遵循structure.md约定和tech.md模式] ## 原子任务要求 **每个任务必须满足这些标准以便于代理执行：** - **文件范围**: 最多涉及1-3个相关文件 - **时间限制**: 15-30分钟内可完成 - **单一目的**: 每个任务一个可测试的结果 - **特定文件**: 必须指定要创建/修改的确切文件 - **代理友好**: 清晰的输入输出，最小上下文切换 ## 任务格式指南 - 使用复选框格式：`- [ ] 任务编号. 任务描述` - **指定文件**: 始终包含要创建/修改的确切文件路径 - **包含实施细节**作为要点 - 使用以下方式引用需求：`_Requirements: X.Y, Z.A_` - 使用以下方式引用要利用的现有代码：`_Leverage: path/to/file.ts, path/to/component.tsx_` - 仅关注编码任务（不涉及部署、用户测试等） - **避免宽泛术语**: 任务标题中不使用"系统"、"集成"、"完成" ## 好坏任务示例 ❌ **坏示例（太宽泛）**： - "实现身份验证系统"（影响多个文件，多个目的） - "添加用户管理功能"（范围模糊，无文件规范） - "构建完整的仪表板"（太大，多个组件） ✅ **好示例（原子化）**： - "在models/user.py中创建具有邮箱/密码字段的User模型" - "使用bcrypt在utils/auth.py中添加密码哈希工具" - "在components/LoginForm.tsx中创建具有邮箱/密码输入的LoginForm组件" ## 任务 - [ ] 1. 在src/types/feature.ts中创建核心接口 - 文件: src/types/feature.ts - 为功能数据结构定义TypeScript接口 - 扩展base.ts中的现有基础接口 - 目的: 为功能实施建立类型安全 - _Leverage: src/types/base.ts_ - _Requirements: 1.1_ - [ ] 2. 在src/models/FeatureModel.ts中创建基础模型类 - 文件: src/models/FeatureModel.ts - 实现扩展BaseModel类的基础模型 - 使用现有验证工具添加验证方法 - 目的: 为功能提供数据层基础 - _Leverage: src/models/BaseModel.ts, src/utils/validation.ts_ - _Requirements: 2.1_ - [ ] 3. 向FeatureModel.ts添加特定模型方法 - 文件: src/models/FeatureModel.ts（继续任务2） - 实现创建、更新、删除方法 - 添加外键关系处理 - 目的: 完成CRUD操作的模型功能 - _Leverage: src/models/BaseModel.ts_ - _Requirements: 2.2, 2.3_ - [ ] 4. 在tests/models/FeatureModel.test.ts中创建模型单元测试 - 文件: tests/models/FeatureModel.test.ts - 编写模型验证和CRUD方法的测试 - 使用现有测试工具和测试数据 - 目的: 确保模型可靠性并捕获回归 - _Leverage: tests/helpers/testUtils.ts, tests/fixtures/data.ts_ - _Requirements: 2.1, 2.2_ - [ ] 5. 在src/services/IFeatureService.ts中创建服务接口 - 文件: src/services/IFeatureService.ts - 定义包含方法签名的服务契约 - 扩展基础服务接口模式 - 目的: 为依赖注入建立服务层契约 - _Leverage: src/services/IBaseService.ts_ - _Requirements: 3.1_ - [ ] 6. 在src/services/FeatureService.ts中实施功能服务 - 文件: src/services/FeatureService.ts - 使用FeatureModel创建具体服务实施 - 使用现有错误工具添加错误处理 - 目的: 为功能操作提供业务逻辑层 - _Leverage: src/services/BaseService.ts, src/utils/errorHandler.ts, src/models/FeatureModel.ts_ - _Requirements: 3.2_ - [ ] 7. 在src/utils/di.ts中添加服务依赖注入 - 文件: src/utils/di.ts（修改现有） - 在依赖注入容器中注册FeatureService - 配置服务生命周期和依赖 - 目的: 在整个应用程序中启用服务注入 - _Leverage: src/utils/di.ts中的现有DI配置_ - _Requirements: 3.1_ - [ ] 8. 在tests/services/FeatureService.test.ts中创建服务单元测试 - 文件: tests/services/FeatureService.test.ts - 编写具有模拟依赖的服务方法测试 - 测试错误处理场景 - 目的: 确保服务可靠性和适当的错误处理 - _Leverage: tests/helpers/testUtils.ts, tests/mocks/modelMocks.ts_ - _Requirements: 3.2, 3.3_ - [ ] 4. 创建API端点 - 设计API结构 - _Leverage: src/api/baseApi.ts, src/utils/apiUtils.ts_ - _Requirements: 4.0_ - [ ] 4.1 设置路由和中间件 - 配置应用程序路由 - 添加身份验证中间件 - 设置错误处理中间件 - _Leverage: src/middleware/auth.ts, src/middleware/errorHandler.ts_ - _Requirements: 4.1_ - [ ] 4.2 实施CRUD端点 - 创建API端点 - 添加请求验证 - 编写API集成测试 - _Leverage: src/controllers/BaseController.ts, src/utils/validation.ts_ - _Requirements: 4.2, 4.3_ - [ ] 5. 添加前端组件 - 计划组件架构 - _Leverage: src/components/BaseComponent.tsx, src/styles/theme.ts_ - _Requirements: 5.0_ - [ ] 5.1 创建基础UI组件 - 设置组件结构 - 实施可重用组件 - 添加样式和主题 - _Leverage: src/components/BaseComponent.tsx, src/styles/theme.ts_ - _Requirements: 5.1_ - [ ] 5.2 实施功能特定组件 - 创建功能组件 - 添加状态管理 - 连接到API端点 - _Leverage: src/hooks/useApi.ts, src/components/BaseComponent.tsx_ - _Requirements: 5.2, 5.3_ - [ ] 6. 集成和测试 - 计划集成方法 - _Leverage: src/utils/integrationUtils.ts, tests/helpers/testUtils.ts_ - _Requirements: 6.0_ - [ ] 6.1 编写端到端测试 - 设置E2E测试框架 - 编写用户旅程测试 - 添加测试自动化 - _Leverage: tests/helpers/testUtils.ts, tests/fixtures/data.ts_ - _Requirements: 全部_ - [ ] 6.2 最终集成和清理 - 集成所有组件 - 修复任何集成问题 - 清理代码和文档 - _Leverage: src/utils/cleanup.ts, docs/templates/_ - _Requirements: 全部_

除了上面这些文档以外，还有可以集成到CLAUDE.md中的 product.md、structure.md以及tech.md，这些文件，在安装好spec-workflow后都可以参考一下，这里就不再演示了。

感谢阅读，希望这篇文章能给你带来帮助！