1. 项目概述为AI编程助手制定规则如果你和我一样在日常开发中重度依赖像Cursor和Windsurf这类集成了AI编程助手的IDE那你一定有过类似的体验AI助手有时能给出惊艳的代码片段但更多时候它的回答过于宽泛不符合你的编码习惯或者干脆忽略了项目的特定架构和约束。每次都需要在聊天框里重复输入“请遵循项目中的TypeScript规范”、“优先使用函数组件而非类组件”、“不要使用any类型”这不仅低效也让AI助手的潜力大打折扣。这正是rules-for-ai这个项目要解决的核心痛点。它不是一个简单的配置文件模板而是一套完整的、可交互的规则引擎专门用于“驯化”你IDE中的AI编程助手。通过为Cursor和Windsurf提供结构化的、高质量的规则定义它能将你的个人偏好、团队规范、项目架构等上下文信息系统地注入到AI的“记忆”中。简单来说它让AI助手从一个“通才”变成了深谙你项目细节和编码风格的“专属协作者”。这个项目适合所有使用Cursor或Windsurf的开发者无论你是独立开发者想统一自己的代码风格还是团队负责人希望将编码规范无缝集成到开发流程中。它通过预置的高质量通用规则和一系列任务导向的快捷命令极大地提升了AI辅助编程的精准度和效率。2. 核心设计思路与工作原理拆解2.1 规则文件的双层架构全局与局部的智慧rules-for-ai项目的设计核心在于其清晰的双层规则架构这模仿了软件开发中配置管理的常见模式全局默认配置与项目特定覆盖。全局规则Global Rules是你所有项目的“宪法”。它定义了那些跨项目通用、你个人或团队始终坚持的编码原则。例如代码风格缩进用2个空格还是4个空格字符串用单引号还是双引号通用最佳实践禁止使用var优先使用const和letReact组件必须使用函数式组件和Hooks。安全与性能红线禁止使用eval()避免在循环内进行DOM操作。AI交互偏好“请先解释你的思路再给出代码”、“生成的代码必须附带简要注释”。这些规则被保存在global_rules.mdWindsurf或global_rules.mdcCursor文件中。一旦设置它们会在你打开的任何项目中作为AI助手的背景知识生效为你提供一致性的基础保障。项目规则Project Rules则是针对特定项目的“地方法规”。它位于项目根目录文件名为.windsurfrulesWindsurf或project_rules.mdcCursor。这一层规则用于定义项目独有的上下文技术栈与架构“本项目使用Next.js 14 App Router状态管理采用ZustandAPI调用统一使用axios实例。”目录结构与约定“/components存放通用组件/lib存放工具函数/types存放TypeScript类型定义。”项目特定约束“所有API响应必须通过src/lib/api-response.ts中的格式化函数处理”、“与后端交互的数据模型定义在src/models/目录下”。业务逻辑提示“用户权限分为‘admin’, ‘editor’, ‘viewer’三级相关逻辑请参考src/hooks/use-permissions.ts。”当AI助手在处理一个具体项目时它会优先遵循项目规则同时继承全局规则中不冲突的部分。这种设计确保了规则的灵活性和针对性既保持了个人习惯的统一又尊重了每个项目的特殊性。2.2 交互式设置让规则“活”起来与手动编写一个静态的Markdown规则文件不同rules-for-ai最大的亮点在于其交互式设置流程。它通过预设的/setup命令引导你与AI助手进行一场结构化的对话从而动态生成最适合你的规则文件。这个过程远比复制粘贴模板更有价值。AI助手会向你提出一系列问题例如“你主要使用哪些编程语言和框架” “你的团队有特定的代码风格指南吗如Airbnb, Google” “你希望我在代码审查时重点关注哪些方面性能、安全性、可读性” “对于这个特定项目有哪些重要的目录或文件我需要特别关注”你的回答会被AI理解和消化并转化为精确、可执行的规则条款。这种方式有两大优势降低使用门槛你不需要成为规则语法专家只需用自然语言描述你的需求。规则更贴合实际通过问答形式挖掘出的需求往往比你自己罗列的更全面、更贴近真实工作场景。2.3 快捷命令生态从规则到高效工作流定义了规则只是第一步如何让这些规则在开发流程中高效发挥作用才是关键。rules-for-ai项目预置了一系列以/开头的快捷命令这些命令本质上是基于你已设定规则的、高度定制化的“宏”或“工作流模板”。例如当你输入/review时AI助手并非随机开始审查代码。它会主动调用规则文件中关于“代码审查”的条款比如“审查时需检查输入验证、错误处理是否完备”、“对照ESLint规则检查代码风格”、“评估函数是否过于复杂圈复杂度”。这使得代码审查变得系统化、标准化。再比如/arch命令AI助手会根据规则中定义的项目技术栈如“微服务架构服务间通过gRPC通信”为你提供符合该架构范式的设计建议而不是泛泛而谈。这些快捷命令将零散的AI能力整合成了针对特定开发任务调试、重构、写测试、写文档的标准化解决方案极大地提升了开发效率。3. 核心配置解析与实操要点3.1 规则文件语法与结构精讲虽然/setup交互流程能自动生成文件但理解规则文件的底层结构能帮助你进行更精细的手动调整。Windsurf和Cursor的规则文件都是Markdown格式但通过特定的标题和列表来结构化信息。一个高效的规则文件通常包含以下部分# 项目编码规范 ## 技术栈与架构 - **前端框架**: 使用 React 18并采用函数组件与 Hooks。 - **状态管理**: 使用 Redux Toolkitslice 文件应放置在 src/store/slices/ 下。 - **样式方案**: 使用 Tailwind CSS避免编写行内样式。 - **API 通信**: 使用 axios且所有请求必须通过定义在 src/api/client.ts 中的实例发出。 ## 代码风格 - **缩进**: 使用 2 个空格。 - **分号**: 语句末尾不加分号。 - **命名**: - 组件PascalCase (如 UserProfile) - 函数/变量camelCase (如 fetchUserData) - 常量UPPER_SNAKE_CASE (如 API_ENDPOINT) - **TypeScript**: 严禁使用 any 类型必须为函数参数和返回值定义明确类型。 ## AI 交互指令 - 在生成代码前请先简要说明实现思路。 - 生成的代码块必须附带解释其关键部分的注释。 - 当被要求重构时优先考虑可读性和可维护性而非过度优化。 - 如果对需求有疑问请主动提问确认不要猜测。 ## 项目特定上下文 - 用户认证逻辑已封装在 src/auth/ 目录下请直接调用相关函数。 - 所有页面组件都应放置在 src/pages/ 目录并使用 getServerSideProps 进行数据获取。 - 工具函数应放在 src/utils/ 目录并优先使用已存在的函数。关键要点使用清晰的标题##来划分规则类别这有助于AI快速定位相关规则。列表项-用于描述具体的规则条目语言要肯定、明确避免歧义。强调关键路径和名词使用反引号包裹文件路径、函数名、变量名使用加粗强调核心概念这能帮助AI更准确地理解上下文。规则优先级通常文件靠后的规则不会覆盖前面的但更具体、更详细的描述会被AI赋予更高权重。如果出现矛盾虽然应避免项目规则.windsurfrules/project_rules.mdc中的条目会覆盖全局规则。3.2 全局规则与项目规则的配置策略如何划分全局和项目规则是发挥其威力的关键。根据我的经验可以遵循以下策略全局规则 (global_rules.md/global_rules.mdc) 应包含个人/团队基础编码风格缩进、引号、命名约定等。通用安全与质量红线禁用危险函数、要求错误处理、复杂度警告阈值等。AI交互元规则你希望AI以何种方式与你合作如先思考后输出、主动提问。跨技术栈通用实践例如“写函数时优先考虑纯函数”、“注释应解释‘为什么’而不是‘是什么’”。项目规则 (.windsurfrules/project_rules.mdc) 应包含项目技术栈明细精确到库的版本和主要配置方式。项目目录架构清晰的模块划分和导入别名如/。业务领域逻辑核心的业务概念、状态流转、权限模型描述。外部依赖说明关键的三方服务API调用方式、数据库模型简述。当前工作焦点例如“当前正在重构用户模块请注意与新的UserService接口保持一致”。注意一个常见的误区是把所有规则都塞进项目规则。这会导致每个新项目都要从头配置。正确的做法是将那些你希望在所有项目中保持一致的习惯提炼到全局规则中让项目规则专注于“这个项目独一无二”的部分。3.3 快捷命令的深度定制与扩展项目预置的快捷命令/debug,/review等已经非常实用但其真正的潜力在于你可以根据项目规则对其进行“情境化”增强。例如在你的project_rules.mdc中你可以为/test命令添加上下文## 测试策略 - 单元测试使用 Jest 和 React Testing Library。 - 组件测试应聚焦于用户交互而非实现细节。 - 所有 API 相关的函数必须编写模拟mock测试。 - 测试文件应与源文件并列命名为 [filename].test.tsx。这样当你在这个项目中运行/test命令并指向一个React组件时AI助手不仅会建议写测试还会自动套用Jest RTL的语法并提醒你关注交互和模拟API。你甚至可以创建自己的“快捷命令提示区”。在规则文件中加入## 自定义快捷命令提示 - 当我说“/部署检查”时请帮我检查当前代码是否符合部署清单清单见deploy-checklist.md的要求。 - 当我说“/生成CRUD”时请基于src/models/下的TypeScript接口生成对应的API路由、服务层函数和基础UI组件。虽然AI不会自动识别这些自定义“命令”但你可以通过复制这段描述到聊天框来快速激活一个复杂的工作流。这相当于为你常用的、复杂的提示词prompt建立了快速入口。4. 完整工作流实操与核心环节实现4.1 初始化安装与首次交互式设置让我们从头开始为一个新的Next.js项目配置rules-for-ai。步骤1克隆规则库在你的开发环境任意位置克隆项目仓库。这通常只需要做一次。git clone https://github.com/hashiiiii/rules-for-ai.git这个仓库本地副本是你的“规则工具箱”里面包含了预置的全局规则模板和快捷命令定义。步骤2创建全局规则文件进入你克隆的rules-for-ai目录找到global_rules.mdcCursor或global_rules.mdWindsurf的模板文件。将其复制到AI助手的全局配置目录。Cursor: 通常你可以直接在与AI的聊天框中输入“打开全局规则”Cursor会引导你创建或打开该文件。你也可以手动在用户配置目录下找到它。Windsurf: 根据其文档全局规则文件有特定存放位置。将模板内容粘贴进去并进行初步编辑填入你跨项目通用的规则。例如设置你的默认语言为TypeScript偏好使用async/await等。不要追求一步到位后续可以随时调整。步骤3在新项目中启动交互式设置现在打开你的Next.js项目。在Cursor或Windsurf的AI聊天框中输入/setupAI助手会开始引导式对话。它会问一系列问题例如“项目的主要编程语言和框架是什么”你答TypeScript, Next.js 14“有特定的代码风格指南吗”你答遵循ESLint的standard规则并自行添加了X条规则“项目有什么特殊的架构或目录约定吗”你答使用App Router组件放在app/components/工具函数在lib/步骤4生成并存储项目规则问答结束后AI会根据你的回答生成一份初步的.windsurfrules或project_rules.mdc文件内容。此时你需要输入/store这个命令会指示AI将刚才对话中总结出的规则正式写入到当前项目根目录的对应规则文件中。至此项目专属的AI助手规则就配置完成了。4.2 日常开发中的规则调用与迭代规则文件不是“一劳永逸”的设置而应该随着项目演进而迭代。场景添加一个新功能模块当你开始开发一个“消息通知”模块时发现AI助手对项目内的消息队列如Bull使用方式不熟悉。此时你可以直接打开project_rules.mdc文件在“项目特定上下文”部分手动添加一条- **消息队列**: 使用 Bull 处理后台任务。队列定义在 src/queues/ 目录下处理器processor应返回明确的结果或抛出错误。参考 src/queues/email.queue.ts 的写法。或者使用/adjust命令。输入/adjust后告诉AI“请更新项目规则加入对Bull消息队列的使用规范说明参考现有的email.queue.ts文件。” AI会帮你生成更规范的描述并更新规则文件。场景利用规则进行高效协作当一位新成员加入项目时你无需花费大量时间口述项目规范。只需让他/她在本地配置好AI助手后打开项目。AI助手在读取项目规则后其行为会自动对齐到项目规范。当新成员问“这个API该怎么调用”时AI的回答会基于规则中的“API通信使用axios实例…”来生成正确代码极大降低了上手成本。场景执行标准化任务你需要审查一个刚写完的组件。只需选中相关代码在聊天框中输入/review。AI助手会立刻基于规则中定义的审查要点如“检查PropTypes/TypeScript接口定义”、“确认错误边界处理”、“评估组件复杂度”进行扫描并给出结构化反馈而不是泛泛地说“代码看起来不错”。4.3 高级技巧规则文件的模块化与组合对于大型或复杂的项目单个规则文件可能变得冗长。虽然Windsurf和Cursor原生不支持直接导入其他规则文件但我们可以通过“模块化描述”来实现类似效果。你可以在项目规则文件中这样组织# 项目AI规则 ## 核心架构 (详见 ARCHITECTURE.md) - 整体为微前端架构主应用使用 Module Federation。 - 各子应用独立开发部署通信通过自定义事件总线。 - 更多细节请阅读 docs/ARCHITECTURE.md ## 代码风格 - ...风格规则 ## API 规范 (详见 API_CONTRACT.md) - 所有后端API遵循RESTful规范响应格式为 { code, data, message }。 - 错误码定义在 src/constants/error-codes.ts。 - 完整接口文档见 docs/API_CONTRACT.md同时在/setup或日常对话中你可以指示AI助手“请优先阅读docs/ARCHITECTURE.md和docs/API_CONTRACT.md以理解系统上下文。” 虽然AI不会自动持续读取这些文件但在当前会话中它会加载这些文件的内容作为额外上下文与规则文件相辅相成。另一种实践是为不同的开发阶段准备不同的规则“侧重点”。例如在原型开发阶段规则可以强调“快速实现允许使用临时mock数据暂不考虑性能优化”而在代码重构阶段则可以切换为“严格遵循SOLID原则优先考虑可测试性必须添加单元测试”。你可以通过注释/取消注释规则文件中的不同区块或准备多个规则文件副本进行切换。5. 常见问题排查与实战技巧实录即使有了完善的规则在实际使用中仍可能遇到问题。以下是我在实践中总结的常见情况及解决方案。5.1 AI助手“无视”或“误解”规则问题现象你明明在规则中写了“使用函数组件”但AI生成的仍然是类组件或者你定义了项目结构但AI还是引用了错误的路径。排查思路与解决检查规则文件位置与名称这是最常见的问题。确认文件是否放在项目根目录且名称完全正确.windsurfrules或project_rules.mdc注意前者以点开头。全局规则文件也要确认路径正确。检查规则语法确保使用的是Markdown语法标题清晰列表规范。避免使用过于复杂或嵌套的格式。有时一个格式错误可能导致AI解析失败。规则冲突或过于模糊如果全局规则说“用单引号”项目规则说“用双引号”AI可能会困惑。确保规则明确无冲突。同时避免“写出高质量的代码”这种模糊描述要具体如“函数行数不超过50行圈复杂度低于10”。重启IDE或AI会话规则文件通常在IDE启动或新会话开始时加载。修改规则后尝试关闭并重新打开AI聊天面板或者重启IDE以确保新规则被加载。主动提示AI在提问时可以主动提醒AI参考规则。例如“根据项目规则中关于API调用的约定请帮我生成一个获取用户列表的函数。”5.2 快捷命令执行效果不佳问题现象输入/refactor后AI给出的重构建议非常表面或者/debug无法定位到真正的问题。解决与优化提供足够上下文快捷命令不是魔法。在执行/debug前最好先选中出错的代码段或者提供错误信息。对于/refactor告诉AI你希望改进的具体方向如“提高这个函数的可测试性”或“解耦这个组件的数据获取逻辑”。强化规则中的命令定义在项目规则中为特定命令添加更详细的上下文。例如在规则中明确“当执行/debug时请按照以下步骤分析1. 复现问题现象2. 检查输入输出3. 检查相关状态和副作用4. 提出假设并验证。”组合使用命令/plan/arch/review是一个强大的组合。先让AI制定计划再设计架构最后审查实现每一步都基于已定义的规则能产生更系统化的输出。5.3 规则文件维护成本与版本控制问题规则文件需要随项目更新如何有效维护并与团队共享实战技巧将规则文件纳入版本控制一定要将.windsurfrules或project_rules.mdc提交到Git仓库中。这是团队共享AI上下文的最简单方式。任何成员拉取代码后AI助手就能立即获得最新的项目规范。在规则中引用其他文档如前所述规则文件本身应保持简洁核心。将详细的架构图、API文档、部署流程等放在docs/目录下的独立文件中并在规则文件中引用。这样规则文件只维护AI需要“时刻牢记”的核心指令。定期回顾与更新在每次迭代总结或架构调整后花几分钟更新规则文件。将其视为“项目知识库的AI可读摘要”。/adjust命令是完成这项工作的好帮手。区分个人与团队规则有些规则可能纯属个人偏好如“生成的注释用中文”。这类规则更适合放在你的全局规则中而不是项目规则里避免污染团队共享的配置。5.4 性能与响应考量问题规则文件写得非常详细、冗长会影响AI的响应速度或准确性吗经验之谈根据我的使用经验现代AI助手的上下文窗口已经非常大一个精心编写的规则文件几千字对其响应速度的影响微乎其微几乎无法感知。关键在于质量而非数量。准确性冗长且充满无关信息的规则文件确实可能稀释重要指令的权重。因此规则应简洁、明确、结构化。使用标题分层把最重要的约束放在前面和最显眼的位置。优先级AI会综合考量整个上下文当前代码、聊天历史、规则文件。规则文件是强大的背景信息但当前对话中的具体指令通常拥有最高的优先级。因此如果你发现AI偏离了规则在提问时清晰地重申关键要求往往能立刻纠正它。我个人在实践中发现一个维护良好的规则文件其带来的效率提升减少重复说明、提高代码一致性、加速上下文切换远远超过任何微小的性能开销。它更像是一个为你量身定制的、永不疲倦的编程搭档记住了所有关于“如何在这个项目中写好代码”的细节。