1. 项目概述一个为工程团队设计的AI驱动开发工作流启动器如果你和你的团队正在使用Cursor IDE并且希望将AI辅助开发从一个偶尔使用的“代码补全工具”升级为一套可预测、可复现、能真正融入团队协作流程的“工程化工作流”那么这个名为“Cursor SDD Starter”的项目就是你一直在寻找的答案。SDD即“Spec-Driven Development”规范驱动开发是这个工具包的核心哲学。它不是一个简单的代码片段集合而是一个平台无关的、技能驱动的智能体开发框架旨在将Cursor从一个被动的助手转变为你项目中的一位主动的、理解你架构的“虚拟工程师”。简单来说这个工具包为你提供了一套现成的“剧本”和“工具”。它通过一个交互式的设置向导cursor-setup来快速分析你的项目然后生成一系列定制化的“技能”Skills和“规则”Rules。这些技能覆盖了从需求澄清、架构设计、代码实现、测试编写到最终PR检查的完整开发闭环。无论你的项目是移动端的React Native、后端的Node.js或Go还是复杂的全栈应用它都能适配并生成符合你技术栈的最佳实践。它的核心价值在于将零散的AI提示工程固化为团队共享的、可迭代的工程资产让每一次与AI的协作都像遵循一个经过验证的、高效的开发协议。2. 核心设计理念与工作流拆解2.1 从“聊天式”到“流程式”的范式转变在没有结构化工作流之前我们在Cursor中的交互往往是随机的遇到一个bug打开聊天框描述问题需要写个新函数再打开聊天框描述需求。这种模式存在几个明显问题上下文割裂每次对话都是新的开始、结果不可预测依赖你当次的提示词水平、难以团队共享你的“魔法提示词”别人不知道。Cursor SDD Starter正是为了解决这些问题而生。它的设计核心是“技能驱动”和“规范先行”。它将开发任务抽象为一系列可复用的“技能”Skill每个技能都是一个自包含的、目标明确的指令集。例如new-feature是创建新功能的总指挥architecture-guard是架构守门员pr-checklist是合并前的质量检查官。这些技能通过清晰的协议相互调用形成了一个确定的、可追溯的“智能体循环”。2.2 双路径工作流按复杂度智能路由项目最精妙的设计之一是其内置的“智能路由”机制。当你发起一个new-feature请求时它不会盲目地开始写代码而是先对任务的复杂度进行分类然后将其导入两条预设的路径之一路径A完整功能适用于任何非琐碎的任务例如新页面、新模块、新服务或涉及3个以上文件的改动。这条路径严格遵循软件工程的最佳实践包含需求澄清、架构审查、高层/底层设计、分层实现、逐层验证等步骤。它强制在关键节点如设计完成后暂停等待人工确认确保AI的行动始终在可控的轨道上。这相当于为AI配备了一位经验丰富的Tech Lead在它“开干”之前先帮它把方案评审一遍。路径B简单任务适用于微小、增量的修改比如修复一个明显的bug、添加一个简单的工具函数预计在30分钟内完成。对于这类任务它会跳过繁重的设计评审环节直接进入实现和基础验证追求效率。这种设计非常符合实际开发场景。它避免了“用牛刀杀鸡”的过度设计也防止了“用水果刀砍树”的架构失控。作为使用者你只需要用自然语言描述需求系统会自动为你选择最合适的开发流程。2.3 规则与技能可编程的团队知识库这是项目将AI能力“工程化”的基石。它包含两大核心配置体系规则.mdc文件位于.cursor/rules/目录下。你可以把它理解为项目的“宪法”和“地方法规”。项目级规则project-conventions.mdc设置了alwaysApply: true意味着只要项目在Cursor中打开这些规则就会一直加载到AI的上下文中。这里应该放置那些绝对不容违反的架构约束和团队约定例如“所有API响应必须包裹在统一的ApiResponse对象中”、“禁止在业务逻辑层直接操作数据库连接”。模式规则[lang]-patterns.mdc,test-patterns.mdc这些规则通过globs配置如**/*.ts只在打开对应语言文件时才生效。它们定义了具体的编码模式例如“React组件必须使用函数式声明和TypeScript”、“Python的异常处理必须包含具体的错误日志”。技能.md文件位于.cursor/skills/目录下的各个子文件夹中。每个技能都是一个独立的Markdown文件包含完成特定任务所需的完整指令、步骤和上下文。技能可以被用户直接调用如debugger也可以在技能链中被其他技能调用如new-feature在执行中调用architecture-guard。技能的强大之处在于其可组合性和可定制性。团队可以将解决某类复杂问题的“金科玉律”沉淀为一个技能新成员或AI都能通过调用这个技能获得与资深工程师同水平的解决思路。通过规则和技能的配合团队的核心开发理念、技术栈特性和常见问题解决方案就从依赖个人经验的“隐性知识”变成了存储在版本库中、可随时调用和迭代的“显性资产”。3. 从零开始手把手部署与初始化3.1 环境准备与项目集成在开始之前请确保你的本地环境满足两个基本条件一是已经安装并配置好 Cursor IDE 二是你的项目本身是一个Git仓库或者你准备将其初始化为一个。Node.js环境是可选的仅在需要通过npx安装Context7时用到。集成Cursor SDD Starter到现有项目官方提供了两种方式我强烈推荐交互式设置但理解手动流程也至关重要。方式一复制文件基础集成打开终端进入你的项目根目录执行以下命令# 克隆启动器仓库可以克隆到任何临时位置 git clone https://github.com/ameya-vichare/cursor-sdd-starter # 将核心目录和文件复制到你的项目中 cp -rn cursor-sdd-starter/.cursor cursor-sdd-starter/docs cursor-sdd-starter/tasks cursor-sdd-starter/PROJECT.md /path/to/your-project/注意-n参数代表“不覆盖”如果你的项目里已经有.cursor目录这个命令会跳过它避免冲突。如果发生这种情况你需要手动复制技能文件夹cp -rn cursor-sdd-starter/.cursor/skills/cursor-setup cursor-sdd-starter/.cursor/skills/new-feature /path/to/your-project/.cursor/skills/执行完这一步你的项目根目录下会新增.cursor,docs,tasks文件夹以及PROJECT.md文件。此时框架的“骨架”已经就位但还没有血肉——它还不了解你的具体技术栈和项目规范。3.2 运行交互式设置向导核心步骤这是整个初始化过程的“魔法时刻”。在Cursor中打开你的项目确保位于项目根目录然后在聊天框中输入cursor-setup按下回车cursor-setup技能就会被激活。这个向导会像一位经验丰富的DevOps工程师一样引导你完成以下步骤项目扫描与分析它会自动扫描你的代码库识别项目类型是React应用还是Spring Boot服务、主要编程语言、使用的框架和关键依赖。这个分析过程非常关键决定了后续生成规则和技能的针对性。交互式问答向导会提出一系列问题来澄清你的项目目标、架构偏好和团队规范。例如“你的项目主要是一个Web前端应用对吗”“你希望强制使用TypeScript的严格模式吗”“你的团队使用怎样的Git分支策略例如Git Flow, GitHub Flow”“你希望集成哪些代码质量工具ESLint, Prettier, 特定的测试框架” 请务必认真回答这些问题你的回答将直接写入生成的配置文件中。工具安装与配置向导会建议并引导你安装Context7一个用于增强AI代码理解能力的工具以及其他相关的MCPModel Context Protocol工具。它会提供具体的安装命令如npx ctx7 setup。生成项目专属资产这是最核心的输出阶段。向导会根据你的回答和项目扫描结果动态生成定制化的PRD模板(docs/PRD.md)一个结构化的产品需求文档框架。项目专属的Cursor规则(.cursor/rules/*.mdc)例如为React项目生成react-patterns.mdc里面会包含Hooks使用规范、组件设计原则等。一整套完整的技能(.cursor/skills/下的多个子目录)除了基础技能还会生成针对你技术栈的debugger、test-writing、[tool]-verification如eslint-verification等。整个过程大约需要5-10分钟。完成后你的项目就从一个普通的代码仓库升级为一个搭载了“AI副驾驶操作系统”的智能开发环境。3.3 初始化后的目录结构详解运行完cursor-setup后你的项目结构会变得非常丰富且有组织。理解每个目录和文件的职责有助于你后续进行自定义。你的项目根目录/ ├── .cursor/ # Cursor 配置核心 │ ├── rules/ # 规则库由cursor-setup生成 │ │ ├── project-conventions.mdc # 项目级铁律始终生效 │ │ ├── react-patterns.mdc # React特定编码模式打开.tsx/.ts文件时生效 │ │ └── test-patterns.mdc # 测试规范打开.spec/.test文件时生效 │ │ │ └── skills/ # 技能库基础生成 │ ├── cursor-setup/ # 初始化向导已使用 │ ├── new-feature/ # 新功能总控 │ ├── architecture-guard/ # 架构审查 │ ├── debugger/ # 针对你技术栈的调试指南 │ ├── module-creation/ # 模块脚手架如生成Redux slice或API route │ └── ...更多生成的技能 │ ├── docs/ # 文档中心 │ ├── PRD.md # 产品需求文档动态维护 │ ├── specs/ # 存放每个功能的详细设计规范 │ └── decisions/ # 架构决策记录ADR记录重大技术选择原因 │ ├── tasks/ # 任务管理 │ ├── lessons.md # “十大经验教训”每次开发前可快速浏览 │ └── todo.md # 当前进行中的任务列表 │ └── PROJECT.md # 项目模块注册表记录所有重要模块及其职责实操心得不要害怕cursor-setup生成的文件多。这些文件是高度模块化的你可以随时根据团队实际情况进行微调。例如如果团队引入了新的状态管理库你可以手动编辑project-conventions.mdc和react-patterns.mdc来增加相应的规则。这个目录结构本身就是一套优秀的文档实践。4. 核心技能链实战以开发一个新功能为例现在让我们进入最激动人心的部分实际使用这套工作流来开发一个功能。假设我们要在一个React TypeScript的前端项目中添加一个“用户个人资料编辑”页面。4.1 发起任务调用new-feature在Cursor的聊天框中我们输入new-feature 我们需要一个用户个人资料编辑页面。页面应该包含表单允许用户更新头像、昵称、个人简介。表单需要有验证提交后调用更新用户的API。同时需要一个新的路由 /profile/edit 来访问这个页面。发送指令后new-feature技能被激活。它首先会分析这个描述的复杂度涉及新页面、新路由、表单逻辑、API调用显然属于复杂任务。于是它自动进入了路径A完整功能。4.2 阶段A1需求澄清与细化AI不会立刻开始写代码。它会先进入“澄清模式”可能会提出一些阻塞性的关键问题以确保理解无误。例如它可能会问“请问更新用户的API端点是什么请求体和响应体的格式能否提供示例”“对于头像上传是使用本地上传还是提供URL如果需要上传有现成的组件或服务吗”“表单验证的具体规则是什么昵称的长度限制个人简介是否必填”注意事项这个阶段AI只会问真正影响设计和实现的阻塞性问题。对于不明确的细节它可能会基于现有代码库的惯例进行合理的假设并在后续的设计中体现出来。你的回答越精确后续步骤的返工就越少。理想情况下你应该将详细的API文档或设计稿链接粘贴给它。4.3 阶段A2架构守卫审查在得到关键信息后new-feature会调用architecture-guard技能。这个技能就像一个严格的架构师它会检查层级违规这个新功能应该放在哪个代码层级是放在src/features/profile/下还是src/pages/profile/它会根据你项目中现有的架构模式比如是否使用了Feature-based结构给出建议或警告。依赖关系新的页面组件是否会引入不合理的依赖例如是否试图在UI组件中直接导入数据访问层的模块命名冲突检查PROJECT.md中的模块注册表确保新模块的名称不会与现有模块冲突。如果架构守卫发现了问题它会强制停止流程并给出修改建议。你必须解决这些问题才能继续。这个“硬停止”机制是保证代码库架构整洁的关键防火墙。4.4 阶段A3生成设计方案与等待批准通过架构审查后AI会开始进行高层设计HLD和底层设计LLD。它可能会在聊天框中输出文件结构图展示将要创建的所有文件如EditProfilePage.tsx,EditProfileForm.tsx,validationSchema.ts,api.ts,index.ts等及其位置。组件关系图说明各个UI组件如何嵌套和通信。数据流图展示用户操作如何触发状态变化、API调用和UI更新。然后流程会明确地暂停并提示“设计已完成。请审查以上方案确认无误后输入‘继续’以开始实现。”实操心得千万不要跳过这个确认步骤这是人类开发者保持控制力的最重要环节。仔细检查AI生成的设计目录结构是否符合团队约定组件拆分是否合理如果发现问题现在就是最好的修改时机。你可以直接告诉AI“将validationSchema合并到EditProfileForm组件里我们不希望有太多零散文件。” AI会根据你的反馈调整设计然后再次等待你的确认。4.5 阶段A4-A6分层实现与自动化验证在你批准设计后魔法开始了。AI会进入实现阶段但它不是一口气写完所有代码而是分层、分步骤地进行创建模块与基础文件首先它会调用module-creation技能按照设计图创建所有必要的目录和空的骨架文件。实现第一层例如API层AI会先编写调用后端API的服务函数包括类型定义、请求配置和错误处理。完成后它会自动调用eslint-verification和build技能检查代码风格并确保项目能编译通过。实现第二层例如表单逻辑与验证层接着编写表单的React Hook Form配置、Yup验证模式等。完成后再次进行代码验证。实现第三层UI组件层最后编写实际的React组件TSX。每完成一个组件都可能触发一次验证。集成与路由将所有部分组合起来并配置路由如在App.tsx或路由文件中添加新路由。完整验证所有代码编写完毕后new-feature会发起一轮全面的验证链lint代码风格、build构建、test运行测试如果已有相关测试、code-review模拟代码审查检查常见问题。这个过程模拟了优秀工程师的编码习惯小步快跑持续验证。每次验证就像一次微型的CI确保每一步的产出都是可工作的极大降低了最后集成时出现复杂错误的概率。4.7 阶段A7提交前最终检查在最终验证通过后new-feature会调用pr-checklist技能。这个技能会生成一份详尽的清单供你在创建Pull Request前进行最终的人工复核。清单可能包括[ ] 功能是否与原始需求描述一致[ ] 所有新的代码是否都有适当的单元测试或集成测试[ ] 代码是否遵循了项目的.cursor/rules/中定义的所有模式[ ] 是否有控制台警告或错误[ ] 是否更新了相关的文档如PROJECT.md中的模块注册表只有当你手动勾选完这些项目整个new-feature流程才算是圆满结束。此时你已经获得了一个经过多轮自动化检查和人工确认的、高质量的、可立即提交的代码变更集。5. 高级技巧与自定义配置指南5.1 如何定制属于自己团队的规则项目自带的规则是通用的起点真正的威力在于定制。编辑.cursor/rules/下的.mdc文件你可以植入团队的“灵魂”。在project-conventions.mdc中定义核心原则// .cursor/rules/project-conventions.mdc alwaysApply: true # 核心架构约束 - 禁止在 components/ 目录下的UI组件中直接使用 fetch 或 axios所有数据获取必须通过 src/lib/api/ 下的服务模块。 - 所有React组件必须使用 React.memo 进行包裹除非有明确理由不这样做。 - 错误处理必须使用团队统一的 ErrorBoundary 组件和 notifyError 工具函数禁止直接 console.error。 - 状态管理必须使用Zustand禁止新增Redux代码。 # Git规范 - 提交信息必须遵循Conventional Commits格式feat:, fix:, chore:等。 - 分支命名feat/short-description, fix/issue-123。这些规则具有最高优先级AI在项目的任何地方写代码时都会遵守。在语言模式规则中定义最佳实践// .cursor/rules/react-patterns.mdc alwaysApply: false globs: [**/*.tsx, **/*.ts] # React with TypeScript 模式 - 组件Props必须使用 interface 定义并以 组件名Props 命名。 - 优先使用 const MyComponent: React.FCMyComponentProps ({ prop1 }) { ... } 形式声明组件。 - 自定义Hook必须以 use 前缀开头且内部逻辑必须与渲染无关。 - 避免使用 any 类型如果必须使用需添加 // eslint-disable-next-line typescript-eslint/no-explicit-any 注释并说明理由。5.2 创建你自己的专属技能当团队反复处理某一类特定任务时将其固化为技能能极大提升效率。例如团队经常需要对接某个特定的第三方支付API每次都要查文档、写类似的初始化代码和错误处理。你可以在.cursor/skills/下创建一个新目录比如stripe-integration/里面放一个skill.md文件# stripe-integration - 集成Stripe支付 ## 目标 快速在项目中添加Stripe支付功能。 ## 前置条件 1. 已拥有Stripe账户和API密钥。 2. 项目已安装 stripe 和 stripe/react-stripe-js 包。 ## 步骤 1. **环境变量**在 .env.local 中添加 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY 和 STRIPE_SECRET_KEY。 2. **服务端API路由**在 pages/api/payment/ 下创建 create-intent.js使用以下模板... 3. **前端支付组件**使用 Elements 和 CardElement 包裹支付表单。示例代码... 4. **错误处理**必须捕获并处理 StripeCardError, StripeInvalidRequestError。 ## 参考链接 - Stripe官方文档: https://stripe.com/docs - 团队内部示例项目: [链接]创建完成后任何团队成员或AI只需要输入stripe-integration就能获得一套标准化的、符合团队最佳实践的集成指南。5.3 与项目管理工具集成项目预设支持与Linear、Jira等工具集成。如果团队使用Linearcursor-setup向导可能会检测到.linear配置文件并生成linear-do技能。这个技能可以读取Linear中的任务列表。根据任务创建分支。在实现过程中自动更新任务状态如“进行中”、“待评审”。在PR创建后自动将PR链接关联到Linear任务。这实现了从任务管理到代码开发再到交付的轻度自动化流水线让AI助手真正融入团队的DevOps流程。6. 常见问题排查与效能提升技巧6.1 技能调用失败或行为异常问题输入new-feature后无反应或AI回复“我不理解这个命令”。排查首先检查.cursor/skills/目录下是否存在new-feature/文件夹及里面的skill.md文件。可能是复制文件时遗漏了。解决确保技能目录结构正确并尝试在Cursor中重新加载项目关闭再打开项目文件夹。问题AI在执行技能时似乎忽略了.cursor/rules/中的某条规则。排查检查该规则文件的语法。alwaysApply: true必须写在文件顶部。对于模式规则确认globs模式是否能匹配到你的目标文件。解决一个常见技巧是在规则文件中使用更具体的描述。与其说“代码要整洁”不如说“每个函数行数不超过30行”、“if-else必须包含大括号”。AI对具体、可执行的指令理解得更好。6.2 生成的代码质量不符合预期问题AI生成的代码虽然能运行但设计模式陈旧或不符合团队最新规范。解决规则和技能需要持续维护。当团队引入新的库如从Redux迁移到Zustand或确立新的模式时必须同步更新.cursor/rules/下的文件。把维护这些文件视为一项重要的技术债务偿还任务。问题AI在复杂业务逻辑上容易“胡编乱造”API或数据结构。解决充分利用prd-spec技能和docs/specs/目录。在启动new-feature之前或者在其澄清阶段A1强烈建议先手动或通过prd-spec编写一份详细的设计规范Spec明确列出所有的接口定义、数据模型、状态流。然后将此规范文件作为上下文提供给AI。给AI的上下文越精确它的输出就越可靠。6.3 如何最大化工作流效率从“小任务”开始培养信任不要一开始就让AI处理最核心、最复杂的模块。先用它来生成工具函数、写单元测试、修复简单的bug走Route B。在低风险任务中磨合让你和团队熟悉它的“工作方式”同时逐步完善规则。投资“技能”建设将团队内部的技术分享、代码审查中的常见反馈、解决复杂Bug的“独门秘籍”沉淀为技能。这是构建团队AI知识库的过程其回报是长期且复利的。人类负责战略AI负责战术始终牢记你是架构师和产品负责人AI是高效的执行工程师。你的职责是在A3阶段审批设计在关键节点做出业务决策。AI的职责是将你批准的设计快速、无误地转化为高质量的代码。不要陷入让AI做产品决策的误区。定期回顾与优化每隔一段时间和团队一起回顾tasks/lessons.md并将在使用过程中学到的新经验补充进去。同时检查哪些规则形同虚设哪些技能使用频率低进行迭代和清理。这套工作流不是一个“安装即忘”的工具而是一个需要与你共同成长的“伙伴”。你为它注入的规则和智慧越多它反馈给你的效率和质量提升就越大。它最终的目标是让开发者从重复、繁琐、模式化的编码劳动中解放出来更专注于创造性的架构设计和复杂的业务逻辑破解。