1. 项目概述为你的AI编程伙伴打造专属工具箱如果你和我一样日常开发已经离不开Cursor或者Claude Code这类AI驱动的IDE那你肯定也遇到过类似的困扰每次开启一个新项目或者切换到一个新的技术栈时都需要花不少时间重新“调教”你的AI助手。你得一遍遍地告诉它“我们这里用FastAPIORM用SQLAlchemy 2.0记得用异步模式”“React组件要用TypeScript写状态管理用Zustand样式用Tailwind CSS”。这个过程不仅繁琐而且容易遗漏关键细节导致生成的代码风格不一甚至引入不符合项目规范的错误。jaansokk/cursor_tools这个项目就是为了解决这个痛点而生的。它本质上是一个高度结构化、可复用的“AI助手配置库”。你可以把它理解为你为Cursor和Claude Code这两位“编程实习生”准备的、分门别类的《工作手册》和《技能工具箱》。这个工具箱里装的不只是冰冷的配置更是一套经过实践验证的工作流规范、领域专精技能和自动化操作指令。无论是全栈工程师、前端开发者还是Python后端都能从中找到适合自己的配置快速将AI助手的能力对齐到你的项目技术栈和团队规范上从而将重复性的沟通成本降到最低把精力真正集中在创造性的逻辑设计和架构决策上。2. 核心设计理念与目录结构解析这个项目的设计非常清晰其核心思想是“关注点分离”和“配置即代码”。它将AI助手所需的不同类型的指导文件按照功能清晰地归类到不同的目录中使得管理和维护变得异常简单。理解这个结构是高效使用它的第一步。2.1 双引擎支持.cursor与.claude目录项目同时支持Cursor和Claude Code两款主流AI IDE这非常务实。虽然两者底层都是基于类似的LLM大语言模型但它们在功能特性和配置方式上存在差异。项目通过创建.cursor和.claude两个平行的根目录来适配这种差异避免了配置的混淆。.cursor/ 专门针对Cursor IDE的配置。Cursor的“技能”Skills和“规则”Rules系统是其特色功能允许更细粒度的行为控制。.claude/ 专门针对Claude Code的配置。Claude Code更侧重于通过一个中心化的CLAUDE.md文件来定义工作流并通过agents/目录来组织不同角色的AI代理。这种分离确保了配置的精准性和兼容性你不需要为了适配另一个IDE而修改现有配置。2.2 四大核心模块详解无论是哪个IDE的目录其下的子模块都围绕着四个核心概念展开它们共同构成了AI助手的“行为准则”。2.2.1 Skills技能赋予AI领域专精知识技能目录是项目的精髓所在。它不再是泛泛地告诉AI“请写Python代码”而是给它装备了针对特定技术栈的“专家经验包”。ui-design/(Web UI设计): 这个技能包让AI深刻理解如何用Tailwind CSS构建高质量、可维护的Web界面。它不仅仅包含基础的类名使用更内化了如“避免过早抽象”、“遵循设计系统模板”、“进行工艺检查craft checks”等高级最佳实践。当AI处理前端UI任务时它会自动调用这套知识产出结构清晰、样式一致且符合现代CSS架构的代码。react-dev/(React开发): 针对React 18生态。它明确了函数式组件、HooksuseState, useEffect, useContext等、TypeScript类型定义、与Tailwind的集成方式以及测试规范。这能确保AI生成的React代码是现代的、类型安全的并且符合团队约定的状态管理逻辑即使没有明确指定技能包里的默认倾向也会引导AI。python-dev/(Python开发): 聚焦于现代Python后端技术栈特别是FastAPI框架。它规定了SQLAlchemy 2.0的异步用法、Pydantic v2用于数据验证、Alembic进行数据库迁移以及pytest作为测试框架。这能极大提升后端API代码的规范性、性能和可测试性。实操心得技能文件的内容组织非常关键。一个好的技能描述应该像一份给新人的“快速上手指南”包含1)技术栈版本2)核心模式与约定如API响应格式、错误处理中间件3)要避免的反模式4)推荐的工具库和配置。你可以基于项目提供的模板为你自己的技术栈如Vue3 Pinia、NestJS、Go Fiber等创建专属技能包。2.2.2 Agents代理定义AI的协作角色代理文件定义了AI在特定任务中扮演的“角色”或“工作岗位”。这超越了基础编码进入了工作流协作层面。engineer.md(全栈工程师): 这是你的主力编码伙伴。它被设定为能够理解完整需求、进行技术选型、编写从数据库到前端组件的全链路代码并具备基本的架构思考能力。verifier.md(验证者): 这是一个“挑剔的同事”角色。它的任务是进行代码审查Code Review、测试验证和逻辑校验。当你完成一个功能后可以让“验证者”代理来检查代码它会专注于寻找潜在bug、性能问题、安全漏洞和规范违反而不是去写新代码。researcher.md(研究员): 当面临新技术选型、方案调研或复杂问题排查时这个代理被训练成善于搜索、分析、归纳信息并提供评估建议的专家。在Claude Code中你可以通过agent语法在对话中直接召唤特定的代理。例如写完一段代码后输入“verifier 请检查这段代码是否有潜在的内存泄漏风险”。2.2.3 Rules规则约束AI的微观行为规则是Cursor IDE特有的强大功能它以.mdc文件形式存在用于在非常具体的场景下约束AI的行为防止其“想当然”。ask-first.mdc(先询问再假设): 强制AI在面对新任务或模糊需求时必须先向你提问以澄清细节而不是基于自己的假设直接开始执行。这能有效避免“跑偏”。include-specs.mdc(引用需求文档): 要求AI在执行任何任务前必须参考项目中的spec-index.md或类似的需求文档确保实现与需求对齐。git-mv-rename.mdc(使用git mv重命名): 这是一个经典的、人类开发者都容易忽略的细节。此规则强制AI在重命名文件时必须使用git mv命令而不是普通的mv后手动git add/rm。这能保持Git历史记录的清晰和准确。update-specs.mdc(更新需求文档): 要求AI在完成代码实现后如果发现需求文档specs有需要更新的地方如接口变更、边界条件补充必须主动提出或直接更新文档保持文档与代码同步。注意事项规则虽好但不宜过多过细。建议只添加那些能切实防止高频、高成本错误的规则。过于琐碎的规则可能会让AI显得“畏手畏脚”影响对话流畅度。通常ask-first和git-mv-rename是收益最高的两条全局规则。2.2.4 Commands命令与全局指南commands/: 存放可复用的对话指令或快捷命令。例如commit-msg.md可能定义了一套生成符合Conventional Commits规范的提交信息的指令模板。CLAUDE.md(仅.claude目录): 这是Claude Code项目的“宪法”文件。它通常包含了项目的全局工作流说明、技术栈概述、代码风格指南、分支策略、部署流程等。任何新加入项目的AI代理或开发者都应首先阅读此文件以了解项目全貌。3. 部署与集成从项目到全局的灵活使用项目提供了两种部署方式适应不同的使用场景单项目集成和全局同步。3.1 方式一单项目集成推荐用于团队项目这是最直接的方式将所需的工具配置复制到特定项目的版本控制目录中。操作步骤克隆或下载jaansokk/cursor_tools仓库。进入你的项目根目录。将需要的技能、代理或规则复制到项目内的.cursor/或.claude/目录下。# 示例为当前项目添加Cursor的UI设计技能和“先询问”规则 cp -r /path/to/cursor_tools/.cursor/skills/ui-design ./.cursor/skills/ cp -r /path/to/cursor_tools/.cursor/rules/ask-first.mdc ./.cursor/rules/重启你的Cursor或Claude Code IDE以便其重新索引并加载新的配置文件。优势配置即代码工具的配置随项目代码一起被Git管理任何克隆该项目的人都能获得完全一致的AI助手体验极大保证了团队协作的一致性。项目隔离不同项目可以使用完全不同的技能组合互不干扰。例如一个FastAPI后端项目只启用python-dev技能而一个Next.js前端项目则启用react-dev和ui-design技能。3.2 方式二全局同步适合个人开发者如果你希望在所有个人项目中共享同一套高质量的AI配置可以使用项目提供的便捷同步脚本。操作步骤确保脚本有可执行权限chmod x scripts/*.sh。运行同步脚本。你可以选择同步全部或按需同步部分模块。# 同步所有Cursor工具到全局目录 ~/.cursor ./scripts/sync_cursor.sh # 仅同步Cursor的agents到全局目录 ./scripts/sync_cursor.sh --agents # 同步所有Claude Code工具到全局目录 ~/.claude ./scripts/sync_claude.sh同步后无需在每个项目中单独配置Cursor/Claude Code会自动读取用户主目录下的全局配置。优势一劳永逸一次配置所有项目受益。集中管理更新和维护只需在全局目录中进行一次。避坑指南全局配置和项目配置可能存在冲突。通常IDE会优先采用项目级配置。但如果你在某个项目中需要覆盖某个全局技能只需在项目内创建同名的技能文件即可。建议将最通用、最基础的个人偏好如代码格式规则、通用的提问规则放在全局将项目特定的技术栈技能放在项目内。4. 实战演练以构建一个FastAPI微服务为例让我们通过一个完整的场景看看这套工具如何提升开发效率。假设我们要创建一个简单的用户管理API。4.1 初始化项目与配置创建项目并初始化环境mkdir user-service cd user-service python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows pip install fastapi sqlalchemy pydantic alembic集成cursor_tools# 创建项目本地配置目录 mkdir -p .cursor # 复制Python开发技能和必要的规则 cp -r /path/to/cursor_tools/.cursor/skills/python-dev .cursor/skills/ cp /path/to/cursor_tools/.cursor/rules/ask-first.mdc .cursor/rules/ cp /path/to/cursor_tools/.cursor/rules/update-specs.mdc .cursor/rules/创建需求文档在项目根目录创建spec-index.md这是include-specs.mdc规则所要求的。# 用户管理微服务需求规格 ## 概述 提供基本的用户CRUD API。 ## 技术栈 * FastAPI * SQLAlchemy 2.0 (异步) * Pydantic v2 * SQLite (开发环境) ## API 端点 1. POST /users/ - 创建用户 2. GET /users/{user_id} - 获取用户详情 3. GET /users/ - 获取用户列表支持分页 4. PUT /users/{user_id} - 更新用户 5. DELETE /users/{user_id} - 删除用户 ## 用户模型字段 * id: int (主键自增) * username: str (唯一非空) * email: str (唯一非空) * full_name: str (可选) * is_active: bool (默认True) * created_at: datetime (自动生成)重启Cursor让它索引新文件。4.2 与AI助手的高效协作现在打开Cursor在Chat界面中AI助手已经加载了python-dev技能和ask-first规则。你的提示词“我们需要实现用户管理API。请先阅读spec-index.md了解需求。”AI的响应受规则影响“好的我已经阅读了spec-index.md。我看到需要实现一个基于FastAPI和SQLAlchemy 2.0异步模式的用户CRUD API使用SQLite数据库。在开始之前我想确认几个细节1) 分页参数page和size的默认值分别是多少2) 更新用户时是允许部分更新PATCH语义还是必须全量更新PUT语义3) 删除用户是软删除标记is_active为False还是硬删除”你的回答“1) 默认 page1, size20。2) 允许部分更新使用PATCH语义但端点路径按需求文档保持为PUT。3) 硬删除。”接下来AI会基于python-dev技能的知识生成高度符合规范的代码。例如它会自动使用AsyncSession正确导入select和update使用Pydantic v2的model_validator进行复杂验证并为每个端点生成初步的pytest测试用例骨架。它甚至可能会提醒你“根据Alembic最佳实践我现在可以为你生成初始的数据库迁移脚本吗”在整个过程中update-specs.mdc规则可能会促使AI在实现后发现需求文档未明确“邮箱格式验证”从而向你提问“需求文档中没有规定邮箱格式验证规则。我建议在Pydantic模型中使用EmailStr类型并已实现。是否需要更新spec-index.md以反映此约束”4.3 利用代理进行代码审查功能实现后你可以创建一个简单的verifier.mdc规则或直接使用Agent功能让AI切换角色进行审查。你的提示词“verifier请审查我刚实现的app/crud/users.py文件重点检查异步上下文管理、SQL注入防护和异常处理是否恰当。”AI作为验证者的响应“审查完成。主要发现1)良好实践正确使用了async with session.begin():管理事务。2)潜在问题在get_user函数中直接使用了字符串拼接构建查询条件filter(User.username username)是安全的因为这是SQLAlchemy表达式但需要注意如果未来有动态过滤条件应避免使用字符串格式化。3)改进建议建议为UserNotFound异常添加更具体的HTTP状态码如404映射在FastAPI的异常处理器中统一处理。总体代码质量良好符合异步SQLAlchemy规范。”5. 高级技巧与自定义扩展5.1 创建你自己的专属技能项目提供的技能是优秀的起点但每个团队都有自己的“独门秘籍”。创建自定义技能非常简单。在.cursor/skills/或.claude/skills/下创建一个新目录例如my-company-backend/。在该目录下创建skill.mdc文件。内容结构可以参考现有技能但核心是清晰、具体。# 公司后端开发规范 (v1.0) ## 核心框架与版本 * 使用 **FastAPI 0.104** * 数据库操作统一使用 **SQLAlchemy 2.0** 的异步模式。 * 数据验证与序列化使用 **Pydantic v2**。 ## 项目结构约定src/ ├── api/ # 路由层 ├── core/ # 配置、安全、依赖项 ├── crud/ # 数据库操作层不包含业务逻辑 ├── models/ # SQLAlchemy 数据模型 ├── schemas/ # Pydantic 模型请求/响应 └── services/ # 核心业务逻辑层## 关键编码规范 1. **依赖注入**所有数据库Session必须通过FastAPI的 Depends 注入禁止在函数内直接创建。 2. **错误处理**业务异常统一继承自 app.core.exceptions.CustomHTTPException并在 app/core/handlers.py 中注册全局处理器。 3. **响应封装**所有成功API响应必须使用 app.schemas.ResponseModel[T] 进行包装。统一格式为 {code: 200, msg: success, data: T}。 4. **日志记录**使用 structlog 进行结构化日志记录关键业务步骤和异常必须记录。 ## 必须避免的反模式 * ❌ 在路由函数中编写复杂的SQL或业务逻辑。 * ❌ 直接返回SQLAlchemy模型实例必须通过Pydantic Schema转换。 * ❌ 使用同步的 session.query()必须使用异步的 session.execute(select(...))。重启IDE该技能即可被识别和应用。5.2 组合使用技能与规则技能和规则可以组合使用产生“112”的效果。例如python-dev技能 ask-first.mdc规则AI在编写Python代码时对于模糊需求会主动提问确保生成的代码精准。ui-design技能 include-specs.mdc规则AI在设计UI前会强制要求查阅设计稿或需求文档保证产出与设计一致。全局git-mv-rename.mdc规则这是一个“安全网”规则无论AI在执行什么任务重构、修复bug、开发新功能只要涉及文件重命名都会采用最安全的方式。你可以通过项目内的scripts/目录下的同步脚本灵活地将不同的规则和技能组合同步到全局或项目目录中。5.3 与版本控制系统Git的协同强烈建议将项目本地的.cursor/或.claude/目录纳入版本控制如Git。这带来了几个巨大好处团队一致性确保所有团队成员使用同一套AI辅助标准减少沟通成本。配置可追溯技能的迭代和规则的增减都有历史记录方便回顾和审计。分支特定配置你甚至可以为不同的Git分支配置不同的规则。例如在develop分支启用严格的verifier代理进行代码审查而在feature/*分支则侧重于engineer代理进行快速开发。6. 常见问题与故障排查在实际使用中你可能会遇到一些问题。以下是常见情况的排查指南。问题现象可能原因解决方案Cursor/Claude Code没有识别新添加的技能或规则。1. IDE未重启索引。2. 配置文件放错了位置如应放在.cursor/rules/却放在了.cursor/根目录。3. 文件格式或扩展名错误Cursor规则需.mdc。1. 完全重启IDE。2. 检查目录结构是否与项目文档完全一致。3. 确保技能目录内有skill.mdc规则文件以.mdc结尾。AI的行为没有按照规则执行例如仍然直接重命名文件而不使用git mv。1. 规则文件语法有误。2. 存在多个同名规则冲突全局 vs 项目。3. 该规则在某些上下文中被IDE或AI策略覆盖。1. 检查.mdc文件内容确保是纯文本指令无格式错误。2. 检查~/.cursor/rules/和./.cursor/rules/下是否有同名文件项目级优先。3. 规则并非100%强制AI可能会在极高置信度下执行简单操作。可尝试在Chat中明确提醒“请遵守git-mv-rename规则”。技能效果不明显AI生成的代码仍不符合预期。1. 技能描述不够具体或存在歧义。2. 当前对话上下文过长早期技能信息被“遗忘”。3. 你的提示词过于宽泛未触发技能的具体应用。1. 细化技能描述提供具体的代码示例和反例。2. 开启新的Chat会话或使用/skill_name命令显式调用技能。3. 在提示词中明确引用技能如“请运用python-dev技能创建一个异步的FastAPI端点来处理...”。同步脚本执行失败Permission denied。脚本没有执行权限或目标目录如~/.cursor权限不足。运行chmod x scripts/*.sh赋予脚本执行权限。对于全局目录确保你有写入权限。在Claude Code中agent语法不生效。1. 代理文件未正确放置在.claude/agents/目录下。2. 代理文件格式不符合Claude Code要求。1. 确认文件路径正确。2. 参考项目提供的agents/示例文件确保文件以清晰的描述开头定义了代理的角色、目标和约束。个人经验分享这套工具的价值在于“沉淀”和“复用”。最开始你可能只是零星地写几条规则。但随着项目推进你会不断发现那些重复向AI解释的事情——比如“我们这里用Zod而不是joi做验证”、“我们的组件库是shadcn/ui”——把这些都逐步沉淀成技能或规则。几个月后你就拥有了一个高度定制化、能极大提升你和团队生产力的AI助手配置库。它不再是一个外部工具而是你软件开发工作流中一个无缝集成、不可或缺的智能环节。