1. 从“指令”到“规格”AI编程范式的静默革命如果你还在和ChatGPT、Claude或者Cursor里的AI助手用一段又一段精心雕琢的Prompt提示词进行“对话式编程”那你可能已经落后了半个身位。我最近在深度使用Cursor、Windsurf这类新一代AI IDE时发现了一个被严重低估但正在悄然改变游戏规则的功能Spec Mode或者说“规格模式”。它不是什么花哨的新按钮而是一种根本性的交互范式转变——从我们向AI“下达指令”转变为向AI“交付规格说明书”。过去一年我写了不下几千条Prompt。从最初的“写一个Python函数计算斐波那契数列”到后来复杂的“重构这个React组件采用Context API管理状态并添加错误边界”。每一次交互都像是一次小心翼翼的“谈判”我描述需求AI生成代码我检查、指出错误、补充细节AI修正……循环往复。这个过程的核心是“对话”而对话的载体就是Prompt。但Spec Mode彻底颠覆了这一点。它不再要求你写出完美的、一步到位的指令而是让你专注于定义清楚“你想要什么”——也就是软件的需求规格。AI的角色从一个需要你一步步指挥的“执行者”转变为一个能直接阅读需求文档并产出完整方案的“工程师”。这听起来有点抽象让我举个最直接的例子。假设你要开发一个用户登录系统。在传统Prompt模式下你可能会这样开始“用Next.js 14 App Router写一个登录页面包含邮箱和密码输入框一个提交按钮使用React Hook Form进行表单验证样式用Tailwind CSS。” 然后AI生成代码。你发现忘了说“需要记住登录状态”于是补充Prompt“添加一个AuthContext使用jwt token登录成功后跳转到/dashboard。” AI生成更多代码。你接着发现token刷新逻辑没处理、错误提示太简陋……整个过程是线性的、增量的、对话驱动的。而在Spec Mode下你做的事情完全不同。你会创建一个独立的、结构化的文档可能是一个Markdown文件或IDE里的一个专属面板然后像写产品需求文档PRD或技术设计文档一样写下项目用户认证系统目标为Next.js应用提供安全、完整的用户登录、注册、状态管理和令牌刷新功能。技术栈Next.js 14 (App Router), React, TypeScript, Tailwind CSS, next-auth或自定义JWT方案。核心功能规格页面/login页面邮箱/密码表单第三方登录Google按钮忘记密码链接。/register页面邮箱、密码、确认密码表单。表单验证前端使用React Hook Form Zod验证规则邮箱格式、密码强度等。状态管理使用React Context创建一个AuthProvider包裹应用。提供useAuthhook暴露user,login,logout,isLoading状态和方法。登录态持久化使用httpOnly cookie存储JWT访问令牌。API路由POST /api/auth/login验证凭证签发JWT。POST /api/auth/register创建新用户。POST /api/auth/refresh使用刷新令牌获取新的访问令牌。GET /api/auth/session获取当前用户会话。安全与体验密码加密存储服务端。自动令牌刷新在访问令牌过期前静默刷新。路由保护实现高阶组件withAuth用于保护如/dashboard,/profile等页面。UI/UX 细节加载状态提交按钮禁用并显示加载动画。错误提示表单级和全局Toast通知。响应式设计。写完这份规格书后你将它“喂”给处于Spec Mode的AI。AI不再是和你一句一句聊天而是会通读这份完整的规格理解各个模块之间的关联和约束然后直接生成一整套相互关联的、可运行的代码文件/app/login/page.tsx,/app/auth/AuthProvider.tsx,/app/api/auth/[...nextauth]/route.ts如果使用next-auth以及相关的工具函数、类型定义和Tailwind配置更新。它甚至可能生成一个简单的README.md说明如何启动项目。这个转变的核心价值在于它把人类的智力从“如何与机器沟通”的细节中解放出来聚焦于“到底要构建什么”这个更本质、更富创造性的问题上。我们不再需要是Prompt大师而是需要成为更清晰的产品定义者和架构师。Spec Mode正是下一代AI编程范式的雏形。1.1 为什么Prompt模式遇到了天花板在深入Spec Mode之前我们必须理解为什么曾经革命性的“对话式Prompt编程”开始显现出其局限性。这并非Prompt本身不好而是当AI的能力从“代码补全”演进到“系统构建”时旧的交互方式成了瓶颈。第一上下文碎片化与信息衰减。这是最致命的痛点。一个复杂的特性开发往往需要十几轮甚至几十轮对话。当你对话到第15轮时去修改第2轮中生成的某个组件的props设计AI可能已经“忘记”了当时为什么那么设计或者那个改动会如何影响在第8轮中生成的依赖该组件的其他模块。你不得不手动在Prompt里复述历史上下文比如“还记得我们之前做的那个UserCard组件吗现在需要给它加一个props叫showEmail……”效率极低且容易出错。人类的短期记忆和聊天窗口的上下文长度共同构成了信息传递的瓶颈。第二系统化思维缺失。Prompt是线性的、即时的。它鼓励“走一步看一步”的开发模式。但优秀的软件是一个系统各个部分之间存在复杂的依赖和约束关系。比如数据库Schema的设计会影响API接口的形态进而影响前端组件的props结构。在Prompt对话中你很难一次性向AI传达这种跨模块、跨层级的系统约束。结果往往是AI生成了一堆在孤立环境下看都正确但拼在一起却相互冲突的代码。第三沟通成本高昂。为了得到一个理想的输出你不得不学习所谓的“Prompt工程”如何排列指令的优先级如何给出正面和反面的例子如何设定角色如何使用特殊的格式标记。这本身成了一门需要钻研的“玄学”。更不用说你需要用自然语言精确描述一些用代码几句话就能说清的逻辑细节描述的过程本身就充满了歧义。第四难以复用和迭代。今天你通过一段精彩的Prompt生成了一个完美的数据表格组件。下周在新项目中需要类似的组件但稍有不同。你不得不重新组织语言或者翻找历史记录复制粘贴那段Prompt并小心调整。这个过程缺乏模块化和可组合性。而Spec Mode下的“规格书”本身就是一份结构化的、可版本控制、可 diff、可复用的文档。Spec Mode的出现正是为了解决这些天花板问题。它将交互的单元从一次性的、流动的“对话消息”提升到了结构化的、可持久化的“规格文档”。这不仅仅是工具功能的改变更是思维模式的升级。2. Spec Mode核心解析它到底是什么如何工作理解了“为什么”我们再来拆解“是什么”。Spec Mode不是一个单一功能而是一套由几个关键理念支撑的工作流。目前它最成熟的体现是在像Cursor、Windsurf这样的智能IDE中但它的思想可以应用到任何你与AI协作编程的场景中。2.1 Spec Mode的三大核心支柱支柱一结构化输入取代自然语言流这是最直观的变化。在Spec Mode下你的主要输入不是一个聊天输入框而是一个可以编辑的文档区域。这个文档有预期的结构。以Cursor的“.spec”文件为例它鼓励但不强制你按照以下结构组织内容# 项目或功能名称 ## 目标 (Goal) 用一两句话清晰说明要构建什么解决什么问题。 ## 技术栈与约束 (Tech Stack Constraints) - 框架、库、语言版本。 - 必须遵守的代码规范如命名约定、不使用某个已废弃的API。 - 性能、安全、可访问性等方面的非功能性需求。 ## 详细规格 (Detailed Specifications) 这是核心部分通常按模块或功能点展开。 - **模块A**描述其职责、输入输出、行为逻辑。可以包含伪代码、API端点设计、状态流描述。 - **模块B**描述其与模块A的交互关系。 - **UI/UX 描述**可以附上草图、Figma链接或详细的样式描述如“使用Tailwind的阴影类圆角为rounded-lg”。 ## 验收条件 (Acceptance Criteria) 像写测试用例一样定义“如何才算完成”。 - 当用户输入无效邮箱时表单应显示红色边框和错误信息“请输入有效的邮箱地址”。 - 点击提交后按钮应显示加载状态直到API返回响应。 - 成功登录后用户应被重定向到仪表板且顶部导航栏显示用户头像。这种结构强迫你在写代码之前进行思考和解构。它把模糊的想法变成了可验证的条目。对于AI来说这种结构化的信息也远比一段冗长的自然语言更容易解析和理解因为它明确了信息的类别和层次。支柱二全局理解与批量生成这是Spec Mode威力最大的地方。AI在“阅读”完整个规格文档后会对其形成一个全局的理解。它知道要创建多少个文件每个文件的大致职责以及文件之间的导入导出关系。然后它可以进行批量生成。比如根据上面登录系统的规格AI可能会一次性生成或规划出以下文件树/app/ /auth/ AuthProvider.tsx useAuth.ts withAuth.tsx /api/ /auth/ login/ route.ts register/ route.ts refresh/ route.ts session/ route.ts /login/ page.tsx LoginForm.tsx /register/ page.tsx /lib/ /utils/ jwt.ts validation.ts /types/ auth.ts它不仅仅生成这些文件的骨架还会填充大部分核心逻辑。因为AI从规格中同时看到了前端验证、API端点、状态管理等多个需求它可以在生成LoginForm.tsx时直接引用在规格中定义好的validation.ts中的Zod Schema在生成route.ts时直接使用jwt.ts中的工具函数。这种“并行”生成能力是顺序对话Prompt几乎无法实现的。支柱三迭代基于文档而非对话在Spec Mode下迭代开发的方式变了。当你需要修改功能时你不是去和AI说“嘿我们改一下这里”而是直接去修改那份规格文档。比如你想在登录时添加一个“记住我”的复选框。传统Prompt模式你“在登录表单里加一个‘记住我’的复选框。” AI生成新的LoginForm代码。 你“这个复选框的状态需要影响到token的有效期如果勾选有效期设为7天否则2小时。” AI修改AuthProvider和登录API的逻辑。 ……Spec Mode迭代打开login_system.spec.md文件。在“详细规格”的“UI/UX描述”部分为登录表单添加“添加一个记住我复选框默认不勾选。”在“API路由”的/api/auth/login部分修改说明“请求体新增rememberMe: boolean字段。若为true则设置刷新令牌的maxAge为7天否则为2小时。”保存规格文档。将更新后的规格再次提交给AI在Cursor里这可能通过一个“更新代码以匹配Spec”的指令触发。AI会读取整个更新后的文档理解这个新功能对UI、API、状态逻辑的全面影响然后对所有相关文件进行协调一致的更新。这保证了修改的原子性和一致性避免了“改了东墙忘了西墙”的情况。规格文档成为了唯一的“事实来源”。2.2 Spec Mode下的典型工作流结合我的使用经验一个高效的Spec Mode工作流通常包含以下步骤构思与拆解在动手写任何代码或规格之前先在白板或笔记上梳理清楚你要构建的东西。把它拆解成相对独立的模块、组件或功能点。思考它们之间的数据流和依赖关系。撰写规格文档在IDE中创建.spec文件或类似的文档。按照“目标 - 约束 - 详细规格 - 验收条件”的结构用清晰、无歧义的语言可以中英文混合描述每个部分。这里的技巧是像在给一位经验丰富但对你项目一无所知的工程师写任务说明书。要详细但避免描述具体的代码实现细节那是AI的工作。首次生成将规格文档提交给AI例如在Cursor中你可以对.spec文件运行spec指令。AI会分析文档并生成代码。首次生成的结果可能不完美但它会建立一个完整的、可编译的项目骨架。审查与精修仔细审查生成的代码。重点看几个方面架构符合度生成的代码结构是否符合你的预期模块划分是否清晰关键逻辑正确性核心的业务逻辑、算法、状态管理是否正确依赖与导入文件之间的导入关系是否正确有没有循环依赖样式与细节UI是否符合描述迭代规格而非代码如果发现不符合预期的地方不要直接去修改生成的代码。回到规格文档思考是哪里描述不清、有歧义或遗漏了约束条件。修改规格文档使其更精确。然后再次让AI根据更新后的规格来调整代码。这个过程可能重复几次直到规格文档足够精确能稳定地驱动AI生成符合你要求的代码。填充与微调对于非常复杂或需要高度定制化的逻辑AI可能无法从规格中完全推断。这时可以在生成的主体框架上针对单个文件或函数使用传统的聊天Prompt或编辑指令进行微调和细节填充。Spec Mode提供了主体框架传统Prompt负责局部精雕细琢二者是互补的。注意从修改代码跳回修改规格是思维转变的关键一步也是最难适应的一步。我们本能地想去直接改代码但要忍住。坚持“规格驱动”的原则长期来看会极大提升协作效率和代码的一致性。3. 实战用Spec Mode从零构建一个任务管理看板让我们通过一个完整的、贴近实际开发的例子来感受Spec Mode的威力。我们将构建一个简化版的Trello风格任务看板包含拖拽功能。3.1 第一步撰写规格说明书我们在项目根目录创建一个kanban.spec.md文件。# 简易任务管理看板 ## 目标 构建一个单页应用用于可视化管理和追踪任务状态。用户可以通过拖拽任务卡片在不同列表之间移动任务以反映任务进度。 ## 技术栈与约束 - **前端框架**: React 18 TypeScript - **构建工具**: Vite - **样式**: Tailwind CSS - **拖拽库**: 使用 dnd-kit 核心套件dnd-kit/core, dnd-kit/sortable, dnd-kit/utilities因其轻量且与React集成好。 - **状态管理**: 使用 React Context useReducer避免引入Redux等重型库。 - **数据持久化**: 使用 localStorage 在浏览器端持久化看板数据。 - **代码规范**: 函数组件使用箭头函数组件文件使用 .tsx 扩展名工具函数使用 .ts。 ## 详细规格 ### 数据模型 定义应用的核心数据类型。 - **Task任务**: { id: string, title: string, description?: string, listId: string } - **List列表**: { id: string, title: string } (例如“待办”、“进行中”、“已完成”) - **BoardState看板状态**: { lists: List[], tasks: Task[] } ### 核心组件 1. **Board 组件** (Board.tsx) - 根组件持有全局状态BoardState。 - 提供状态管理 Context (BoardContext)。 - 初始化时从 localStorage 加载数据变化时自动保存。 - 渲染 ListContainer 组件。 2. **ListContainer 组件** (ListContainer.tsx) - 使用 dnd-kit 的 DndContext 和 SortableContext 包裹整个看板区域。 - 处理拖拽开始、结束、取消等事件。 - 水平排列多个 List 组件。 3. **List 组件** (List.tsx) - 表示一个任务列表如“待办”。 - 是可拖拽的容器使用 useSortable。 - 显示列表标题和该列表下的所有 TaskCard 组件。 - 包含一个按钮用于在该列表中添加新任务。 4. **TaskCard 组件** (TaskCard.tsx) - 表示单个任务卡片。 - 是可拖拽的项目使用 useSortable。 - 显示任务标题和描述如果有。 - 包含一个删除按钮用于移除该任务。 ### 状态与逻辑 - **状态初始化**: 默认创建3个列表“待办”、“进行中”、“已完成”和若干示例任务。 - **状态更新逻辑** (在 reducer 中实现): - ADD_TASK: 在指定列表中添加新任务。 - DELETE_TASK: 删除指定任务。 - MOVE_TASK: 当任务被拖拽到另一个列表时更新其 listId。如果是在同一列表内排序则更新任务的顺序通过调整 tasks 数组顺序实现。 - UPDATE_TASK: 编辑任务标题或描述为未来扩展预留。 - **持久化逻辑**: 每次状态更新后将完整的 BoardState 序列化为 JSON 保存到 localStorage。应用加载时尝试读取并解析。 ### UI/UX 细节 - **布局**: 列表水平滚动每个列表固定宽度如 w-80卡片垂直排列。 - **拖拽视觉反馈**: - 被拖拽的卡片半透明。 - 拖拽经过的列表容器背景色轻微变化如 bg-gray-50。 - **交互**: - 点击列表的“添加任务”按钮弹出简单输入框或直接在本列表底部添加输入行输入标题后按回车创建。 - 点击任务卡片的删除按钮需有确认提示使用 window.confirm 或简单状态控制。 - 任务描述可折叠/展开。 - **样式**: 使用Tailwind实用类。列表背景为浅灰色卡片为白色阴影。整体风格简洁。 ## 验收条件 1. 页面加载后显示三个预定义的列表和若干任务卡片。 2. 鼠标长按任务卡片可开始拖拽拖拽时卡片半透明。 3. 将任务卡片拖拽到另一个列表区域并释放卡片应移动到目标列表。 4. 在同一列表内上下拖拽卡片可以改变其顺序。 5. 点击列表标题旁的“”按钮可以成功在该列表创建新任务。 6. 点击任务卡片的删除图标经确认后该任务从看板消失。 7. 刷新浏览器页面看板状态列表、任务及其位置应被保留。这份规格书大约有500字但它定义了一个完整应用的需求、架构、技术选型和交互细节。它没有一行代码但任何一位有经验的React开发者或者一个强大的AI都能从中清晰地知道要构建什么。3.2 第二步AI生成与初步审查在Cursor中我们可以对这个.spec.md文件使用“生成代码”功能。AI通常是Claude 3.5 Sonnet或GPT-4会读取这份文档并开始生成代码。它可能会先创建项目的基本ViteReactTS结构然后按照规格逐一创建组件和逻辑。生成结果的关键审查点项目结构检查是否生成了src/components/目录里面是否有Board.tsx,ListContainer.tsx,List.tsx,TaskCard.tsx。以及src/contexts/,src/types/,src/utils/等目录。依赖安装检查package.json是否包含了dnd-kit相关依赖和tailwindcss。核心逻辑打开src/contexts/BoardContext.tsx检查useReducer的reducer函数是否实现了MOVE_TASK,ADD_TASK等动作。重点看MOVE_TASK的逻辑它需要处理同一列表内排序和跨列表移动两种情况这是拖拽的核心。拖拽集成打开ListContainer.tsx检查是否正确定义了DndContext的onDragEnd事件处理函数并且该函数能正确调用dispatch({ type: MOVE_TASK, ...})。持久化检查Board.tsx的useEffect是否在状态变化时执行localStorage.setItem以及在初始化时执行localStorage.getItem。首次生成后你可能会发现一些问题。例如AI可能用了一种不同于你预期的dnd-kit的排序策略或者localStorage的键名是硬编码的。记住此时不要直接修改代码文件。3.3 第三步迭代规格驱动修正假设我们发现AI生成的代码中任务在同一列表内拖拽排序时视觉反馈很卡顿。我们判断可能是AI选择的排序策略比如直接操作数组索引在频繁渲染下效率不高。错误的做法直接打开ListContainer.tsx和reducer函数修改排序算法。正确的Spec Mode做法回到kanban.spec.md文件在“状态更新逻辑”部分对MOVE_TASK增加更明确的约束。### 状态更新逻辑 (补充/修正) - **MOVE_TASK 动作的优化要求**: - 为实现流畅的拖拽排序在更新 tasks 数组顺序时应使用高效的不可变数据更新方式。 - 当任务在同一列表内移动时建议使用类似 array-move 库的函数或等价的纯函数逻辑来重新排序避免复杂的splice/index计算以减少潜在的性能开销和bug。 - 此逻辑应在 reducer 函数中集中处理。我们还可以在“验收条件”中增加一条8. 拖拽排序尤其是同一列表内应保持流畅无明显卡顿或视觉闪烁。保存规格文档。然后我们再次触发AI“根据更新后的规格调整代码”。AI会重新理解我们对性能的关切并可能采取以下一种或多种措施在reducer中引入更优雅的数组元素移动逻辑。检查是否在DndContext中正确配置了modifiers或collisionDetection策略以优化性能。甚至可能建议将tasks数组的排序与每个List关联以简化更新逻辑。通过迭代规格我们不仅修复了当前的问题还将这个“性能要求”明确记录在了项目的核心文档中对未来的维护者和AI都是一种约束和指引。3.4 第四步局部微调与收尾经过几轮规格迭代主体框架和核心逻辑已经稳定。现在我们需要一些规格难以描述的细节。例如我们希望任务卡片在鼠标悬停时有一个微妙的阴影效果。这时我们可以切换到传统Prompt模式但作用域限定在单个文件。打开TaskCard.tsx在Cursor的聊天框中输入TaskCard.tsx 请为任务卡片的容器div添加一个Tailwind CSS类实现鼠标悬停时阴影略微加深的效果让交互感更强。AI会只修改这个文件添加类似hover:shadow-md的类名。这种“Spec定框架Prompt雕细节”的混合模式非常高效。4. Spec Mode的挑战、局限与最佳实践尽管Spec Mode潜力巨大但它并非银弹。在实际使用中我踩过不少坑也总结出一些让Spec Mode发挥最大效力的实践心得。4.1 当前面临的挑战与局限AI对复杂规格的理解仍有偏差当规格文档非常庞大和复杂时比如描述一个完整的微服务架构AI可能无法完全把握所有细节之间的关联导致生成的代码出现矛盾或遗漏。它更擅长处理中等复杂度、模块边界清晰的系统规格。生成代码的风格和质量不稳定同样的规格不同时间运行AI可能生成风格略有差异的代码比如函数命名习惯、错误处理方式。虽然可以通过在“约束”部分极力明确代码规范来改善但无法完全杜绝。调试与错误追踪困难如果生成的代码运行时报错错误栈指向的是AI生成的代码。你需要像调试他人代码一样去理解AI的逻辑这有时比调试自己的代码更费劲因为你不完全了解AI的“思路”。对现有项目的集成Spec Mode在绿地项目从零开始上表现最佳。对于棕地项目已有大量代码如何编写一个只描述增量功能、又能与现有代码库和谐融合的规格是一个高难度挑战。AI可能无法完全理解你现有的架构和约定。过度依赖的风险长期使用可能导致开发者疏于对底层代码和架构的深入理解变成“规格经理”。一旦AI生成有深层逻辑缺陷的代码而开发者缺乏审查能力就会引入严重隐患。4.2 高效使用Spec Mode的最佳实践基于数百小时的使用经验我提炼出以下实践准则能帮你绕过大多数坑1. 规格文档的写作艺术分而治之不要试图用一个庞大的Spec文件描述整个项目。为每个相对独立的功能模块、子系统或组件包创建独立的.spec.md文件。例如auth.spec.md,user-profile.spec.md,> 从Prompt到Spec：AI编程范式的变革与规格驱动开发实践
1. 从“指令”到“规格”AI编程范式的静默革命如果你还在和ChatGPT、Claude或者Cursor里的AI助手用一段又一段精心雕琢的Prompt提示词进行“对话式编程”那你可能已经落后了半个身位。我最近在深度使用Cursor、Windsurf这类新一代AI IDE时发现了一个被严重低估但正在悄然改变游戏规则的功能Spec Mode或者说“规格模式”。它不是什么花哨的新按钮而是一种根本性的交互范式转变——从我们向AI“下达指令”转变为向AI“交付规格说明书”。过去一年我写了不下几千条Prompt。从最初的“写一个Python函数计算斐波那契数列”到后来复杂的“重构这个React组件采用Context API管理状态并添加错误边界”。每一次交互都像是一次小心翼翼的“谈判”我描述需求AI生成代码我检查、指出错误、补充细节AI修正……循环往复。这个过程的核心是“对话”而对话的载体就是Prompt。但Spec Mode彻底颠覆了这一点。它不再要求你写出完美的、一步到位的指令而是让你专注于定义清楚“你想要什么”——也就是软件的需求规格。AI的角色从一个需要你一步步指挥的“执行者”转变为一个能直接阅读需求文档并产出完整方案的“工程师”。这听起来有点抽象让我举个最直接的例子。假设你要开发一个用户登录系统。在传统Prompt模式下你可能会这样开始“用Next.js 14 App Router写一个登录页面包含邮箱和密码输入框一个提交按钮使用React Hook Form进行表单验证样式用Tailwind CSS。” 然后AI生成代码。你发现忘了说“需要记住登录状态”于是补充Prompt“添加一个AuthContext使用jwt token登录成功后跳转到/dashboard。” AI生成更多代码。你接着发现token刷新逻辑没处理、错误提示太简陋……整个过程是线性的、增量的、对话驱动的。而在Spec Mode下你做的事情完全不同。你会创建一个独立的、结构化的文档可能是一个Markdown文件或IDE里的一个专属面板然后像写产品需求文档PRD或技术设计文档一样写下项目用户认证系统目标为Next.js应用提供安全、完整的用户登录、注册、状态管理和令牌刷新功能。技术栈Next.js 14 (App Router), React, TypeScript, Tailwind CSS, next-auth或自定义JWT方案。核心功能规格页面/login页面邮箱/密码表单第三方登录Google按钮忘记密码链接。/register页面邮箱、密码、确认密码表单。表单验证前端使用React Hook Form Zod验证规则邮箱格式、密码强度等。状态管理使用React Context创建一个AuthProvider包裹应用。提供useAuthhook暴露user,login,logout,isLoading状态和方法。登录态持久化使用httpOnly cookie存储JWT访问令牌。API路由POST /api/auth/login验证凭证签发JWT。POST /api/auth/register创建新用户。POST /api/auth/refresh使用刷新令牌获取新的访问令牌。GET /api/auth/session获取当前用户会话。安全与体验密码加密存储服务端。自动令牌刷新在访问令牌过期前静默刷新。路由保护实现高阶组件withAuth用于保护如/dashboard,/profile等页面。UI/UX 细节加载状态提交按钮禁用并显示加载动画。错误提示表单级和全局Toast通知。响应式设计。写完这份规格书后你将它“喂”给处于Spec Mode的AI。AI不再是和你一句一句聊天而是会通读这份完整的规格理解各个模块之间的关联和约束然后直接生成一整套相互关联的、可运行的代码文件/app/login/page.tsx,/app/auth/AuthProvider.tsx,/app/api/auth/[...nextauth]/route.ts如果使用next-auth以及相关的工具函数、类型定义和Tailwind配置更新。它甚至可能生成一个简单的README.md说明如何启动项目。这个转变的核心价值在于它把人类的智力从“如何与机器沟通”的细节中解放出来聚焦于“到底要构建什么”这个更本质、更富创造性的问题上。我们不再需要是Prompt大师而是需要成为更清晰的产品定义者和架构师。Spec Mode正是下一代AI编程范式的雏形。1.1 为什么Prompt模式遇到了天花板在深入Spec Mode之前我们必须理解为什么曾经革命性的“对话式Prompt编程”开始显现出其局限性。这并非Prompt本身不好而是当AI的能力从“代码补全”演进到“系统构建”时旧的交互方式成了瓶颈。第一上下文碎片化与信息衰减。这是最致命的痛点。一个复杂的特性开发往往需要十几轮甚至几十轮对话。当你对话到第15轮时去修改第2轮中生成的某个组件的props设计AI可能已经“忘记”了当时为什么那么设计或者那个改动会如何影响在第8轮中生成的依赖该组件的其他模块。你不得不手动在Prompt里复述历史上下文比如“还记得我们之前做的那个UserCard组件吗现在需要给它加一个props叫showEmail……”效率极低且容易出错。人类的短期记忆和聊天窗口的上下文长度共同构成了信息传递的瓶颈。第二系统化思维缺失。Prompt是线性的、即时的。它鼓励“走一步看一步”的开发模式。但优秀的软件是一个系统各个部分之间存在复杂的依赖和约束关系。比如数据库Schema的设计会影响API接口的形态进而影响前端组件的props结构。在Prompt对话中你很难一次性向AI传达这种跨模块、跨层级的系统约束。结果往往是AI生成了一堆在孤立环境下看都正确但拼在一起却相互冲突的代码。第三沟通成本高昂。为了得到一个理想的输出你不得不学习所谓的“Prompt工程”如何排列指令的优先级如何给出正面和反面的例子如何设定角色如何使用特殊的格式标记。这本身成了一门需要钻研的“玄学”。更不用说你需要用自然语言精确描述一些用代码几句话就能说清的逻辑细节描述的过程本身就充满了歧义。第四难以复用和迭代。今天你通过一段精彩的Prompt生成了一个完美的数据表格组件。下周在新项目中需要类似的组件但稍有不同。你不得不重新组织语言或者翻找历史记录复制粘贴那段Prompt并小心调整。这个过程缺乏模块化和可组合性。而Spec Mode下的“规格书”本身就是一份结构化的、可版本控制、可 diff、可复用的文档。Spec Mode的出现正是为了解决这些天花板问题。它将交互的单元从一次性的、流动的“对话消息”提升到了结构化的、可持久化的“规格文档”。这不仅仅是工具功能的改变更是思维模式的升级。2. Spec Mode核心解析它到底是什么如何工作理解了“为什么”我们再来拆解“是什么”。Spec Mode不是一个单一功能而是一套由几个关键理念支撑的工作流。目前它最成熟的体现是在像Cursor、Windsurf这样的智能IDE中但它的思想可以应用到任何你与AI协作编程的场景中。2.1 Spec Mode的三大核心支柱支柱一结构化输入取代自然语言流这是最直观的变化。在Spec Mode下你的主要输入不是一个聊天输入框而是一个可以编辑的文档区域。这个文档有预期的结构。以Cursor的“.spec”文件为例它鼓励但不强制你按照以下结构组织内容# 项目或功能名称 ## 目标 (Goal) 用一两句话清晰说明要构建什么解决什么问题。 ## 技术栈与约束 (Tech Stack Constraints) - 框架、库、语言版本。 - 必须遵守的代码规范如命名约定、不使用某个已废弃的API。 - 性能、安全、可访问性等方面的非功能性需求。 ## 详细规格 (Detailed Specifications) 这是核心部分通常按模块或功能点展开。 - **模块A**描述其职责、输入输出、行为逻辑。可以包含伪代码、API端点设计、状态流描述。 - **模块B**描述其与模块A的交互关系。 - **UI/UX 描述**可以附上草图、Figma链接或详细的样式描述如“使用Tailwind的阴影类圆角为rounded-lg”。 ## 验收条件 (Acceptance Criteria) 像写测试用例一样定义“如何才算完成”。 - 当用户输入无效邮箱时表单应显示红色边框和错误信息“请输入有效的邮箱地址”。 - 点击提交后按钮应显示加载状态直到API返回响应。 - 成功登录后用户应被重定向到仪表板且顶部导航栏显示用户头像。这种结构强迫你在写代码之前进行思考和解构。它把模糊的想法变成了可验证的条目。对于AI来说这种结构化的信息也远比一段冗长的自然语言更容易解析和理解因为它明确了信息的类别和层次。支柱二全局理解与批量生成这是Spec Mode威力最大的地方。AI在“阅读”完整个规格文档后会对其形成一个全局的理解。它知道要创建多少个文件每个文件的大致职责以及文件之间的导入导出关系。然后它可以进行批量生成。比如根据上面登录系统的规格AI可能会一次性生成或规划出以下文件树/app/ /auth/ AuthProvider.tsx useAuth.ts withAuth.tsx /api/ /auth/ login/ route.ts register/ route.ts refresh/ route.ts session/ route.ts /login/ page.tsx LoginForm.tsx /register/ page.tsx /lib/ /utils/ jwt.ts validation.ts /types/ auth.ts它不仅仅生成这些文件的骨架还会填充大部分核心逻辑。因为AI从规格中同时看到了前端验证、API端点、状态管理等多个需求它可以在生成LoginForm.tsx时直接引用在规格中定义好的validation.ts中的Zod Schema在生成route.ts时直接使用jwt.ts中的工具函数。这种“并行”生成能力是顺序对话Prompt几乎无法实现的。支柱三迭代基于文档而非对话在Spec Mode下迭代开发的方式变了。当你需要修改功能时你不是去和AI说“嘿我们改一下这里”而是直接去修改那份规格文档。比如你想在登录时添加一个“记住我”的复选框。传统Prompt模式你“在登录表单里加一个‘记住我’的复选框。” AI生成新的LoginForm代码。 你“这个复选框的状态需要影响到token的有效期如果勾选有效期设为7天否则2小时。” AI修改AuthProvider和登录API的逻辑。 ……Spec Mode迭代打开login_system.spec.md文件。在“详细规格”的“UI/UX描述”部分为登录表单添加“添加一个记住我复选框默认不勾选。”在“API路由”的/api/auth/login部分修改说明“请求体新增rememberMe: boolean字段。若为true则设置刷新令牌的maxAge为7天否则为2小时。”保存规格文档。将更新后的规格再次提交给AI在Cursor里这可能通过一个“更新代码以匹配Spec”的指令触发。AI会读取整个更新后的文档理解这个新功能对UI、API、状态逻辑的全面影响然后对所有相关文件进行协调一致的更新。这保证了修改的原子性和一致性避免了“改了东墙忘了西墙”的情况。规格文档成为了唯一的“事实来源”。2.2 Spec Mode下的典型工作流结合我的使用经验一个高效的Spec Mode工作流通常包含以下步骤构思与拆解在动手写任何代码或规格之前先在白板或笔记上梳理清楚你要构建的东西。把它拆解成相对独立的模块、组件或功能点。思考它们之间的数据流和依赖关系。撰写规格文档在IDE中创建.spec文件或类似的文档。按照“目标 - 约束 - 详细规格 - 验收条件”的结构用清晰、无歧义的语言可以中英文混合描述每个部分。这里的技巧是像在给一位经验丰富但对你项目一无所知的工程师写任务说明书。要详细但避免描述具体的代码实现细节那是AI的工作。首次生成将规格文档提交给AI例如在Cursor中你可以对.spec文件运行spec指令。AI会分析文档并生成代码。首次生成的结果可能不完美但它会建立一个完整的、可编译的项目骨架。审查与精修仔细审查生成的代码。重点看几个方面架构符合度生成的代码结构是否符合你的预期模块划分是否清晰关键逻辑正确性核心的业务逻辑、算法、状态管理是否正确依赖与导入文件之间的导入关系是否正确有没有循环依赖样式与细节UI是否符合描述迭代规格而非代码如果发现不符合预期的地方不要直接去修改生成的代码。回到规格文档思考是哪里描述不清、有歧义或遗漏了约束条件。修改规格文档使其更精确。然后再次让AI根据更新后的规格来调整代码。这个过程可能重复几次直到规格文档足够精确能稳定地驱动AI生成符合你要求的代码。填充与微调对于非常复杂或需要高度定制化的逻辑AI可能无法从规格中完全推断。这时可以在生成的主体框架上针对单个文件或函数使用传统的聊天Prompt或编辑指令进行微调和细节填充。Spec Mode提供了主体框架传统Prompt负责局部精雕细琢二者是互补的。注意从修改代码跳回修改规格是思维转变的关键一步也是最难适应的一步。我们本能地想去直接改代码但要忍住。坚持“规格驱动”的原则长期来看会极大提升协作效率和代码的一致性。3. 实战用Spec Mode从零构建一个任务管理看板让我们通过一个完整的、贴近实际开发的例子来感受Spec Mode的威力。我们将构建一个简化版的Trello风格任务看板包含拖拽功能。3.1 第一步撰写规格说明书我们在项目根目录创建一个kanban.spec.md文件。# 简易任务管理看板 ## 目标 构建一个单页应用用于可视化管理和追踪任务状态。用户可以通过拖拽任务卡片在不同列表之间移动任务以反映任务进度。 ## 技术栈与约束 - **前端框架**: React 18 TypeScript - **构建工具**: Vite - **样式**: Tailwind CSS - **拖拽库**: 使用 dnd-kit 核心套件dnd-kit/core, dnd-kit/sortable, dnd-kit/utilities因其轻量且与React集成好。 - **状态管理**: 使用 React Context useReducer避免引入Redux等重型库。 - **数据持久化**: 使用 localStorage 在浏览器端持久化看板数据。 - **代码规范**: 函数组件使用箭头函数组件文件使用 .tsx 扩展名工具函数使用 .ts。 ## 详细规格 ### 数据模型 定义应用的核心数据类型。 - **Task任务**: { id: string, title: string, description?: string, listId: string } - **List列表**: { id: string, title: string } (例如“待办”、“进行中”、“已完成”) - **BoardState看板状态**: { lists: List[], tasks: Task[] } ### 核心组件 1. **Board 组件** (Board.tsx) - 根组件持有全局状态BoardState。 - 提供状态管理 Context (BoardContext)。 - 初始化时从 localStorage 加载数据变化时自动保存。 - 渲染 ListContainer 组件。 2. **ListContainer 组件** (ListContainer.tsx) - 使用 dnd-kit 的 DndContext 和 SortableContext 包裹整个看板区域。 - 处理拖拽开始、结束、取消等事件。 - 水平排列多个 List 组件。 3. **List 组件** (List.tsx) - 表示一个任务列表如“待办”。 - 是可拖拽的容器使用 useSortable。 - 显示列表标题和该列表下的所有 TaskCard 组件。 - 包含一个按钮用于在该列表中添加新任务。 4. **TaskCard 组件** (TaskCard.tsx) - 表示单个任务卡片。 - 是可拖拽的项目使用 useSortable。 - 显示任务标题和描述如果有。 - 包含一个删除按钮用于移除该任务。 ### 状态与逻辑 - **状态初始化**: 默认创建3个列表“待办”、“进行中”、“已完成”和若干示例任务。 - **状态更新逻辑** (在 reducer 中实现): - ADD_TASK: 在指定列表中添加新任务。 - DELETE_TASK: 删除指定任务。 - MOVE_TASK: 当任务被拖拽到另一个列表时更新其 listId。如果是在同一列表内排序则更新任务的顺序通过调整 tasks 数组顺序实现。 - UPDATE_TASK: 编辑任务标题或描述为未来扩展预留。 - **持久化逻辑**: 每次状态更新后将完整的 BoardState 序列化为 JSON 保存到 localStorage。应用加载时尝试读取并解析。 ### UI/UX 细节 - **布局**: 列表水平滚动每个列表固定宽度如 w-80卡片垂直排列。 - **拖拽视觉反馈**: - 被拖拽的卡片半透明。 - 拖拽经过的列表容器背景色轻微变化如 bg-gray-50。 - **交互**: - 点击列表的“添加任务”按钮弹出简单输入框或直接在本列表底部添加输入行输入标题后按回车创建。 - 点击任务卡片的删除按钮需有确认提示使用 window.confirm 或简单状态控制。 - 任务描述可折叠/展开。 - **样式**: 使用Tailwind实用类。列表背景为浅灰色卡片为白色阴影。整体风格简洁。 ## 验收条件 1. 页面加载后显示三个预定义的列表和若干任务卡片。 2. 鼠标长按任务卡片可开始拖拽拖拽时卡片半透明。 3. 将任务卡片拖拽到另一个列表区域并释放卡片应移动到目标列表。 4. 在同一列表内上下拖拽卡片可以改变其顺序。 5. 点击列表标题旁的“”按钮可以成功在该列表创建新任务。 6. 点击任务卡片的删除图标经确认后该任务从看板消失。 7. 刷新浏览器页面看板状态列表、任务及其位置应被保留。这份规格书大约有500字但它定义了一个完整应用的需求、架构、技术选型和交互细节。它没有一行代码但任何一位有经验的React开发者或者一个强大的AI都能从中清晰地知道要构建什么。3.2 第二步AI生成与初步审查在Cursor中我们可以对这个.spec.md文件使用“生成代码”功能。AI通常是Claude 3.5 Sonnet或GPT-4会读取这份文档并开始生成代码。它可能会先创建项目的基本ViteReactTS结构然后按照规格逐一创建组件和逻辑。生成结果的关键审查点项目结构检查是否生成了src/components/目录里面是否有Board.tsx,ListContainer.tsx,List.tsx,TaskCard.tsx。以及src/contexts/,src/types/,src/utils/等目录。依赖安装检查package.json是否包含了dnd-kit相关依赖和tailwindcss。核心逻辑打开src/contexts/BoardContext.tsx检查useReducer的reducer函数是否实现了MOVE_TASK,ADD_TASK等动作。重点看MOVE_TASK的逻辑它需要处理同一列表内排序和跨列表移动两种情况这是拖拽的核心。拖拽集成打开ListContainer.tsx检查是否正确定义了DndContext的onDragEnd事件处理函数并且该函数能正确调用dispatch({ type: MOVE_TASK, ...})。持久化检查Board.tsx的useEffect是否在状态变化时执行localStorage.setItem以及在初始化时执行localStorage.getItem。首次生成后你可能会发现一些问题。例如AI可能用了一种不同于你预期的dnd-kit的排序策略或者localStorage的键名是硬编码的。记住此时不要直接修改代码文件。3.3 第三步迭代规格驱动修正假设我们发现AI生成的代码中任务在同一列表内拖拽排序时视觉反馈很卡顿。我们判断可能是AI选择的排序策略比如直接操作数组索引在频繁渲染下效率不高。错误的做法直接打开ListContainer.tsx和reducer函数修改排序算法。正确的Spec Mode做法回到kanban.spec.md文件在“状态更新逻辑”部分对MOVE_TASK增加更明确的约束。### 状态更新逻辑 (补充/修正) - **MOVE_TASK 动作的优化要求**: - 为实现流畅的拖拽排序在更新 tasks 数组顺序时应使用高效的不可变数据更新方式。 - 当任务在同一列表内移动时建议使用类似 array-move 库的函数或等价的纯函数逻辑来重新排序避免复杂的splice/index计算以减少潜在的性能开销和bug。 - 此逻辑应在 reducer 函数中集中处理。我们还可以在“验收条件”中增加一条8. 拖拽排序尤其是同一列表内应保持流畅无明显卡顿或视觉闪烁。保存规格文档。然后我们再次触发AI“根据更新后的规格调整代码”。AI会重新理解我们对性能的关切并可能采取以下一种或多种措施在reducer中引入更优雅的数组元素移动逻辑。检查是否在DndContext中正确配置了modifiers或collisionDetection策略以优化性能。甚至可能建议将tasks数组的排序与每个List关联以简化更新逻辑。通过迭代规格我们不仅修复了当前的问题还将这个“性能要求”明确记录在了项目的核心文档中对未来的维护者和AI都是一种约束和指引。3.4 第四步局部微调与收尾经过几轮规格迭代主体框架和核心逻辑已经稳定。现在我们需要一些规格难以描述的细节。例如我们希望任务卡片在鼠标悬停时有一个微妙的阴影效果。这时我们可以切换到传统Prompt模式但作用域限定在单个文件。打开TaskCard.tsx在Cursor的聊天框中输入TaskCard.tsx 请为任务卡片的容器div添加一个Tailwind CSS类实现鼠标悬停时阴影略微加深的效果让交互感更强。AI会只修改这个文件添加类似hover:shadow-md的类名。这种“Spec定框架Prompt雕细节”的混合模式非常高效。4. Spec Mode的挑战、局限与最佳实践尽管Spec Mode潜力巨大但它并非银弹。在实际使用中我踩过不少坑也总结出一些让Spec Mode发挥最大效力的实践心得。4.1 当前面临的挑战与局限AI对复杂规格的理解仍有偏差当规格文档非常庞大和复杂时比如描述一个完整的微服务架构AI可能无法完全把握所有细节之间的关联导致生成的代码出现矛盾或遗漏。它更擅长处理中等复杂度、模块边界清晰的系统规格。生成代码的风格和质量不稳定同样的规格不同时间运行AI可能生成风格略有差异的代码比如函数命名习惯、错误处理方式。虽然可以通过在“约束”部分极力明确代码规范来改善但无法完全杜绝。调试与错误追踪困难如果生成的代码运行时报错错误栈指向的是AI生成的代码。你需要像调试他人代码一样去理解AI的逻辑这有时比调试自己的代码更费劲因为你不完全了解AI的“思路”。对现有项目的集成Spec Mode在绿地项目从零开始上表现最佳。对于棕地项目已有大量代码如何编写一个只描述增量功能、又能与现有代码库和谐融合的规格是一个高难度挑战。AI可能无法完全理解你现有的架构和约定。过度依赖的风险长期使用可能导致开发者疏于对底层代码和架构的深入理解变成“规格经理”。一旦AI生成有深层逻辑缺陷的代码而开发者缺乏审查能力就会引入严重隐患。4.2 高效使用Spec Mode的最佳实践基于数百小时的使用经验我提炼出以下实践准则能帮你绕过大多数坑1. 规格文档的写作艺术分而治之不要试图用一个庞大的Spec文件描述整个项目。为每个相对独立的功能模块、子系统或组件包创建独立的.spec.md文件。例如auth.spec.md,user-profile.spec.md,>