Cursor SDD Starter：AI驱动开发工作流工程化实践指南

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能力“工程化”的基石。它包含两大核心配置体系：

1. 规则（.mdc文件）：位于.cursor/rules/目录下。你可以把它理解为项目的“宪法”和“地方法规”。

   • 项目级规则（project-conventions.mdc）：设置了alwaysApply: true，意味着只要项目在Cursor中打开，这些规则就会一直加载到AI的上下文中。这里应该放置那些绝对不容违反的架构约束和团队约定，例如：“所有API响应必须包裹在统一的ApiResponse对象中”、“禁止在业务逻辑层直接操作数据库连接”。
   • 模式规则（[lang]-patterns.mdc,test-patterns.mdc）：这些规则通过globs配置（如**/*.ts），只在打开对应语言文件时才生效。它们定义了具体的编码模式，例如：“React组件必须使用函数式声明和TypeScript”、“Python的异常处理必须包含具体的错误日志”。

2. 技能（.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工程师一样，引导你完成以下步骤：

1. 项目扫描与分析：它会自动扫描你的代码库，识别项目类型（是React应用还是Spring Boot服务？）、主要编程语言、使用的框架和关键依赖。这个分析过程非常关键，决定了后续生成规则和技能的针对性。
2. 交互式问答：向导会提出一系列问题来澄清你的项目目标、架构偏好和团队规范。例如：
   • “你的项目主要是一个Web前端应用，对吗？”
   • “你希望强制使用TypeScript的严格模式吗？”
   • “你的团队使用怎样的Git分支策略？（例如：Git Flow, GitHub Flow）”
   • “你希望集成哪些代码质量工具？（ESLint, Prettier, 特定的测试框架）” 请务必认真回答这些问题，你的回答将直接写入生成的配置文件中。
3. 工具安装与配置：向导会建议并引导你安装Context7（一个用于增强AI代码理解能力的工具）以及其他相关的MCP（Model Context Protocol）工具。它会提供具体的安装命令（如npx ctx7 setup）。
4. 生成项目专属资产：这是最核心的输出阶段。向导会根据你的回答和项目扫描结果，动态生成：
   • 定制化的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会进入实现阶段，但它不是一口气写完所有代码，而是分层、分步骤地进行：

1. 创建模块与基础文件：首先，它会调用@module-creation技能，按照设计图创建所有必要的目录和空的骨架文件。
2. 实现第一层（例如，API层）：AI会先编写调用后端API的服务函数，包括类型定义、请求配置和错误处理。完成后，它会自动调用@eslint-verification和@build技能，检查代码风格并确保项目能编译通过。
3. 实现第二层（例如，表单逻辑与验证层）：接着编写表单的React Hook Form配置、Yup验证模式等。完成后，再次进行代码验证。
4. 实现第三层（UI组件层）：最后编写实际的React组件（TSX）。每完成一个组件，都可能触发一次验证。
5. 集成与路由：将所有部分组合起来，并配置路由（如在App.tsx或路由文件中添加新路由）。
6. 完整验证：所有代码编写完毕后，@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.FC<MyComponentProps> = ({ 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等工具集成。如果团队使用Linear，@cursor-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 如何最大化工作流效率

1. 从“小任务”开始培养信任：不要一开始就让AI处理最核心、最复杂的模块。先用它来生成工具函数、写单元测试、修复简单的bug（走Route B）。在低风险任务中磨合，让你和团队熟悉它的“工作方式”，同时逐步完善规则。
2. 投资“技能”建设：将团队内部的技术分享、代码审查中的常见反馈、解决复杂Bug的“独门秘籍”沉淀为技能。这是构建团队AI知识库的过程，其回报是长期且复利的。
3. 人类负责战略，AI负责战术：始终牢记，你是架构师和产品负责人，AI是高效的执行工程师。你的职责是：在A3阶段审批设计，在关键节点做出业务决策。AI的职责是：将你批准的设计，快速、无误地转化为高质量的代码。不要陷入让AI做产品决策的误区。
4. 定期回顾与优化：每隔一段时间，和团队一起回顾tasks/lessons.md，并将在使用过程中学到的新经验补充进去。同时，检查哪些规则形同虚设，哪些技能使用频率低，进行迭代和清理。

这套工作流不是一个“安装即忘”的工具，而是一个需要与你共同成长的“伙伴”。你为它注入的规则和智慧越多，它反馈给你的效率和质量提升就越大。它最终的目标，是让开发者从重复、繁琐、模式化的编码劳动中解放出来，更专注于创造性的架构设计和复杂的业务逻辑破解。