一文快速理解 Spec 模式
摘要：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 使用场景
为大家列举了一些使用场景供参考，大家可以更针对性进行尝试。
场景 | 描述 | 为什么需要 Spec 模式 |
新系统/新模块 0→1 | 从零搭建一个完整的服务、模块或应用 | 需求范围大、架构决策多，必须先对齐大纲再动手 |
大规模重构 | 对现有系统进行架构级重构或技术栈迁移 | 涉及大量文件和模块间依赖，需要清晰的任务拆解和验收标准 |
多人协作项目 | 团队中多位工程师基于 AI 协同开发同一项目 | Spec 文档作为单一事实来源对齐所有人的理解 |
高质量/高稳定性要求 | 核心业务逻辑、支付系统、安全模块等关键功能的开发 | 需要严格的验收清单来确保每个环节达标 |
长期维护项目 | 需要持续迭代、有历史包袱的成熟项目 | 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 在你的节奏下工作，而不是反过来被它“牵着走”。