本文作者：Amber，TRAE 产品运营
TRAE 当前已经支持 Spec 功能。本文将从 Vibe Coding 的痛点出发，为大家讲解什么是 Spec，Plan 和 Spec 之间的区别，最后用一个场景案例为大家演示如何使用 Spec 模式，让大家更清晰理解如何用 Spec 驱动开发。
Vibe Coding 的痛点
在介绍什么是 Spec Coding 之前，我们先回到大家都很熟悉的一个概念：Vibe Coding。
在 2025 年初，Vibe Coding 几乎席卷了整个开发者圈子，也让很多从未写过代码的人第一次“上手开发”。那时候最流行的一句话就是： “每个人都可以成为开发者。” ****你只需要用自然语言描述需求，不用太多思考，一路点击“Accept All”，一个应用就能跑起来。但慢慢地你会发现，结果开始和预期越来越偏。
举个例子：
你正在用 TRAE IDE 做 Vibe Coding。一开始一切都很顺利，AI 写代码飞快，项目雏形肉眼可见地长出来。直到中途某个节点，你突然发现哪里不太对劲——文件目录结构被改了、某个模块的实现方式和你想的不一样，甚至它开始实现一些你根本没提过的需求……等你回过神来，已经陷在一堆“能跑但不是你要的”代码屎山里，最后改起来比自己重写还痛苦。
但这并不只是“AI 自作主张”的问题，本质上是上下文带来的限制。大语言模型在长对话中天然容易丢失连贯性。离最初的提示词越远，智能体就越容易开始靠“脑补”来填补空白。任务简单时，这种 Vibe Coding 的副作用还不明显；可一旦项目变复杂，它就会像滚雪球一样，把小偏差放大成大问题。
综合来看，Vibe Coding 面临了以下几点困境：
-
缺乏全局视野： AI 往往只在单文件或局部上下文中改动，难以理解对整体架构的影响，容易出现“局部看着还行、全局一团乱”的情况（类型、依赖、边界错漏等）。
-
代码质量不稳定，容易遗漏边界 case： 实时生成强依赖“当下运气”，主流程大多能跑通，但异常处理、边界条件、空值检查等细节经常被忽略，质量难以稳定达标。
-
迭代容易与技术债累积： 缺少事先沉淀好的实现 Plan，开发过程变成“走一步看一步”，临时打补丁越来越多，决策过程又难追溯，后续迭代很难保持一致性。
-
可追溯性较差： 核心逻辑与权衡散落在对话记录里，没有很好沉淀到 Git 或文档中。一旦需要排查 Bug 或做重构，很难回溯当初“为什么要这么做”。
-
上下文丢失： 每次对话上下文是相对独立的，过一段时间再回来接着改，不仅需要重新向 AI 解释背景，你自己也要重新把当初的设计捋一遍。
-
团队协作困难： 关键信息沉淀在“某个人和 AI 的对话”里，其他成员只能看到最后的代码，看不到中间的设计意图和演进路径。
那么为了解决以上这些困境， Spec Coding 就应运而生。
什么是 Spec Coding
Spec Coding（规范驱动开发，Spec-Driven Development，简称 SDD）是一种新兴的 AI 辅助开发方法论，它将软件规范（Specification）作为开发的核心和真理之源。
与传统的"Vibe Coding"（即时反应式编码）不同，Spec Coding 强调在编写代码之前先建立清晰、结构化的规范文档，然后让 Coding Agent 基于这些规范生成代码。
这种方法论的核心洞察是：我们正在从 “代码是真理之源”转向“意图是真理之源”。 在 AI 时代，规范不再是被束之高阁的静态文档，而是变成了可执行的、活的产物（Living Artifacts），能够直接驱动代码的生成和演进。
一个非常简单的需求，当然可以直接 Vibe Coding，但当你开始尝试做复杂项目时，随着会话变长，智能体往往会逐渐失去对全局的把握。
Spec 就是为了解决这一问题而存在的——它提供一份可以持续维护的实现计划，让人和 AI Agent 在整个开发过程中始终对齐：现在在做什么、接下来要做什么、什么算完成。如果你曾经见过 AI 在项目进行到一半时突然“跑偏”，那么 Spec 就是帮你预防这种情况的那根“安全绳”。
Plan 和 Spec 如何选择
这里引入一个新的概念【 Plan 模式】，简单描述两者的区别：
-
Plan 模式适用于中小型功能开发和模块级重构，生成一份计划文档后直接执行。
-
Spec 模式则面向更复杂的系统级任务，生成完整的三阶段文档组（大纲 + 任务列表 + 验收清单），每个阶段都支持用户确认和 Refine。
-
这两者都可以在 TRAE 中使用「/」符号触发。
很多人看到这里可能会有个疑问：既然 Spec 看上去更系统、更严谨，那我是不是所有项目都应该用 Spec？
答案是不需要。Spec 不是目的本身，它是一种帮你更高效、更可控完成复杂开发的方式。
-
什么时候考虑用 /spec： 从零开始构建复杂项目、范围存在较多不确定性、或者项目会跨越多个开发周期。当 agent 走错方向代价较大的情况出现的时候，应该及时开始用 spec 驱动长任务开发。
-
什么时候考虑用 /plan： 范围清晰、边界明确的任务——比如加功能、部分代码重构、修一个定义清楚的 bug。或者比如给现有 App 加个深色模式，这种情况下 Plan 模式就够了。
本质上，两者背后的逻辑是一致的：无论是一页纸的简短计划，还是一整套完整的 Spec，核心都是——在动手写代码之前，先和 Agent 建立清晰共识。 这些文档既是你的进度追踪工具，又是 AI Agent 在长任务中上下文开始漂移时可以随时“拉回来的锚点”。
有了这个锚点，复杂项目才真正变得可控。你不再需要和 AI 不断拉扯，而是和它站在同一侧，把同一件事情一步步做完。
如何在 TRAE 中使用 Spec
在 TRAE 中输入 /spec，Agent 不会立刻开始写代码，而是先和你一起生成三份文档：
-
项目范围（ spec.md ） 是整个项目的全局概览。你在做什么、为什么要做这个改动、做了哪些决策和权衡、以及明确哪些东西在范围之内。它是整个项目的北极星文档，其他所有东西都围绕着它展开。
-
任务拆解（ tasks.md ） 是 agent 把项目范围具体化的地方。它会把整个 spec 拆成若干个子模块，每个子模块下面有子任务，每个子任务再细化成具体的执行步骤。这是一份详细的、有顺序的实现计划。Agent 在推进项目的过程中会实时勾选任务，你随时都能看到进展在哪里。
-
验证清单（ checklist.md ） 是一份完整性核查表。当 agent 完成全部实现工作之后，它会逐项过一遍这份清单，确认没有遗漏。代码实现、功能验证、测试覆盖……全部对完，项目才算收尾。
这三份文档都不是一次性锁死的，整个开发过程中你随时可以修改和迭代。
Spec vs. 上传文档：有什么不一样？
你可能会想：我也可以给 Agent 上传项目文档或参考资料来提供上下文，那 /spec 还有什么额外的价值？
区别在于主动性。
上传文档是被动的，只是提供了当前项目的背景信息。你把资料丢给 agent，它在需要的时候参考一下。文档本身不会追踪进度，不会拆解任务，也不会在 agent 跑偏的时候主动把它拉回来。
/spec 是更加主动的。它不只是给 agent 提供参考，而是让 agent 和你一起从零生成一套结构化的执行计划。任务有顺序，进度实时勾选，验证清单在最后兜底。整个开发过程中，agent 不是在"参考"这份文档，而是在"执行"它，并且在任何时候你的思路有变化都可以实时“纠偏” agent。
当然，这两者并不互斥。如果你有现成的项目规范或技术文档，完全可以在生成 spec 的时候把背景资料一并提供给 agent，让它在起草项目范围的时候把这些内容纳入进来。
接下来，我们从一个简单的实践出发。
Spec 实践
场景描述： 你现在要从零开始做一个 PWA（Progressive Web App，这个本质上是一种可以安装到任何设备上、支持离线使用的网页应用），带后端邮件发送功能。用户在手机或电脑上填写联系表单，提交后触发一封邮件发送到指定地址。
这种项目用 Vibe 模式十有八九会翻车。前端架构、Service Worker、后端 API、邮件服务集成……如果范围没有提前定清楚，智能体就会替你做一堆你没授权的决定。等你发现问题，往往已经要重新接 API、换不同的集成服务，或者反复跑端到端测试才能把东西对齐。
那我们看看用 Spec 模式，会是什么情况呢？
1️⃣ 和 AI 描述需求
先写一个 prompt："我想做一个支持后端邮件发送的 PWA。用户填写联系表单，提交后触发邮件发送到指定地址。" 然后输入 /spec。
2️⃣ 智能体生成了项目范围草稿。你这个时候可以整体读一遍，做必要的补充 （比如指定用 Resend 作为邮件服务商）然后确认。
3️⃣ 智能体生成任务拆解：项目初始化、前端组件、后端 API、邮件集成、PWA 配置、测试。检查一下顺序和内容，调整需要调整的地方，确认。
4️⃣ 验证清单准备好，正式开始构建。
开发过程中，Agent 会严格按照你确认的任务拆解推进，并且会实时标记已经完成的子任务，不会突然自由发挥。如果它开始做出 spec 里没有的假设，把它指回文档，它会重新校准。
Spec 不只是文档，它是整个开发过程中随时可以用的对齐工具。
最终你会得到一个完整运行的 PWA 软件，通过表单提交就能真实发出邮件。不需要在最后来一轮善后，去修那些你从没做过的决定。
Spec 使用场景
为大家列举了一些使用场景供参考，大家可以更针对性进行尝试。
一些常见问题
Q1：Spec 模式会让我的开发流程变慢吗？
对于简单任务，Agent 不会启用 Spec 模式，仍然使用 React 模式即时执行。只有当任务确实复杂到需要规划时，才需要升级到 Spec 模式。虽然 Spec 模式在开始阶段多了文档生成和确认环节，但它通过减少返工、避免方向偏差来节省总体时间。对于系统级任务，"花 10 分钟对齐方案"远比"花 2 小时写完再推倒重来"高效得多。
Q2：我可以在 Spec 模式执行过程中修改文档吗？
可以。文档首次创建时，Agent 会暂停并等待你确认。在此阶段你可以直接编辑文档内容，也可以用自然语言告诉 Agent 你希望修改的部分，Agent 会据此 Refine 文档。确认执行后，任务列表和验收清单的状态会随着执行进度自动更新。
Q3：Spec 模式生成的文档存在哪里？
所有 Spec 文档存储在项目根目录下的 .trae/specs/ 目录中，按任务名称分组为独立文件夹，每个文件夹包含 spec.md、tasks.md 和 checklist.md 三个文件。Plan 模式的文档则存储在 .trae/documents/ 目录中。这些文件可以纳入版本控制，作为项目知识资产长期保留。
总结：选择适合的 AI Coding 模式
TRAE 提供的三种模式，其实对应不同复杂度的开发场景。
Vibe 模式是大多数人的起点，也就是我们提到的“氛围感编程方式”。你给一个 prompt，让 agent 直接去跑，或者有时候你可以和 agent 来一场即兴的头脑风暴，在几个对话来回之间把功能构建出来。这种方式适合快速验证想法、搭原型，或者在现有项目上做简单改动。
Plan 模式则是在开始写代码之前多了一步：agent 先列出一个简短的实施计划，等你确认后再动手。可以把它理解成正式开工前的一次快速对齐。这一步能拦住大多数的方向性偏差，又不会明显拖慢节奏。特别适合范围已经比较清晰的功能迭代和模块化重构。
而 Spec 模式是为更复杂的情况设计的：从零开始的项目、周期较长的任务、任何一个早期决策出错就会带来连锁反应的开发场景。Spec 模式不会直接开始写代码，而是先和你共同建立一份项目基准文件夹，作为整个开发过程的锚点。不管项目跑多长，智能体始终知道自己在做什么、为什么这么做。
可以把这三种模式理解成一个从简到繁的坐标轴：项目越简单、越清晰，就越适合快速推进；项目越复杂、越模糊，就越需要在动手之前把结构搭好。
最后，你可以根据自己的具体场景，灵活选择最合适的 AI Coding 模式，让 AI 在你的节奏下工作，而不是反过来被它“牵着走”。
