1. 项目概述为AI编程装上“龙骨”如果你和我一样是个独立开发者或者小团队的成员最近肯定没少用 Cursor 这类 AI 编程工具。刚开始那会儿感觉简直像开了挂描述需求代码“唰”一下就出来了效率飞起。但用久了问题就来了AI 生成的代码今天一个风格明天一个写法函数命名随心所欲变量定义天马行空更头疼的是它只管“实现”功能不管“设计”和“测试”代码堆着堆着一个崭新的“屎山”就在你眼皮子底下拔地而起了。后期维护、迭代、加新功能每一步都像在雷区里跳舞。这就是Keel Kit要解决的问题。它不是什么新的编程语言或框架而是一套专门为Cursor设计的IPD集成产品开发流程配置包。你可以把它理解成给 AI 编程过程装上一根“龙骨”——一套强制性的、结构化的思考和工作框架。它的核心是一个名为.cursorrules的配置文件通过一系列精心设计的指令如/plan,/test,/forge引导 AI 在动手写代码之前必须像人类资深工程师一样先进行需求分析、架构设计、安全检查和测试规划。简单说Keel Kit 把企业级软件开发的成熟流程决策、设计、开发、测试、验证做成了 AI 能理解和执行的“剧本”让 AI 从“代码生成器”升级为“有纪律的工程协作者”。它不是为了限制 AI 的创造力恰恰相反是为了让 AI 的创造力能在一个稳固、可维护的工程基础上持续发挥避免项目早期就埋下技术债务的种子。无论你是前端、后端还是全栈开发者只要你用 Cursor 进行日常开发这套工具都能显著提升你与 AI 协作的产出质量和长期可维护性。2. 核心理念与架构拆解为什么是“三层IPD”Keel Kit 的整个设计哲学都建立在IPD集成产品开发的三层架构之上。这不是凭空想出来的花架子而是为了解决 AI 编程中几个最核心的痛点决策随意、设计缺失、开发无序。我们一层层来看。2.1 决策层定下项目的“宪法”这是整个流程的起点也是最容易被忽略的一步。在传统的 AI 编程中我们往往是“边做边想”让 AI 生成一个登录页面它可能用 React再让它加个表单它可能又混入了不同的状态管理思路。技术栈摇摆不定架构风格前后不一项目做到一半才发现基础选型有问题回头成本极高。Keel Kit 的决策层通过/init和/plan两个指令强制把这个“定调子”的工作前置化、显式化。/init- 技术栈与设计风格奠基当你输入/init 我要做一个电商后台管理系统AI 不会立刻开始写代码。它会进入“方案顾问”模式基于你的需求生成2-3 个完整的、可对比的技术方案。每个方案都会包含前端框架组合例如方案A是 React TypeScript Tailwind CSS Zustand方案B是 Vue 3 TypeScript Element Plus Pinia。后端与数据库Node.js (Express/NestJS) 配 MongoDB还是 Python (FastAPI) 配 PostgreSQL部署与运维简单的 Docker Compose还是直接上 Kubernetes 声明文件设计风格遵循 Material Design 3还是采用更简洁的 Ant Design 规范优缺点与成本分析每个方案的学习曲线、社区生态、性能特点、预估的初期搭建成本。实操心得这一步的关键在于“对比”和“选择”。AI 生成的方案可能各有侧重一个偏向开发速度一个偏向长期维护。我通常会要求 AI 从“小型团队快速迭代”和“中大型项目稳健架构”两个角度分别给出方案。用户做出选择后AI 会自动生成tech_stack.md和design_system.md这两个文件。它们就是项目的“宪法”后续所有工作都必须基于此展开从根本上杜绝了技术栈的“漂移”。/plan- 从需求到规格的转换有了技术栈接下来是具体功能。输入/plan 实现一个带JWT鉴权、角色管理和操作日志的用户管理模块。此时AI 会切换成PM产品经理和Arch架构师角色。读取宪法它会先去看刚生成的tech_stack.md知道我们要用 React 和 NestJS。结构化分析然后它会产出两份核心文档specs/TR_DECISION.md这是决策记录。里面会写明这个功能的业务背景、核心用户故事、非功能性需求如性能要求、安全性要求、以及潜在的风险如第三方JWT库的安全漏洞。specs/TR_IMPL.md这是实现规格。它会详细定义 RESTful API 的端点GET /api/users、请求/响应体格式、数据库表结构User, Role, Permission 表及其关系、以及核心的业务逻辑流程图。生成命名锚点同时AI 会生成一份.keel/memory/naming_convention.md。这份文件规定了本项目内各类元素的命名规则例如组件用PascalCase函数用camelCase常量用UPPER_SNAKE_CASEAPI路由遵循kebab-case。这解决了 AI 变量命名混乱的老大难问题。2.2 转换层将蓝图转化为设计稿决策层产出了“做什么”和“用什么做”转换层则解决“长什么样”和“怎么交互”。这是连接产品逻辑与用户界面的桥梁对于前端和全栈项目至关重要。/design- UI/UX 解决方案输入/design 基于TR_IMPL.md中的API设计用户管理后台的列表页、新增和编辑表单的UI。AI 会切换成UX用户体验设计师角色。读取设计规范它会参考design_system.md知道我们的配色主色调是#1890ff圆角是8px使用 Ant Design 组件库。产出设计稿生成specs/UI_DESIGN_SOLUTION.md。这份文档不是图片而是结构化的描述可能包括页面布局采用左右结构左侧导航右侧主内容区。组件树UserManagementPage包含UserTable、SearchBar、ActionButtonGroup。交互逻辑点击“新增”弹出 Modal 表单表格支持按角色筛选删除操作需二次确认。状态定义页面级的loading状态表格的pagination和filters状态。注意事项很多开发者会跳过设计直接开发导致UI与交互反复修改。Keel Kit 强制进行这一步即使产出的是文字描述也迫使开发者和AI在编码前对齐视觉和交互预期大幅减少了返工。对于复杂交互你可以要求AI用伪代码或状态机图来描述逻辑。2.3 执行层SOP化的开发与质量保障这是代码落地的阶段也是 Keel Kit 体现其工程价值最核心的地方。它引入了安全左移和测试驱动开发的理念把质量保障嵌入了开发流程的每一步。/test- 测试先行定义成功标准在写一行业务代码之前先输入/test 为TR_IMPL.md中的用户登录和权限验证API生成单元测试和E2E测试。AI 切换为QA测试角色。读取测试模板参考.keel/templates/test_template.md里的规范例如每个测试用例必须包含Arrange-Act-Assert三段式。生成“失败”的测试在tests/目录下生成auth.service.test.ts和user.e2e.spec.ts。关键点在于这些测试一开始必须是失败的Red。因为功能还没实现。这强制践行了 TDD测试驱动开发的第一步为后续的/forge提供了明确的、可验证的“完工定义”。/forge- 在约束下编写代码现在终于可以输入/forge 实现TR_IMPL.md和UI_DESIGN_SOLUTION.md中描述的用户登录API及前端页面。AI 切换为Builder建造者角色。它的工作不再是自由发挥而是在多重约束下进行依赖检查写import语句前先检查package.json如果发现需要的库如nestjs/jwt不存在会先提示你安装。遵循命名锚点变量、函数、文件的命名必须严格遵循naming_convention.md。遵守安全基线在编写登录逻辑时会自动引用.keel/knowledge/security.md中的规则例如“密码必须加盐哈希存储”、“JWT token 必须设置合理的过期时间”。实现功能最后才是在这些框架内编写出可以通过之前那些失败测试的代码。/verify与/fix- 验收与仲裁代码写完后输入/verify。AI再次作为QA会运行所有测试检查依赖完整性并扫描代码是否符合命名规范。如果全部通过则流程结束。 最精妙的设计在于仲裁机制如果测试失败了AI 不会直接改代码或改测试而是生成一份仲裁报告分析失败原因是“实现代码有Bug”还是“测试用例本身写错了”。由用户来做出最终判断并决定使用/fix修复代码还是手动修正测试用例。这避免了AI在“让测试通过”这个单一目标下可能写出错误逻辑或扭曲测试的隐患。3. 核心配置与目录结构深度解析Keel Kit 的强大和灵活性很大程度上源于其清晰、可扩展的目录结构。它不是黑盒所有规则和模板都是可查看、可编辑的纯文本文件。理解这个结构你才能真正驾驭它。3.1.cursorrules流程的“总控大脑”这个文件是 Keel Kit 的核心它定义了所有指令/init,/plan等的具体行为逻辑。本质上它是一个超级复杂的、结构化的 Prompt 集合。当你输入/plan时Cursor 实际上是将一整套预设的提示词、上下文和指令发送给 AI 模型。一个典型的指令定义会包含角色描述告诉 AI 现在要扮演什么如“你是一位经验丰富的系统架构师”。上下文注入自动将哪些文件如tech_stack.md的内容作为背景信息提供给 AI。任务步骤拆解成一步一步的、具体的子任务。输出格式严格要求 AI 按照指定模板如templates/spec.md的格式生成文档。约束条件例如“在规划前必须先阅读技术栈文档”、“变量命名必须遵循 kebab-case”。实操心得新手不建议直接修改.cursorrules文件因为它逻辑复杂且环环相扣。但当你熟悉了整个流程后可以在这里微调某个指令的细节。比如你觉得/plan生成的决策文档不够详细可以找到对应段落增加一条约束“请额外分析至少两种不同的数据库分表方案及其优劣”。3.2.keel/目录你的项目知识库与武器库这是 Keel Kit 的“弹药库”所有可定制化的部分都在这里。.keel/ ├── knowledge/ # 项目核心知识 │ ├── security.md # 安全红线 │ ├── tech_stack.md # 技术栈圣经/init生成 │ └── design_system.md # 设计语言/init生成 ├── roles/ # AI角色卡 │ ├── pm.md # 产品经理角色定义 │ ├── arch.md # 架构师角色定义 │ ├── ux.md # 设计师角色定义 │ ├── qa.md # 测试工程师角色定义 │ └── builder.md # 开发工程师角色定义 ├── templates/ # 各类产出物模板 │ ├── spec.md # TR_DECISION/IMPL 模板 │ ├── naming_template.md # 命名规范模板 │ ├── test_template.md # 单元/E2E测试模板 │ └── e2e_template.md # 可能合并到test_template └── memory/ # 运行时生成的记忆 └── naming_convention.md # 项目专属命名锚点/plan生成关键目录详解knowledge/- 静态知识security.md这是你需要优先定制的文件。里面预置了一些通用安全规则但你必须根据项目类型添加自己的规则。例如做金融应用必须加入“所有金额计算必须使用 Decimal 类型而非 Float”、“敏感操作必须双因素认证”做医疗应用必须加入“数据传输必须端到端加密”、“审计日志必须记录数据访问者及时间”。tech_stack.md和design_system.md由/init生成是项目的“宪法”。后续所有指令都会读取它们。如果中途想调整技术栈不要直接修改这两个文件而是重新运行/init并描述变更理由让 AI 重新生成并覆盖以保证知识的一致性。roles/- 动态角色每个.md文件定义了一个角色的“人设”。例如qa.md里可能会写“你是一名严谨的测试工程师信奉‘测试是质量的守护者’。你写的测试用例必须边界清晰不仅要覆盖正常流程更要关注异常和边缘情况。你对‘测试通过率’有执念。” 你可以修改这些描述让 AI 的角色行为更符合你的团队文化。templates/- 产出物标准这是控制输出质量的关键杠杆。spec.md模板决定了你的需求文档长什么样test_template.md决定了测试代码的结构。如果你想团队所有项目的 API 文档都遵循 OpenAPI 3.0 格式就可以修改spec.md模板加入必须生成openapi.yaml片段的指令。memory/- 会话记忆这里存放项目运行中生成的、需要被后续步骤引用的信息。目前最主要的就是naming_convention.md。它由/plan根据naming_template.md和具体需求动态生成包含了本项目特有的命名约定如用户服务类名后缀为 ServiceDTO 类名以 Request/Response 结尾。3.3specs/和tests/流程的“交付物”这两个目录是流程的产出。specs/存放所有设计文档是团队包括你和未来的你沟通和追溯的依据。tests/存放所有自动化测试是代码质量的“活文档”和安全网。最佳实践将这些目录纳入版本控制如 Git。它们记录了项目演进的完整决策和实现逻辑价值不亚于源代码本身。4. 完整工作流实战从零构建一个“待办事项”API光说不练假把式。我们用一个最简单的“待办事项TodoAPI”项目走一遍完整的 Keel Kit 流程看看每个环节具体发生了什么以及如何应对实际问题。4.1 阶段0项目初始化 (/init)操作在空的项目根目录打开 Cursor Agent 模式 (CtrlI)输入/init 我需要一个简单的待办事项TodoAPI服务用于学习目的。希望后端API清晰有完整的文档和测试部署简单。AI 行动与输出AI 理解需求生成2-3个方案。例如方案A全栈JavaScriptNode.js Express MongoDB Swagger UI。优点前后端语言统一生态丰富快速原型。缺点MongoDB在复杂事务上稍弱。方案BPython高效后端Python FastAPI SQLite Pydantic。优点开发体验极佳自动交互式API文档依赖注入清晰。缺点对于纯前端开发者Python环境需要适应。方案C企业级风格Java Spring Boot H2 OpenAPI。优点结构严谨适合学习企业级开发模式。缺点稍显笨重启动慢。我们选择方案B因为 FastAPI 的自动文档和 Python 的简洁性很适合这个 demo。AI 生成文件.keel/knowledge/tech_stack.md详细说明了使用 Python 3.9 FastAPI Pydantic SQLite 测试用 Pytest。.keel/knowledge/design_system.md由于是纯后端API这里主要定义了 API 响应格式标准如{code: 200, data: {}, msg: success}和错误码规范。4.2 阶段1功能规划 (/plan)操作输入/plan 实现一个Todo API包含待办事项的增删改查CRUD功能。每个待办事项有标题、描述、完成状态、创建时间字段。需要JWT令牌进行用户认证用户模块可简化并且每个用户只能操作自己的待办事项。AI 行动与输出读取tech_stack.md确认使用 FastAPI 和 SQLite。读取templates/naming_template.md。生成核心文档specs/TR_DECISION.md背景构建一个用于演示的、带认证的 Todo REST API。核心需求用户注册/登录JWT、Todo的CRUD、数据隔离。非功能需求API响应时间 200ms代码覆盖率 80%。风险JWT令牌的安全存储与刷新机制。specs/TR_IMPL.mdAPI 设计POST /auth/registerPOST /auth/loginGET /todosPOST /todosGET /todos/{id}PUT /todos/{id}DELETE /todos/{id}数据模型User表id,username,hashed_passwordTodo表id,title,description,completed,created_at,user_id(外键)依赖python-jose用于JWTpasslib用于密码哈希。.keel/memory/naming_convention.md路由kebab-case(如/auth/login)函数/变量snake_case(如get_current_user)类PascalCase(如TodoService)常量UPPER_SNAKE_CASE(如ACCESS_TOKEN_EXPIRE_MINUTES)4.3 阶段2测试先行 (/test)操作输入/test 基于TR_IMPL.md为认证和Todo的CRUD API生成完整的单元测试和集成测试。AI 行动与输出读取templates/test_template.md。在tests/目录下生成tests/test_auth.py包含测试test_register_user,test_login_for_access_token,test_login_with_wrong_password。tests/test_todos.py包含测试test_create_todo,test_read_todos,test_update_todo,test_delete_todo 以及test_cannot_access_others_todo测试数据隔离。关键点此时运行pytest所有测试都会失败因为我们还没写任何实现代码。这正是我们想要的“Red”状态。4.4 阶段3编码实现 (/forge)操作输入/forge 实现TR_IMPL.md中定义的认证和Todo CRUD API。AI 行动与输出依赖检查AI 发现requirements.txt或pyproject.toml里没有python-jose和passlib会提示“检测到需要python-jose[cryptography]和passlib[bcrypt]库是否现在安装” 确认后它会建议你运行pip install命令。遵循规范创建文件app/main.py,app/models.py,app/schemas.py,app/crud.py,app/routers/auth.py,app/routers/todos.py。所有命名严格遵循naming_convention.md。安全编码在编写密码哈希逻辑时自动引用security.md使用passlib的CryptContext进行 bcrypt 哈希。在生成 JWT 时自动从环境变量读取密钥并设置过期时间。实现功能编写出完整的、结构清晰的 FastAPI 应用代码。此时代码逻辑旨在通过之前生成的测试。4.5 阶段4验收与仲裁 (/verify与/fix)操作输入/verifyAI 行动与输出运行pytest。假设测试通过了大部分但test_cannot_access_others_todo失败了。AI 分析后生成仲裁报告验证失败 - 仲裁分析失败测试test_cannot_access_others_todo错误信息AssertionError: 预期状态码403实际返回200。可能原因1代码Bug/todos/{id}的PUT和DELETE端点中未正确校验当前登录用户user_id与待办事项所属user_id是否一致导致用户可能修改他人的待办事项。可能原因2测试Bug测试用例中构造的“他人待办事项”ID有误或用户认证令牌token未正确隔离。建议请检查app/routers/todos.py中更新和删除操作的权限校验逻辑。用户决策我们检查代码发现确实在update_todo函数里只检查了 Todo 是否存在没检查所属用户。这是一个代码Bug。操作输入/fix 修复Todo更新和删除接口的权限校验逻辑确保用户只能操作自己的待办事项。AI 修改代码添加权限校验。再次运行/verify所有测试通过流程结束。5. 高级定制与疑难排解当你熟练使用基础流程后可以通过定制化来让 Keel Kit 更贴合你的特定项目或团队习惯。5.1 深度定制角色行为打开.keel/roles/builder.md你可能会看到类似内容你是一名注重性能和可读性的高级后端工程师。你写的代码必须遵循以下原则 1. 函数长度不超过30行单一职责。 2. 数据库查询必须考虑N1问题优先使用JOIN或批量查询。 3. 所有对外API必须进行输入验证。 ...你可以修改这些描述。例如加上“你非常重视日志在每个关键业务步骤和异常处都必须记录结构化的日志使用JSON格式包含request_id”。这样AI 在/forge时生成的代码就会自动包含详细的日志记录。5.2 扩展安全基线与检查清单security.md是你的安全护城河。除了预设规则你应该根据项目类型添加Web通用所有用户输入在进入数据库前必须进行转义或使用参数化查询防止SQL注入。API安全敏感API如删除、支付必须实现幂等性令牌或二次确认。配置安全密码、密钥等敏感信息严禁硬编码必须从环境变量或保密管理服务读取。依赖安全在/forge阶段应提示用户使用pip-audit或npm audit检查依赖漏洞。你可以要求 AI 在/verify阶段不仅跑测试还自动运行一个简单的安全脚本检查代码中是否存在eval()、硬编码密码等模式。5.3 常见问题与解决方案Q1/init生成的方案我不满意或者我想中途换技术栈怎么办A最佳实践是重新运行/init。在指令中详细说明你对当前方案的不满和新的期望。例如/init 之前的FastAPI方案不错但我现在需要更强的类型检查和并发性能请提供基于Go (Gin) 和 PostgreSQL 的方案并对比与之前方案的差异。AI 会生成新方案并覆盖tech_stack.md。之后你需要从/plan开始重新规划功能因为底层技术变了。Q2AI 在/forge时生成的代码质量不高有低级错误怎么办A这通常是因为约束不够具体。首先检查你的TR_IMPL.md是否足够详细模糊的需求会得到模糊的代码。其次强化roles/builder.md中的约束并丰富templates/下的模板。最后利用好仲裁机制。当/verify失败时仔细阅读仲裁报告它不仅能指出问题其分析过程本身也是在教育 AI 你的质量标准。经过几次“生成-验证-仲裁-修复”的循环后AI 对你项目上下文的理解会越来越深代码质量会显著提升。Q3Keel Kit 会不会让开发过程变慢A对于第一个功能确实会比直接让 AI 写代码慢因为它增加了规划、设计和测试先行的步骤。但这是一种投资。从第二个功能开始优势就会显现因为技术栈、设计规范、命名约定、安全基线都已确定AI 在后续的/plan和/forge中决策速度更快生成的代码一致性极高几乎不需要重构。更重要的是它极大减少了中后期因架构混乱、代码腐化而导致的、代价高昂的返工和调试时间。对于任何计划长期维护的项目这套流程从整体上看是加速的。Q4如何与现有项目集成AKeel Kit 是渐进式采用的。你不需要一次性重写整个项目。可以将 Keel Kit 的配置文件放入现有项目根目录。运行/init根据现有项目情况手动或引导 AI 完善tech_stack.md和design_system.md。针对下一个要开发的新模块完整地走一遍 Keel 流程 (/plan-/test-/forge-/verify)。对于旧模块的重构可以将其当作一个“新需求”用 Keel 流程来驱动重构保证重构后的代码符合新的规范。这套工具的本质是将你个人的或团队的开发经验、最佳实践沉淀为机器可读、可执行的规则。你用得越多定制得越深它就越像你的一个高度自律、不知疲倦的资深工程搭档守护着你项目的代码质量与架构健康。