AI优先的独立开发脚手架：Cursor Solo Dev Template 实战指南

1. 项目概述一个为AI编程时代量身定制的项目脚手架如果你和我一样是一个习惯单打独斗的独立开发者并且已经深度依赖像 Cursor 这样的 AI 辅助编辑器来提升效率那你肯定遇到过这样的场景每次开启一个新项目都要重新设置一遍规则文件、整理项目结构、定义工作流。这个过程不仅重复而且容易遗漏关键配置导致 AI 助手无论是 Claude 还是其他模型对你的项目上下文理解不深给出的建议总是差那么点意思。这个名为“Cursor Solo Dev Template”的模板就是为了解决这个痛点而生的。它不是一个普通的项目脚手架而是一个“AI 优先”的完整工作流系统。它的核心目标非常明确让你作为“飞行员”指挥 AI “副驾驶”Claude驾驶 Cursor 这架“飞机”能够更精准、更高效地完成从零到一的构建并且能果断地在“完成”或“放弃”之间做出决策彻底避免项目范围蔓延。简单来说它通过一套预设的规则、记忆文件和状态管理机制将你的项目意图、代码风格、架构决策和工作流程“固化”下来让 AI 从项目启动的第一分钟起就和你保持在同一个频道上。我使用这个模板启动过几个小项目后最大的感受是前期花在“对齐”上的沟通成本大幅降低我可以更专注于真正的逻辑构建而不是反复向 AI 解释“我这里想要什么风格”、“那个功能我们不做”。2. 核心设计哲学为确定性而生的轻量级工作流这个模板的设计背后蕴含着一套清晰且经过实践检验的哲学其文档FRAMEWORK.md里提到了“研究支持的实践”。我深入理解后认为其核心可以概括为“为不确定性注入确定性”。独立开发尤其是与 AI 协作时最大的挑战来自两方面一是项目目标的漂移Scope Creep二是上下文的断裂。这个模板通过几个关键设计巧妙地应对了这些挑战。2.1 冻结的愿景DONE.md与范围控制docs/DONE.md文件是这个模板的灵魂。它的作用不是记录“要做的事”而是明确且冻结地定义“什么是完成v1.0”。在项目开始前你必须在这里写下 v1.0 版本必须具备的核心功能列表以及同样重要的——“不构建清单”Kill List。为什么这至关重要在与 AI 协作时AI 可能会基于对话历史提出各种“这个功能也不错”、“那个特性可以加上”的建议。如果没有一个权威的、书面的“完成定义”开发者很容易被带偏陷入不断添加功能的泥潭。DONE.md就是一个锚点。当你在编码中感到迷茫或受到诱惑时回头看看这个文件如果某个想法不在“完成清单”里那就坚决不做如果它在“不构建清单”里那就更不用考虑。这强制你践行“要么交付要么放弃”的极简主义是抵御范围蔓延最有效的防线。我的实操心得是填写DONE.md时要像写产品需求文档一样具体但更精简。例如不要写“实现用户认证”而要写“v1.0 完成1. 基于邮箱和密码的注册与登录 API 端点2. 登录后颁发 JWT 令牌3. 受保护的路由需要验证 JWT”。同时在“不构建清单”里明确写上“不包含第三方 OAuth 登录、密码重置邮件、用户个人资料页”。2.2 动态的上下文memory/目录与 AI 记忆管理如果说DONE.md是宪法那么memory/目录就是不断更新的司法解释和案例库。Cursor IDE 的一个强大特性是能读取特定目录下的 Markdown 文件作为会话上下文。这个模板预置了memory/00-project.md等文件让你系统地管理 AI 需要知道的背景信息。这里的精妙之处在于“分层记忆”00-project.md项目最高层级的描述包括目标用户、核心价值主张、技术栈选择理由。这是 AI 理解项目“为什么存在”的基础。01-architecture.md系统架构图用文字或代码描述、核心数据流、模块职责划分。这帮助 AI 理解代码应该如何组织新的功能应该放在哪个模块。02-decisions.md记录所有重要的技术决策及其原因。比如“为什么选择 SQLite 而非 PostgreSQL”“为什么前端用 React 而不是 Vue”。这能避免 AI 在后续会话中提出已经被否决的方案或者当你隔几天再回来时自己都忘了当初为什么这么选。我的经验是要像写开发日志一样维护memory/下的文件。每当做出一个关键选择或对架构有新的理解就立即更新进去。这相当于为你的 AI 副驾驶提供了一个持续更新的飞行手册确保它无论何时加入对话都对项目的最新状态了如指掌。2.3 即时的心跳STATUS.md与TASKS.mdSTATUS.md文件被设计为“3 行会话锚点”NOW现在在做什么、NEXT接下来做什么、BLOCKED被什么阻塞了。这看起来简单但威力巨大。它的核心价值是降低启动摩擦。很多时候项目搁置是因为再次打开时不知道从何下手。有了STATUS.md你只需要花 30 秒更新这三行就能立刻回到上次中断的上下文。对于 AI 来说它也能精准地知道你现在卡在哪里从而提供更有针对性的帮助而不是泛泛地问“需要我做什么”TASKS.md则是更具体的任务清单并且引入了ICE 优先级模型Impact, Confidence, Ease。这鼓励你对每个任务进行量化评估优先处理那些影响力大、成功信心高、且容易实现的功能。这不仅是项目管理的好方法也能让 AI 在帮你拆解任务或生成代码时更聚焦于高价值部分。注意不要过度规划TASKS.md。我的习惯是只规划接下来 1-2 个迭代周期比如一周内明确要做的任务。更远的未来就只有一个大致方向留在memory/里描述即可。过度详细的长远计划在快速迭代的 solo 开发中反而会成为负担。3. 模板结构深度解析与实操配置光有理念不够我们来看看这个模板具体提供了哪些“武器”以及如何让它们发挥最大效力。3.1.cursor/rules/定义与AI协作的“交通规则”这个目录下的.mdc文件是 Cursor 的规则文件它们会被 Cursor 自动加载并直接影响 AI 的行为。模板预置了五类规则构成了与 AI 协作的基本法。project.mdc定义项目级规则。这里你应该写明项目的核心约束比如“这是一个使用 Next.js 14 App Router 的全栈项目”、“所有 API 响应必须遵循 RESTful 规范”、“主要使用 TypeScript仅在配置文件中使用 JavaScript”。code-style.mdc定义代码风格。这是保证代码一致性的关键。你可以具体规定缩进2空格还是4空格、引号单引号还是双引号、分号使用、命名约定函数用 camelCase组件用 PascalCase、导入排序规则等。有了这个AI 生成的代码在风格上就会与你已有的代码库高度一致省去大量格式化时间。memory.mdc告诉 AI 如何读取记忆。通常会指向memory/目录并指示 AI 在每次会话时优先阅读这些文件以获取上下文。workflow.mdc定义工作流程。例如“在实现新功能前请先参考TASKS.md和STATUS.md”、“所有的数据库查询必须放在src/core/repositories/目录下”、“提交代码前必须运行scripts/test.bat”。no-go.mdc明确禁止事项。这是“不构建清单”在代码层面的延伸。比如“禁止使用any类型”、“禁止直接在前端组件中写硬编码的 API URL”、“禁止引入moment.js库请使用date-fns”。配置心得不要一次性写完所有规则。建议在项目初期只设置最关键的几条如技术栈、基本代码风格然后在开发过程中每当发现 AI 反复出现某种你不希望的行为时就将其作为一条新规则添加到相应的.mdc文件中。这样积累下来的规则集才是最贴合你个人习惯和项目需求的。3.2src/目录结构清晰关注点分离的脚手架模板预置的src/结构采用了一种非常直观的隐喻式分类有助于保持代码的条理性core/(大脑)存放纯粹的业务逻辑、领域模型、计算规则。这里应该不包含任何框架特定的代码如 HTTP 请求处理、数据库操作。例如一个“计算订单折扣”的函数就应该放在这里。api/(管道)处理数据的输入和输出。包括 REST API 路由、GraphQL Resolvers、数据库查询封装ORM 模型或查询构造器、外部服务客户端等。它从core/获取逻辑与外部世界通信。ui/(脸面)用户界面层。对于 Web 项目这里就是 React/Vue 组件对于 CLI 工具这里就是命令行交互逻辑。它调用api/来获取或提交数据。utils/(工具)共享的辅助函数、常量、配置。应该是纯函数或无副作用的工具类。这种结构强迫你在写代码时思考“这段代码属于哪个部分” 这能有效减少模块间的耦合也让 AI 更容易理解在哪里添加新功能。比如当你对 AI 说“添加一个用户注册功能”AI 会知道要去core/创建用户实体逻辑去api/创建注册端点去ui/创建注册表单组件。3.3scripts/自动化脚本一键式开发体验模板提供了 Windows 批处理脚本.bat对于 macOS/Linux 用户需要自行转换为 Shell 脚本.sh。这些脚本的价值在于将常用命令固化减少记忆负担和输入错误。setup.bat通常包含安装依赖npm install,pip install -r requirements.txt、环境变量配置、数据库初始化等。确保任何克隆项目的人都能通过一条命令进入可开发状态。run.bat启动开发服务器。可能同时启动前端和后端服务如concurrently。test.bat运行测试套件。配置好这个就能轻松实践“运行测试”的规则。clean.bat清理构建产物、缓存、日志文件。保持工作区整洁。一个高级技巧你可以在scripts/里添加更多自动化脚本比如deploy.bat部署、db-migrate.bat数据库迁移、generate-component.bat基于模板生成组件。将这些流程脚本化不仅能提升效率也能让 AI 通过规则文件知道如何执行这些标准操作。4. 从零开始使用模板启动一个真实项目让我们以一个具体的例子走一遍使用这个模板启动一个全栈待办事项应用Todo App的完整流程。假设我们使用 Next.js (App Router) Prisma SQLite Tailwind CSS 的技术栈。4.1 第一步克隆与初始化点击模板仓库的 “Use this template” 按钮创建一个属于你自己的新仓库命名为next-todo-app。将仓库克隆到本地git clone your-repo-url。进入项目目录我们首先处理记忆文件。打开memory/00-project.md填写项目核心信息# 项目极简全栈待办事项应用 **一句话描述**我构建一个极简的全栈待办事项应用让个人用户能够快速记录和管理任务以便他们能专注于执行而非工具本身。 **目标用户**需要轻量级、无干扰任务管理的个人用户厌恶功能臃肿的复杂应用。 **核心价值** - **极速启动**打开即用无需复杂设置。 - **数据自治**数据存储在本地 SQLite完全私有。 - **离线可用**基于 Next.js支持基础离线功能。 **技术栈选择理由** - **Next.js 14 (App Router)**提供全栈能力、服务端渲染、简单的部署体验Vercel。 - **Prisma SQLite**Prisma 提供类型安全的数据库访问SQLite 无需单独数据库服务简化部署。 - **Tailwind CSS**快速实现无设计的实用主义 UI。 - **TypeScript**提升代码可靠性和开发体验。打开docs/DONE.md定义 v1.0 范围# v1.0 完成定义 (冻结) ## 核心功能 (必须完成) 1. 用户界面 - 一个主页面展示所有待办事项列表。 - 每个待办事项显示文本内容、创建时间、完成状态复选框。 - 列表顶部有一个输入框和“添加”按钮用于创建新待办事项。 - 支持标记待办事项为完成/未完成点击复选框。 - 支持删除待办事项每个事项旁有删除按钮。 2. 数据持久化 - 所有待办事项数据持久化存储在本地 SQLite 数据库中。 - 页面刷新或重新打开后数据不丢失。 3. 基本交互 - 添加、切换完成状态、删除操作无需页面刷新使用 React 状态更新和 API 路由。 ## 不构建清单 (v1.0 明确不做) 1. 用户账户系统登录/注册。 2. 多列表或分类标签。 3. 任务优先级、截止日期、提醒。 4. 数据同步到云端。 5. 移动端原生应用。 6. 复杂的动画或过渡效果。4.2 第二步配置规则与架构配置.cursor/rules/project.mdc这是一个使用 Next.js 14 (App Router) 的全栈 TypeScript 项目。 前端使用 React 和 Tailwind CSS 进行样式开发。 后端逻辑在 Next.js API Route 中实现使用 Prisma ORM 连接 SQLite 数据库。 项目遵循模板预设的 src/core/, src/api/, src/ui/, src/utils/ 结构。 所有代码必须使用 TypeScript 并遵循严格的类型定义。配置.cursor/rules/code-style.mdc使用 2 个空格进行缩进。 使用单引号 () 定义字符串仅在 JSX 属性需要时使用双引号。 语句末尾不加分号。 使用 camelCase 命名变量和函数。 使用 PascalCase 命名 React 组件、接口和类型。 使用 kebab-case 命名文件组件文件使用 .tsx工具文件使用 .ts。 导入必须分组并按以下顺序排序1. 外部库2. 内部绝对路径导入3. 内部相对路径导入4. 类型导入。创建memory/01-architecture.md# 系统架构 ## 数据流 1. 用户在前端 (src/ui/) 组件中交互如点击添加按钮。 2. 前端组件调用自定义 Hook 或函数位于 src/ui/lib/该函数向对应的 Next.js API Route (src/app/api/) 发起 HTTP 请求。 3. API Route 作为控制器接收请求调用 src/core/ 中的业务逻辑函数进行处理。 4. 业务逻辑函数通过 src/api/repositories/ 下的 Prisma 客户端与 SQLite 数据库交互。 5. 数据库操作结果沿原路返回最终更新前端 React 状态触发 UI 重新渲染。 ## 数据库模型 (Prisma Schema) 位于 prisma/schema.prisma。 初始模型只有一个 Todo - id (String id default(cuid())) - title (String) - 任务内容 - completed (Boolean default(false)) - 是否完成 - createdAt (DateTime default(now())) - 创建时间4.3 第三步开始构建与迭代运行scripts/setup.bat你需要先根据你的环境创建这个脚本内容大致是npm install和npx prisma generate。打开STATUS.md写下NOW: 初始化项目设置 Prisma 和 SQLite。 NEXT: 创建 Todo 的 Prisma 模型和基础 API 路由。 BLOCKED: 无。现在你可以直接对 Cursor 的 AI 说“根据我们的架构和规则初始化 Prisma创建 Todo 模型并生成迁移。” 由于你已经配置了完整的上下文AI 会给出非常精准的命令和代码。完成一步后更新STATUS.md并在TASKS.md中标记任务完成添加新任务。例如在TASKS.md中添加- [ ] 实现 GET /api/todos API 路由 | Impact: High, Confidence: High, Ease: High - [ ] 实现 POST /api/todos API 路由 | Impact: High, Confidence: High, Ease: High - [ ] 创建前端 TodoList 组件 | Impact: High, Confidence: Medium, Ease: Medium持续循环这个过程更新状态 - 通过 AI 实现任务 - 提交代码 - 更新状态。始终以DONE.md为最终验收标准。5. 常见问题、排查技巧与进阶玩法在实际使用中你可能会遇到一些典型问题。以下是我踩过坑后总结的经验。5.1 AI 似乎“忘记”了规则或记忆这是最常见的问题。首先检查规则文件格式确保.mdc文件语法正确没有损坏。可以尝试在 Cursor 中手动输入/rules命令查看当前加载的规则列表。记忆文件路径确认memory.mdc规则正确指向了memory/目录。有时需要重启 Cursor 或重新打开项目来强制重新加载所有规则。会话隔离Cursor 的上下文有时会受会话影响。尝试开启一个新会话新 Chat 窗口并确保在设置中勾选了“自动加载项目规则”。信息过载如果memory/文件过长AI 可能无法有效处理全部信息。尝试精简内容只保留最关键的信息或将长篇文档拆分成更聚焦的多个小文件。5.2 如何将模板适配到非 JavaScript/TypeScript 项目这个模板的理念是通用的但具体实现需要调整。src/结构你可以保留core/,api/,ui/,utils/的隐喻但具体技术实现不同。例如一个 Python Flask 后端项目api/就是你的视图函数app/routes/core/就是业务逻辑层app/services/或app/logic/。规则文件重写.cursor/rules下的所有文件以反映新语言和框架的约定。例如code-style.mdc要定义 Python 的 PEP 8 规范、导入排序等。脚本文件将.bat脚本重写为适合你平台的脚本如.shfor Unix,.ps1for PowerShell并修改其中的命令如将npm run dev改为flask run或python main.py。5.3 在团队中能使用这个模板吗虽然名为“Solo Dev”但其核心——清晰的上下文管理、冻结的范围定义、一致的工作流——对小型团队同样有价值。团队使用时需要关注共享记忆确保memory/目录下的文件是团队共识并且及时更新。可以考虑将其作为代码审查的一部分。统一的规则团队所有成员应使用相同或高度相似的.cursor/rules配置以保证代码风格和 AI 交互方式的一致性。状态同步STATUS.md可能不太适合多人并行开发。可以将其升级为使用简单的看板工具如 GitHub Projects或每日站会来同步状态但保留其“NOW/NEXT/BLOCKED”的核心精神。5.4 如何管理模板本身的更新你可能会在自己的项目中对此模板进行定制。建议将原模板仓库 fork 一份作为你的“基础模板”。在自己的项目中使用 fork 后的模板。如果你发现了一些通用性改进可以向原模板仓库提交 Pull Request。对于你个人的定制比如公司内部特定的技术栈规则可以维护一个你自己的分支。当原模板有更新时可以尝试将更新合并到你的分支中。5.5 进阶将 AI 提示词工程融入模板这个模板已经为 AI 提供了丰富的上下文。你可以更进一步在memory/中创建专门的提示词文件例如memory/03-prompts.md里面存放针对你项目常见任务的、精心设计的提示词。例如# 高效提示词库 ## 创建新的 API 端点 “请遵循我们的架构在 src/app/api/todos/[id]/ 下创建一个处理 DELETE 请求的 API Route。它应该 1. 从路由参数中获取 id。 2. 调用 core/services/todoService.deleteTodo(id)。 3. 处理可能的错误如未找到记录并返回适当的 HTTP 状态码和 JSON 响应。 4. 在 src/core/services/ 中实现对应的 deleteTodo 函数该函数通过 api/repositories/todoRepository 访问数据库。 请先生成代码框架我确认后再填充细节。”这样当你需要执行一个重复模式的任务时可以直接复制粘贴这些结构化的提示词极大提升与 AI 的协作效率。最后我想分享一点个人体会这个模板最大的价值不在于它预设了什么文件夹或文件而在于它强制你养成一种结构化思考和工作的习惯。它让你在 AI 的强大能力面前依然能保持清晰的主线做项目的“飞行员”而不是被 AI 的“可能性”带着跑偏。当你习惯了在开始写第一行代码前先定义好DONE.md维护好memory/你会发现不仅 AI 成了更得力的助手你自己的开发思路也变得更加清晰和高效。它更像是一个关于如何与AI协同工作的思维框架而脚手架只是这个框架的具体呈现。