教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载导读本文基于 easy-vibe 开源仓库中 Spec Coding 章节文档 展开系统讲解 AI 编程从随心所欲的 Vibe Coding向规范驱动的 Spec CodingSpec-Driven Development, SDD演进的完整脉络。你将理解 Sean Grove 在 AI Engineer Worlds Fair 2025 上提出的代码是意图的有损投影这一核心论断掌握在 Claude Code 中用CLAUDE.md、.claude/rules/、/plan落地规范即代码工作流的四阶段方法并学会一套先用 Vibe 探路、再用 Spec 交付的混合策略让 AI 生成的代码从快速但脆弱升级为结构化、可测试、可审计的生产级实现。Spec Coding 的核心思想一切皆 Markdown在深入 Spec Coding 之前需要先理解 Claude Code 的底层设计哲学一切皆 Markdown。在 Claude Code 的设计理念中过程记录、信息传递甚至与模型的对话都可以是 MarkdownCLAUDE.md承载项目约定的 Markdown 文档.claude/rules/一组分层的 Markdown 规则文件集合specs/用 Markdown 描述的功能需求会话历史Claude Code 的聊天记录本身就是 Markdown 格式AGENTS.md定义 Agent 行为的 Markdown 指令这正是 Spec Coding 的核心规范本身就是代码。当你用 Markdown 写下需求、设计决策和验收标准时你已经在写代码——AI 会阅读这段 Markdown然后生成真正的实现。Josh Beckman 对 Grove 演讲的总结精准地捕捉了这一点Software engineering (and lawmaking and legal review) is specification repair. 软件工程以及立法和法律审查就是规范修复。在 Claude Code 中这个规范修复过程是修改 Markdown - AI 阅读 Markdown - 生成/修改代码 - 验证结果。整个工作流由 Markdown 驱动。值得注意的是这一理念在当前仓库中同样有迹可循easy-vibe 本身就是一个Markdown 即内容的 VitePress 文档项目仓库根目录同时维护着 AGENTS.md 与 CLAUDE.md——前者用 Markdown 定义仓库指南项目结构、构建命令、编码规范、提交规范为 AI Agent 提供行为层面的规范约束正是下文用规范驾驭 Agent的活例。1. Sean Grove 的 The New Code一场改变思维方式的演讲2025 年OpenAI 研究员Sean Grove在 AI Engineer Worlds Fair 上发表了题为The New Code的演讲震撼了整个开发者社区。他提出了一个颠覆性的观点70 年来我们一直在写代码来解决问题但代码只是意图的有损投影——规范Specification才是真正的新代码。这场演讲催生了一种新的开发范式Spec Coding——让规范文档而不是代码成为开发的核心产物并让 AI 从规范中生成代码。Grove 此前创立了 GraphQL 开发者工具公司 OneGraph后被 Netlify 收购目前在 OpenAI 从事对齐推理Alignment Reasoning工作——帮助将高层意图转化为可执行的规范与评估标准。他的背景解释了为何这场演讲如此关注意图 - 规范 - 执行的转化链路。1.1 核心论点代码是意图的有损投影Grove 演讲的核心概念可以用一句话概括Code is a lossy projection of intent.代码是意图的有损投影。这句话的含义是什么当你在脑海中有一个想法并将其转化为代码时大量上下文在过程中丢失了——你为什么选择这个方案、考虑了哪些权衡、哪些约束是重要的。最终代码只保留了怎么做而丢失了为什么应该这样做。这就像把一本书压缩成一条推文——信息密度急剧下降原始意图被严重削弱。1.2 编程的本质是沟通Grove 提出了一个简单而深刻的观点If you can communicate effectively, you can program. 如果你能有效沟通你就能编程。他认为实际的编码工作只占开发的10%–20%。其余 80% 是围绕需求和目标的结构化沟通——理解用户想要什么、与团队对齐解决方案、定义验收标准、处理边界情况。这意味着编程能力的核心不是对某门语言语法的掌握而是将模糊意图转化为精确描述的能力。1.3 谁写规范谁就是程序员这是 Grove 最具颠覆性的观点Whoever writes the spec - be it a PM, a lawmaker, an engineer, a marketer - is now the programmer. 谁写规范——无论是产品经理、立法者、工程师还是市场人员——谁就是现在的程序员。随着 AI 越来越擅长将规范转化为代码真正的编程工作从写代码转向写规范。谁能最精确地表达意图谁就能成为最有价值的程序员。1.4 规范可以拥有类代码的工具链Grove 指出规范可以像代码一样拥有完整的工具链Specs actually give us a very similar toolchain, but its targeted at intentions rather than syntax. 规范实际上给了我们非常相似的工具链只不过它瞄准的是意图而非语法。组合Composition规范可以像代码模块一样模块化、可组合测试Testing规范可以内嵌单元测试验证行为是否符合预期Lint规范中的歧义语言可以被检测出来就像 linter 发现语法问题一致性检查Consistency checks跨部门的规范可以被检查一致性类似类型检查器1.5 OpenAI Model Spec活生生的证据Grove 用 OpenAI 自己的Model Spec文档作为证据。当 OpenAI 发现一个谄媚Sycophancy问题时他们并没有重新训练模型而是修改了规范文档。这个变更自动传播到整个系统问题得到修复。这证明了一个关键点规范本身可以像可执行代码一样运作。修改规范等价于修改行为而不需要触碰一行传统代码。Josh Beckman 的总结再次点题Software engineering (and lawmaking and legal review) is specification repair. 软件工程以及立法和法律审查就是规范修复。2. Spec Coding规范即代码2.1 什么是 Spec CodingSpec Coding也称为规范驱动开发Spec-Driven Development, SDD是一种将规范文档作为开发核心产物的方法论。其核心思想是先清晰写出规范然后让 AI 从规范生成代码。规范是事实的源头source of truth代码只是从中派生的实现产物。Robert C. Martin 在Clean Code中的经典论述在 AI 时代重新焕发生机Specifying requirements so precisely that a machine can execute them is programming. 将需求精确到机器可以执行的程度这就是编程。2.2 Vibe Coding 与 Spec Coding 对比维度Vibe CodingSpec Coding方式即兴提示迭代式来回对话先写完整规范再生成代码最适合原型、黑客松、探索生产系统、团队协作、企业级工作代码质量快但脆弱结构化、可测试、可审计一次成功率不稳定以 95% 为目标可复用性一次性提示规范可跨项目复用安全性容易遗漏在规范层面内置文档缺失或总是滞后规范即文档持续维护团队协作依赖个人提示技巧共享规范共享标准两者并非对立关系。正如 Brad Jolicoeur 指出的Clever engineers will even use vibe coding as a first step to generate the initial draft of a specification. 聪明的工程师甚至会先用 Vibe Coding 作为第一步生成规范的初稿。2.3 Spec Coding 的三层规范结构Red Hat 的工程师总结了一个实用的三层规范模型第 1 层功能规范What用自然语言描述预期结果回答它应该做什么## 用户认证功能 ### 用户故事 - 作为新用户我希望用邮箱注册 - 作为已注册用户我希望用邮箱和密码登录 - 作为忘记密码的用户我希望通过邮箱重置密码 ### 验收标准 - 注册时校验邮箱格式和密码强度 - 连续 5 次登录失败后锁定账户 15 分钟 - 密码重置链接 30 分钟内有效第 2 层语言无关规范How —— 架构层定义数据结构、架构模式和安全需求## 技术设计 ### 数据模型 - users 表id, email, password_hash, created_at, locked_until - sessions 表id, user_id, token, expires_at ### API 设计 - POST /api/auth/register - 201 Created - POST /api/auth/login - 200 OK JWT - POST /api/auth/reset-password - 202 Accepted ### 安全需求 - 密码使用 bcryptcost factor 12 - JWT 15 分钟过期refresh token 7 天过期 - 所有端点启用速率限制第 3 层语言相关规范How —— 实现层定义版本要求、测试框架和文档标准## 实现约束 ### 技术栈 - 运行时Node.js 20 - 框架Express 5 - ORMPrisma - 测试Vitest ### 代码约定 - 使用 TypeScript strict mode - 使用自定义 AppError 类处理错误 - 所有 API 端点需要 JSDoc 注释这三层结构从做什么到架构怎么做再到代码怎么写层层递进、职责分明让 AI 在生成代码时有据可依。3. 在 Claude Code 中实践 Spec Coding理解了理论之后下一个问题是如何在 Claude Code 中落地。Claude Code 的设计哲学天然契合 Spec Coding——它的CLAUDE.md、Rules 目录和/plan命令都是规范驱动开发的表现形式。相关基础能力可参见本仓库的 Claude Code 快速上手指南其中详细介绍了CLAUDE.md的创建、/init、/plan、.claudeignore等核心配置。当 OpenAI 自己用 Codex 构建项目时也采用了类似的模式用AGENTS.md文件作为规范来引导 AI Agent。他们最重要的经验是当 Agent 遇到困难时把它当作一个信号——识别缺失的是什么工具、护栏还是文档然后把它补充到仓库中。这与 Spec Coding 完美契合规范是活的人工制品living artifacts应当持续演进。Augment Code 的研究支持同样的结论可执行的规范能保持准确因为 AI Agent 直接根据它们生成代码这形成了一种强制机制——过时的规范会产生坏掉的实现。这意味着规范不会像传统文档那样腐烂。3.1 第一步用CLAUDE.md建立项目规范CLAUDE.md是你项目的活规范。每次 Claude Code 启动时都会读取该文件这相当于给 AI 一本持久的项目手册。结合 Spec Coding 的语境它的角色更加重要——它不仅仅是一个配置文件而是项目规范的入口点。LogRocket 的工程师强调为 AI Agent 提供坚实的上下文至关重要因为它能防止幻觉和低效。没有规范AI Agent 可能对项目做出大量不可控的修改。CLAUDE.md就是提供这种坚实上下文的第一道防线。# 电商项目规范 ## 项目定位 一个面向中小商户的 SaaS 电商平台支持多店铺、多渠道支付。 ## 架构决策 - 前后端分离采用 API-first 设计 - 微服务后端架构服务间通过消息队列通信 - 读写数据库分离 ## 核心约束 - 所有金额以分为单位的整数存储避免浮点精度问题 - 订单状态机必须严格遵循待支付 - 已支付 - 已发货 - 已完成 - 支付相关端点必须幂等Aviator 团队总结了规范应捕获的关键信息——这正是你的CLAUDE.md应该覆盖的内容输入输出格式与数据类型业务规则与边界情况系统依赖与约束性能与可扩展性需求错误处理与安全需求3.2 第二步用 Rules 目录管理分层规范当项目增长后单一的CLAUDE.md会不够用。此时使用.claude/rules/目录来组织分层规范。这正是 Augment Code 所称的可执行规范理念规范不是静态文档而是被 AI Agent 直接消费的活指令。将规则拆分到 Rules 目录后每条规则文件只会在编辑相关文件时被加载既节省 token 又保持精确。Tessl 的工程师发现将需求拆分成结构化文档——用 PRD 定义是什么和为什么用技术规范定义怎么做——有助于防止 AI 在长对话中积累混乱并显著提升输出一致性。.claude/rules/ ├── 00-architecture.md # 架构规则全局 ├── 01-security.md # 安全规则全局 ├── 10-api-design.md # API 设计规则 ├── 11-frontend-patterns.md # 前端模式规则 ├── 12-database.md # 数据库规则 └── 20-testing.md # 测试规则每条规则文件可以通过 frontmatter 指定其作用范围--- globs: - src/api/**/*.ts - src/services/**/*.ts --- # API 设计规则 ## 路由设计 - RESTful 风格使用复数名词/api/v1/orders - 嵌套资源最多两层深/api/v1/users/123/orders ## 响应格式 - 成功{ data, pagination? } - 失败{ error: { code, message, details? } } ## 必须遵守 - 所有写操作需要认证 - 所有列表端点必须支持分页 - 敏感操作必须写审计日志这样当 Claude Code 编辑 API 相关文件时它会自动加载这条规范确保生成的代码符合标准。3.3 第三步用/plan落地 Specify - Plan - Tasks - Implement标准的 Spec Coding 工作流是一个四阶段循环。GitHub Spec Kit 将其标准化为 Specify - Plan - Tasks - Implement而 Claude Code 的/plan命令天然支持这一流程其基础用法详见 Claude Code 快速上手指南 中的技术 4/plan。SpecThis 团队强调了一个关键原则在 Agent 运行前定义边界——在任何代码变更发生之前就知道应该改变什么。这正是/plan的价值。阶段 1Specify明确规范先清楚地写出你想构建什么不要急于写代码/plan 我需要实现一个订单退款功能。规范如下 功能需求 - 发货前用户可以申请全额退款 - 发货后 7 天内用户可以申请退货退款 - 退款需要管理员审批 验收标准 - 退款金额不能超过订单实际支付金额 - 退款状态机已申请 - 已批准 - 退款中 - 已退款 - 退款完成后恢复库存 - 全程记录每一步操作阶段 2Plan生成计划Claude 会根据你的规范生成技术方案 退款功能实现计划 1. 数据模型设计 - 创建 refunds 表 - 为订单状态机添加退款相关状态 2. API 设计 - POST /api/orders/:id/refund - 申请退款 - PUT /api/refunds/:id/approve - 批准退款 - GET /api/refunds - 退款列表 3. 业务逻辑 - 退款资格校验 - 退款金额计算 - 库存恢复逻辑 4. 集成 - 对接支付提供商的退款 API - 发送退款通知阶段 3Tasks拆解任务将计划拆分成可以独立执行的小任务并为每个任务给出清晰的完成标准。阶段 4Implement实现一次实现一个任务每完成一个就验证一个。3.4 真实示例用 Spec Coding 构建用户通知系统用一个完整示例对比 Vibe Coding 和 Spec Coding。Orchestrator.dev 的数据显示在 2025 年 Stack Overflow 调查中84% 的开发者正在使用或计划使用 AI 工具但只有 22% 对结果满意46% 认为准确性问题突出。Spec Coding 正是缩小这种满意度差距的关键。Vibe Coding 方式你构建一个通知功能 AI[立即开始写代码生成一个简单的通知列表] 你它应该支持已读和未读 AI[修改代码添加 read 字段] 你还需要多种通知类型 AI[再次修改添加 type 字段] 你它应该也能推送到手机 AI[进行大规模重写之前的结构不再合适……]结果经过四轮修改架构被一次次推翻重建代码随着时间的推移越来越混乱。Spec Coding 方式先写一个规范文档specs/notification.md# 用户通知系统规范 ## 功能需求 1. 支持三种渠道站内通知、邮件通知和推送通知 2. 通知类型系统公告、订单状态、促销活动、安全告警 3. 用户可以按渠道和类型配置通知偏好 4. 支持已读/未读状态和批量标记已读 ## 数据模型 - notifications 表id, user_id, type, channel, title, content, is_read, created_at - notification_preferences 表user_id, type, channel, enabled ## API 设计 - GET /api/notifications?typeis_read - 获取通知列表分页 - PUT /api/notifications/:id/read - 标记已读 - PUT /api/notifications/read-all - 全部标记已读 - GET /api/notification-preferences - 获取偏好设置 - PUT /api/notification-preferences - 更新偏好设置 ## 验收标准 - 未读通知数量实时更新 - 通知列表支持无限滚动 - 推送通知延迟 3 秒 - 偏好修改立即生效然后在 Claude Code 中specs/notification.md 根据这份规范实现用户通知系统。 先从数据模型开始然后实现 API最后构建前端组件。 每个模块完成后暂停等我确认后再继续。结果一次到位、架构清晰无需反复推倒重建。3.5 用 Superpowers 强化 Spec Coding在 Superpowers 章节 中我们了解了 Superpowers 技能系统一个由 Jesse Vincent 创建的开源 Agent Skills 框架通过强制 TDD、代码审查等纪律让 AI 产出工程级代码。Spec Coding 与 Superpowers 是天然搭档Spec Coding 阶段匹配的 Superpowers 技能定义规范brainstorming- 用苏格拉底式提问澄清需求技术规划writing-plans- 将规范拆解为小任务增量实现test-driven-development- TDD 红绿重构质量验证code-reviewverification-before-completion组合使用示例specs/notification.md 使用 TDD 根据这份规范实现通知系统 完成后帮我做代码审查这一条指令同时激活了 Spec Coding 工作流和 Superpowers 的 TDD、Code Review 技能形成完整的工程级开发流程。3.6 规范的版本控制与持续演进The Vibe Coding Substack 提出了一个重要观点Specs are now code规范即代码。如果规范是代码就应该像代码一样管理版本控制将规范文件纳入 Git与代码一起提交变更追踪规范的每次修改都有提交记录让你知道谁改了什么、为什么改代码审查规范的变更也应通过 PR 审查保持团队对齐CI 集成规范变更触发自动化测试验证实现是否仍然符合规范在 Claude Code 中这意味着你的CLAUDE.md、.claude/rules/和specs/目录都应该纳入版本控制。Robomotion 的经验是将规范与实现一起版本化可以防止漂移drift并让一切保持可审计。OpenAI 的 Harness Engineering 实践也印证了这一点他们的AGENTS.md文件本身就是由 Codex 编写的并随着项目演进持续更新。当 Agent 遇到困难时解决方案不是直接修改代码而是让 Codex 更新规范本身——从而形成规范的自我修复循环。4. 混合策略从 Vibe 到 Spec 的渐进迁移行业共识不是放弃 Vibe Coding而是为正确的场景选择正确的方法。4.1 何时使用 Vibe Coding验证一个想法是否可行30 分钟内做出原型探索不熟悉的技术或框架黑客松或内部演示一次性脚本或工具4.2 何时使用 Spec Coding生产级功能开发多人协作项目需要长期维护的代码安全、支付、数据等敏感领域API 设计与系统集成4.3 推荐的渐进式工作流阶段 1Vibe 探索用 Vibe Coding 快速验证想法。此时不写规范也不担心代码质量构建一个简单的通知弹窗让我们看看它的体验如何阶段 2细化规范可行性确认后把探索过程中的经验整理成规范。你甚至可以请 AI 帮忙基于我们刚构建的通知功能原型 帮我整理一份正式的功能规范文档 包括数据模型、API 设计和验收标准阶段 3用 Spec 重建基于这份规范用 Spec Coding 重新实现生产级版本specs/notification.md 根据规范从头实现不要参考之前的原型代码这个工作流的优势清晰用 Vibe Coding 的速度验证方向用 Spec Coding 的质量交付产品。Robomotion 总结得很好The spec is the source of truth. The AI generated output is the draft implementation. Validation is not optional. 规范是事实的源头。AI 生成的输出是草稿实现。验证不是可选项。5. 常见问题Q1Spec Coding 会不会太慢写规范确实需要前期投入。但 Greg Ceccarelli 的团队用 Spec Coding 实现了三个人四周交付一个完整的 macOS 产品——这在传统开发中几乎不可能。早期花在写规范上的时间会在后期通过更少的返工、更少的 bug 和更低的沟通成本被回收。Q2规范应该详细到什么程度Robomotion 的建议是一份高质量的规范可能只有一页。关键在于它是否回答了这八个问题我们在自动化什么输入是什么输出是什么约束是什么失败模式是什么安全需求是什么性能需求是什么哪些测试能证明它有效Q3如果 AI 只做了规范里写的事而漏掉显而易见的功能怎么办这确实是 Spec Coding 的一个局限。GitHub Spec Kit 用户的反馈是AI 只会严格且仅做规范里写的事。解决方案是在规范中增加一个非功能需求小节在那里列出通用期望如错误处理、日志记录和可访问性。或者把全局规则放在CLAUDE.md中。Q4小项目也需要 Spec Coding 吗不需要。Spec Coding 最适合生产级项目团队协作项目需要长期维护的项目对于快速原型、一次性脚本和学习实验Vibe Coding 更合适。Q5如何让团队接受 Spec Coding先选一个小功能做试点。让团队看到 Spec Coding 如何减少返工、提高一次成功率。2025 年 Stack Overflow 调查显示84% 的开发者正在使用或计划使用 AI 工具但只有 22% 对结果满意——Spec Coding 正是提升这种满意度的关键。6. 总结从 Vibe Coding 到 Spec Coding 的转变不是一场革命而是一次进化。Sean Grove 在 The New Code 中说得非常清楚70 年来我们写代码来解决问题现在我们应该写规范来生成代码。代码是意图的有损投影而规范能完整捕获意图、上下文和约束。对于使用 Claude Code 的开发者来说这种转变已经在发生你写的CLAUDE.md就是你的项目规范你配置的 Rules 目录就是你的分层规范系统你用/plan做的规划就是 Specify - Plan - Tasks 流程结合 Superpowers 的 TDD 与 Code Review 就构成了完整的 Spec Coding 工作流核心要点Vibe Coding 适合探索和原型Spec Coding 适合生产和协作规范是事实的源头代码是从中生产的实现产物写规范的能力 编程能力沟通能力比语法能力更重要从小处开始只要把CLAUDE.md写好你就已经迈出了 Spec Coding 的第一步延伸阅读仓库内部章节Claude Code 快速上手指南掌握CLAUDE.md、/init、/plan、.claudeignore等基础配置与技巧Claude Code Superpowers 工程级开发了解 brainstorming、writing-plans、test-driven-development 等技能如何与 Spec Coding 协同Claude Agent Teams 完全指南下一章将学习如何让多个 AI 实例像真实开发团队一样协作仓库 AGENTS.mdeasy-vibe 自身用 Markdown 定义 Agent 行为指南的实例仓库 CLAUDE.mdeasy-vibe 的项目级规范文件可作为CLAUDE.md写法的参考赞分享教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载相关推荐easy-vibe 深度指南从 Vibe Coding 到 Spec Coding让规范文档成为 AI 编程的新代码easy vibe 深度指南从 Vibe Coding 到 Spec Coding让规范文档成为 AI 编程的新代码 Code is a lossy pr教程文档人工智能Vibe CodingXUnity自动翻译器打破语言障碍的终极游戏翻译解决方案XUnity自动翻译器打破语言障碍的终极游戏翻译解决方案 还在为看不懂外语游戏而烦恼吗XUnity自动翻译器就是你的救星这个强大的开源工具能够实时翻译Un教程文档人工智能Vibe CodingSpec Coding with Claude Code in Easy-Vibe: From Vibe Coding to Specifications as the New Source CodeSpec Coding with Claude Code in Easy Vibe: From Vibe Coding to Specifications as教程文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 Vibe Coding 到 Spec Coding：以规范（Spec）为中心的 AI 编程范式（easy-vibe 实战指南）
教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载导读本文基于 easy-vibe 开源仓库中 Spec Coding 章节文档 展开系统讲解 AI 编程从随心所欲的 Vibe Coding向规范驱动的 Spec CodingSpec-Driven Development, SDD演进的完整脉络。你将理解 Sean Grove 在 AI Engineer Worlds Fair 2025 上提出的代码是意图的有损投影这一核心论断掌握在 Claude Code 中用CLAUDE.md、.claude/rules/、/plan落地规范即代码工作流的四阶段方法并学会一套先用 Vibe 探路、再用 Spec 交付的混合策略让 AI 生成的代码从快速但脆弱升级为结构化、可测试、可审计的生产级实现。Spec Coding 的核心思想一切皆 Markdown在深入 Spec Coding 之前需要先理解 Claude Code 的底层设计哲学一切皆 Markdown。在 Claude Code 的设计理念中过程记录、信息传递甚至与模型的对话都可以是 MarkdownCLAUDE.md承载项目约定的 Markdown 文档.claude/rules/一组分层的 Markdown 规则文件集合specs/用 Markdown 描述的功能需求会话历史Claude Code 的聊天记录本身就是 Markdown 格式AGENTS.md定义 Agent 行为的 Markdown 指令这正是 Spec Coding 的核心规范本身就是代码。当你用 Markdown 写下需求、设计决策和验收标准时你已经在写代码——AI 会阅读这段 Markdown然后生成真正的实现。Josh Beckman 对 Grove 演讲的总结精准地捕捉了这一点Software engineering (and lawmaking and legal review) is specification repair. 软件工程以及立法和法律审查就是规范修复。在 Claude Code 中这个规范修复过程是修改 Markdown - AI 阅读 Markdown - 生成/修改代码 - 验证结果。整个工作流由 Markdown 驱动。值得注意的是这一理念在当前仓库中同样有迹可循easy-vibe 本身就是一个Markdown 即内容的 VitePress 文档项目仓库根目录同时维护着 AGENTS.md 与 CLAUDE.md——前者用 Markdown 定义仓库指南项目结构、构建命令、编码规范、提交规范为 AI Agent 提供行为层面的规范约束正是下文用规范驾驭 Agent的活例。1. Sean Grove 的 The New Code一场改变思维方式的演讲2025 年OpenAI 研究员Sean Grove在 AI Engineer Worlds Fair 上发表了题为The New Code的演讲震撼了整个开发者社区。他提出了一个颠覆性的观点70 年来我们一直在写代码来解决问题但代码只是意图的有损投影——规范Specification才是真正的新代码。这场演讲催生了一种新的开发范式Spec Coding——让规范文档而不是代码成为开发的核心产物并让 AI 从规范中生成代码。Grove 此前创立了 GraphQL 开发者工具公司 OneGraph后被 Netlify 收购目前在 OpenAI 从事对齐推理Alignment Reasoning工作——帮助将高层意图转化为可执行的规范与评估标准。他的背景解释了为何这场演讲如此关注意图 - 规范 - 执行的转化链路。1.1 核心论点代码是意图的有损投影Grove 演讲的核心概念可以用一句话概括Code is a lossy projection of intent.代码是意图的有损投影。这句话的含义是什么当你在脑海中有一个想法并将其转化为代码时大量上下文在过程中丢失了——你为什么选择这个方案、考虑了哪些权衡、哪些约束是重要的。最终代码只保留了怎么做而丢失了为什么应该这样做。这就像把一本书压缩成一条推文——信息密度急剧下降原始意图被严重削弱。1.2 编程的本质是沟通Grove 提出了一个简单而深刻的观点If you can communicate effectively, you can program. 如果你能有效沟通你就能编程。他认为实际的编码工作只占开发的10%–20%。其余 80% 是围绕需求和目标的结构化沟通——理解用户想要什么、与团队对齐解决方案、定义验收标准、处理边界情况。这意味着编程能力的核心不是对某门语言语法的掌握而是将模糊意图转化为精确描述的能力。1.3 谁写规范谁就是程序员这是 Grove 最具颠覆性的观点Whoever writes the spec - be it a PM, a lawmaker, an engineer, a marketer - is now the programmer. 谁写规范——无论是产品经理、立法者、工程师还是市场人员——谁就是现在的程序员。随着 AI 越来越擅长将规范转化为代码真正的编程工作从写代码转向写规范。谁能最精确地表达意图谁就能成为最有价值的程序员。1.4 规范可以拥有类代码的工具链Grove 指出规范可以像代码一样拥有完整的工具链Specs actually give us a very similar toolchain, but its targeted at intentions rather than syntax. 规范实际上给了我们非常相似的工具链只不过它瞄准的是意图而非语法。组合Composition规范可以像代码模块一样模块化、可组合测试Testing规范可以内嵌单元测试验证行为是否符合预期Lint规范中的歧义语言可以被检测出来就像 linter 发现语法问题一致性检查Consistency checks跨部门的规范可以被检查一致性类似类型检查器1.5 OpenAI Model Spec活生生的证据Grove 用 OpenAI 自己的Model Spec文档作为证据。当 OpenAI 发现一个谄媚Sycophancy问题时他们并没有重新训练模型而是修改了规范文档。这个变更自动传播到整个系统问题得到修复。这证明了一个关键点规范本身可以像可执行代码一样运作。修改规范等价于修改行为而不需要触碰一行传统代码。Josh Beckman 的总结再次点题Software engineering (and lawmaking and legal review) is specification repair. 软件工程以及立法和法律审查就是规范修复。2. Spec Coding规范即代码2.1 什么是 Spec CodingSpec Coding也称为规范驱动开发Spec-Driven Development, SDD是一种将规范文档作为开发核心产物的方法论。其核心思想是先清晰写出规范然后让 AI 从规范生成代码。规范是事实的源头source of truth代码只是从中派生的实现产物。Robert C. Martin 在Clean Code中的经典论述在 AI 时代重新焕发生机Specifying requirements so precisely that a machine can execute them is programming. 将需求精确到机器可以执行的程度这就是编程。2.2 Vibe Coding 与 Spec Coding 对比维度Vibe CodingSpec Coding方式即兴提示迭代式来回对话先写完整规范再生成代码最适合原型、黑客松、探索生产系统、团队协作、企业级工作代码质量快但脆弱结构化、可测试、可审计一次成功率不稳定以 95% 为目标可复用性一次性提示规范可跨项目复用安全性容易遗漏在规范层面内置文档缺失或总是滞后规范即文档持续维护团队协作依赖个人提示技巧共享规范共享标准两者并非对立关系。正如 Brad Jolicoeur 指出的Clever engineers will even use vibe coding as a first step to generate the initial draft of a specification. 聪明的工程师甚至会先用 Vibe Coding 作为第一步生成规范的初稿。2.3 Spec Coding 的三层规范结构Red Hat 的工程师总结了一个实用的三层规范模型第 1 层功能规范What用自然语言描述预期结果回答它应该做什么## 用户认证功能 ### 用户故事 - 作为新用户我希望用邮箱注册 - 作为已注册用户我希望用邮箱和密码登录 - 作为忘记密码的用户我希望通过邮箱重置密码 ### 验收标准 - 注册时校验邮箱格式和密码强度 - 连续 5 次登录失败后锁定账户 15 分钟 - 密码重置链接 30 分钟内有效第 2 层语言无关规范How —— 架构层定义数据结构、架构模式和安全需求## 技术设计 ### 数据模型 - users 表id, email, password_hash, created_at, locked_until - sessions 表id, user_id, token, expires_at ### API 设计 - POST /api/auth/register - 201 Created - POST /api/auth/login - 200 OK JWT - POST /api/auth/reset-password - 202 Accepted ### 安全需求 - 密码使用 bcryptcost factor 12 - JWT 15 分钟过期refresh token 7 天过期 - 所有端点启用速率限制第 3 层语言相关规范How —— 实现层定义版本要求、测试框架和文档标准## 实现约束 ### 技术栈 - 运行时Node.js 20 - 框架Express 5 - ORMPrisma - 测试Vitest ### 代码约定 - 使用 TypeScript strict mode - 使用自定义 AppError 类处理错误 - 所有 API 端点需要 JSDoc 注释这三层结构从做什么到架构怎么做再到代码怎么写层层递进、职责分明让 AI 在生成代码时有据可依。3. 在 Claude Code 中实践 Spec Coding理解了理论之后下一个问题是如何在 Claude Code 中落地。Claude Code 的设计哲学天然契合 Spec Coding——它的CLAUDE.md、Rules 目录和/plan命令都是规范驱动开发的表现形式。相关基础能力可参见本仓库的 Claude Code 快速上手指南其中详细介绍了CLAUDE.md的创建、/init、/plan、.claudeignore等核心配置。当 OpenAI 自己用 Codex 构建项目时也采用了类似的模式用AGENTS.md文件作为规范来引导 AI Agent。他们最重要的经验是当 Agent 遇到困难时把它当作一个信号——识别缺失的是什么工具、护栏还是文档然后把它补充到仓库中。这与 Spec Coding 完美契合规范是活的人工制品living artifacts应当持续演进。Augment Code 的研究支持同样的结论可执行的规范能保持准确因为 AI Agent 直接根据它们生成代码这形成了一种强制机制——过时的规范会产生坏掉的实现。这意味着规范不会像传统文档那样腐烂。3.1 第一步用CLAUDE.md建立项目规范CLAUDE.md是你项目的活规范。每次 Claude Code 启动时都会读取该文件这相当于给 AI 一本持久的项目手册。结合 Spec Coding 的语境它的角色更加重要——它不仅仅是一个配置文件而是项目规范的入口点。LogRocket 的工程师强调为 AI Agent 提供坚实的上下文至关重要因为它能防止幻觉和低效。没有规范AI Agent 可能对项目做出大量不可控的修改。CLAUDE.md就是提供这种坚实上下文的第一道防线。# 电商项目规范 ## 项目定位 一个面向中小商户的 SaaS 电商平台支持多店铺、多渠道支付。 ## 架构决策 - 前后端分离采用 API-first 设计 - 微服务后端架构服务间通过消息队列通信 - 读写数据库分离 ## 核心约束 - 所有金额以分为单位的整数存储避免浮点精度问题 - 订单状态机必须严格遵循待支付 - 已支付 - 已发货 - 已完成 - 支付相关端点必须幂等Aviator 团队总结了规范应捕获的关键信息——这正是你的CLAUDE.md应该覆盖的内容输入输出格式与数据类型业务规则与边界情况系统依赖与约束性能与可扩展性需求错误处理与安全需求3.2 第二步用 Rules 目录管理分层规范当项目增长后单一的CLAUDE.md会不够用。此时使用.claude/rules/目录来组织分层规范。这正是 Augment Code 所称的可执行规范理念规范不是静态文档而是被 AI Agent 直接消费的活指令。将规则拆分到 Rules 目录后每条规则文件只会在编辑相关文件时被加载既节省 token 又保持精确。Tessl 的工程师发现将需求拆分成结构化文档——用 PRD 定义是什么和为什么用技术规范定义怎么做——有助于防止 AI 在长对话中积累混乱并显著提升输出一致性。.claude/rules/ ├── 00-architecture.md # 架构规则全局 ├── 01-security.md # 安全规则全局 ├── 10-api-design.md # API 设计规则 ├── 11-frontend-patterns.md # 前端模式规则 ├── 12-database.md # 数据库规则 └── 20-testing.md # 测试规则每条规则文件可以通过 frontmatter 指定其作用范围--- globs: - src/api/**/*.ts - src/services/**/*.ts --- # API 设计规则 ## 路由设计 - RESTful 风格使用复数名词/api/v1/orders - 嵌套资源最多两层深/api/v1/users/123/orders ## 响应格式 - 成功{ data, pagination? } - 失败{ error: { code, message, details? } } ## 必须遵守 - 所有写操作需要认证 - 所有列表端点必须支持分页 - 敏感操作必须写审计日志这样当 Claude Code 编辑 API 相关文件时它会自动加载这条规范确保生成的代码符合标准。3.3 第三步用/plan落地 Specify - Plan - Tasks - Implement标准的 Spec Coding 工作流是一个四阶段循环。GitHub Spec Kit 将其标准化为 Specify - Plan - Tasks - Implement而 Claude Code 的/plan命令天然支持这一流程其基础用法详见 Claude Code 快速上手指南 中的技术 4/plan。SpecThis 团队强调了一个关键原则在 Agent 运行前定义边界——在任何代码变更发生之前就知道应该改变什么。这正是/plan的价值。阶段 1Specify明确规范先清楚地写出你想构建什么不要急于写代码/plan 我需要实现一个订单退款功能。规范如下 功能需求 - 发货前用户可以申请全额退款 - 发货后 7 天内用户可以申请退货退款 - 退款需要管理员审批 验收标准 - 退款金额不能超过订单实际支付金额 - 退款状态机已申请 - 已批准 - 退款中 - 已退款 - 退款完成后恢复库存 - 全程记录每一步操作阶段 2Plan生成计划Claude 会根据你的规范生成技术方案 退款功能实现计划 1. 数据模型设计 - 创建 refunds 表 - 为订单状态机添加退款相关状态 2. API 设计 - POST /api/orders/:id/refund - 申请退款 - PUT /api/refunds/:id/approve - 批准退款 - GET /api/refunds - 退款列表 3. 业务逻辑 - 退款资格校验 - 退款金额计算 - 库存恢复逻辑 4. 集成 - 对接支付提供商的退款 API - 发送退款通知阶段 3Tasks拆解任务将计划拆分成可以独立执行的小任务并为每个任务给出清晰的完成标准。阶段 4Implement实现一次实现一个任务每完成一个就验证一个。3.4 真实示例用 Spec Coding 构建用户通知系统用一个完整示例对比 Vibe Coding 和 Spec Coding。Orchestrator.dev 的数据显示在 2025 年 Stack Overflow 调查中84% 的开发者正在使用或计划使用 AI 工具但只有 22% 对结果满意46% 认为准确性问题突出。Spec Coding 正是缩小这种满意度差距的关键。Vibe Coding 方式你构建一个通知功能 AI[立即开始写代码生成一个简单的通知列表] 你它应该支持已读和未读 AI[修改代码添加 read 字段] 你还需要多种通知类型 AI[再次修改添加 type 字段] 你它应该也能推送到手机 AI[进行大规模重写之前的结构不再合适……]结果经过四轮修改架构被一次次推翻重建代码随着时间的推移越来越混乱。Spec Coding 方式先写一个规范文档specs/notification.md# 用户通知系统规范 ## 功能需求 1. 支持三种渠道站内通知、邮件通知和推送通知 2. 通知类型系统公告、订单状态、促销活动、安全告警 3. 用户可以按渠道和类型配置通知偏好 4. 支持已读/未读状态和批量标记已读 ## 数据模型 - notifications 表id, user_id, type, channel, title, content, is_read, created_at - notification_preferences 表user_id, type, channel, enabled ## API 设计 - GET /api/notifications?typeis_read - 获取通知列表分页 - PUT /api/notifications/:id/read - 标记已读 - PUT /api/notifications/read-all - 全部标记已读 - GET /api/notification-preferences - 获取偏好设置 - PUT /api/notification-preferences - 更新偏好设置 ## 验收标准 - 未读通知数量实时更新 - 通知列表支持无限滚动 - 推送通知延迟 3 秒 - 偏好修改立即生效然后在 Claude Code 中specs/notification.md 根据这份规范实现用户通知系统。 先从数据模型开始然后实现 API最后构建前端组件。 每个模块完成后暂停等我确认后再继续。结果一次到位、架构清晰无需反复推倒重建。3.5 用 Superpowers 强化 Spec Coding在 Superpowers 章节 中我们了解了 Superpowers 技能系统一个由 Jesse Vincent 创建的开源 Agent Skills 框架通过强制 TDD、代码审查等纪律让 AI 产出工程级代码。Spec Coding 与 Superpowers 是天然搭档Spec Coding 阶段匹配的 Superpowers 技能定义规范brainstorming- 用苏格拉底式提问澄清需求技术规划writing-plans- 将规范拆解为小任务增量实现test-driven-development- TDD 红绿重构质量验证code-reviewverification-before-completion组合使用示例specs/notification.md 使用 TDD 根据这份规范实现通知系统 完成后帮我做代码审查这一条指令同时激活了 Spec Coding 工作流和 Superpowers 的 TDD、Code Review 技能形成完整的工程级开发流程。3.6 规范的版本控制与持续演进The Vibe Coding Substack 提出了一个重要观点Specs are now code规范即代码。如果规范是代码就应该像代码一样管理版本控制将规范文件纳入 Git与代码一起提交变更追踪规范的每次修改都有提交记录让你知道谁改了什么、为什么改代码审查规范的变更也应通过 PR 审查保持团队对齐CI 集成规范变更触发自动化测试验证实现是否仍然符合规范在 Claude Code 中这意味着你的CLAUDE.md、.claude/rules/和specs/目录都应该纳入版本控制。Robomotion 的经验是将规范与实现一起版本化可以防止漂移drift并让一切保持可审计。OpenAI 的 Harness Engineering 实践也印证了这一点他们的AGENTS.md文件本身就是由 Codex 编写的并随着项目演进持续更新。当 Agent 遇到困难时解决方案不是直接修改代码而是让 Codex 更新规范本身——从而形成规范的自我修复循环。4. 混合策略从 Vibe 到 Spec 的渐进迁移行业共识不是放弃 Vibe Coding而是为正确的场景选择正确的方法。4.1 何时使用 Vibe Coding验证一个想法是否可行30 分钟内做出原型探索不熟悉的技术或框架黑客松或内部演示一次性脚本或工具4.2 何时使用 Spec Coding生产级功能开发多人协作项目需要长期维护的代码安全、支付、数据等敏感领域API 设计与系统集成4.3 推荐的渐进式工作流阶段 1Vibe 探索用 Vibe Coding 快速验证想法。此时不写规范也不担心代码质量构建一个简单的通知弹窗让我们看看它的体验如何阶段 2细化规范可行性确认后把探索过程中的经验整理成规范。你甚至可以请 AI 帮忙基于我们刚构建的通知功能原型 帮我整理一份正式的功能规范文档 包括数据模型、API 设计和验收标准阶段 3用 Spec 重建基于这份规范用 Spec Coding 重新实现生产级版本specs/notification.md 根据规范从头实现不要参考之前的原型代码这个工作流的优势清晰用 Vibe Coding 的速度验证方向用 Spec Coding 的质量交付产品。Robomotion 总结得很好The spec is the source of truth. The AI generated output is the draft implementation. Validation is not optional. 规范是事实的源头。AI 生成的输出是草稿实现。验证不是可选项。5. 常见问题Q1Spec Coding 会不会太慢写规范确实需要前期投入。但 Greg Ceccarelli 的团队用 Spec Coding 实现了三个人四周交付一个完整的 macOS 产品——这在传统开发中几乎不可能。早期花在写规范上的时间会在后期通过更少的返工、更少的 bug 和更低的沟通成本被回收。Q2规范应该详细到什么程度Robomotion 的建议是一份高质量的规范可能只有一页。关键在于它是否回答了这八个问题我们在自动化什么输入是什么输出是什么约束是什么失败模式是什么安全需求是什么性能需求是什么哪些测试能证明它有效Q3如果 AI 只做了规范里写的事而漏掉显而易见的功能怎么办这确实是 Spec Coding 的一个局限。GitHub Spec Kit 用户的反馈是AI 只会严格且仅做规范里写的事。解决方案是在规范中增加一个非功能需求小节在那里列出通用期望如错误处理、日志记录和可访问性。或者把全局规则放在CLAUDE.md中。Q4小项目也需要 Spec Coding 吗不需要。Spec Coding 最适合生产级项目团队协作项目需要长期维护的项目对于快速原型、一次性脚本和学习实验Vibe Coding 更合适。Q5如何让团队接受 Spec Coding先选一个小功能做试点。让团队看到 Spec Coding 如何减少返工、提高一次成功率。2025 年 Stack Overflow 调查显示84% 的开发者正在使用或计划使用 AI 工具但只有 22% 对结果满意——Spec Coding 正是提升这种满意度的关键。6. 总结从 Vibe Coding 到 Spec Coding 的转变不是一场革命而是一次进化。Sean Grove 在 The New Code 中说得非常清楚70 年来我们写代码来解决问题现在我们应该写规范来生成代码。代码是意图的有损投影而规范能完整捕获意图、上下文和约束。对于使用 Claude Code 的开发者来说这种转变已经在发生你写的CLAUDE.md就是你的项目规范你配置的 Rules 目录就是你的分层规范系统你用/plan做的规划就是 Specify - Plan - Tasks 流程结合 Superpowers 的 TDD 与 Code Review 就构成了完整的 Spec Coding 工作流核心要点Vibe Coding 适合探索和原型Spec Coding 适合生产和协作规范是事实的源头代码是从中生产的实现产物写规范的能力 编程能力沟通能力比语法能力更重要从小处开始只要把CLAUDE.md写好你就已经迈出了 Spec Coding 的第一步延伸阅读仓库内部章节Claude Code 快速上手指南掌握CLAUDE.md、/init、/plan、.claudeignore等基础配置与技巧Claude Code Superpowers 工程级开发了解 brainstorming、writing-plans、test-driven-development 等技能如何与 Spec Coding 协同Claude Agent Teams 完全指南下一章将学习如何让多个 AI 实例像真实开发团队一样协作仓库 AGENTS.mdeasy-vibe 自身用 Markdown 定义 Agent 行为指南的实例仓库 CLAUDE.mdeasy-vibe 的项目级规范文件可作为CLAUDE.md写法的参考赞分享教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载相关推荐easy-vibe 深度指南从 Vibe Coding 到 Spec Coding让规范文档成为 AI 编程的新代码easy vibe 深度指南从 Vibe Coding 到 Spec Coding让规范文档成为 AI 编程的新代码 Code is a lossy pr教程文档人工智能Vibe CodingXUnity自动翻译器打破语言障碍的终极游戏翻译解决方案XUnity自动翻译器打破语言障碍的终极游戏翻译解决方案 还在为看不懂外语游戏而烦恼吗XUnity自动翻译器就是你的救星这个强大的开源工具能够实时翻译Un教程文档人工智能Vibe CodingSpec Coding with Claude Code in Easy-Vibe: From Vibe Coding to Specifications as the New Source CodeSpec Coding with Claude Code in Easy Vibe: From Vibe Coding to Specifications as教程文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考