1. 项目概述为AI编码助手打造的生产级规则集如果你和我一样日常重度依赖 Cursor、Claude 这类 AI 编码助手来提升开发效率那你一定也遇到过类似的困扰AI 生成的代码风格五花八门有时会引入一些不符合项目约定的依赖或者在一些细节处理上“放飞自我”导致生成的代码虽然能用但离“生产就绪”还有一段距离后续还需要花不少时间手动调整和规范。这正是llm-ruleset这个项目诞生的背景。它不是一个简单的代码片段集合而是一套模块化、强观点、具备技术栈感知能力的规则文件专门设计用来“驯服”你的 AI 助手让它们生成的代码从一开始就符合你的团队规范和项目架构真正做到开箱即用保持代码库的整洁与一致。简单来说llm-ruleset就像是为你的 AI 编码助手配备了一位经验丰富的架构师或资深技术主管。在你向 AI 提问或发出指令时这些规则会作为上下文的一部分无声地引导 AI 做出更符合你预期的决策。它覆盖了从代码风格、依赖管理、安全实践到特定框架如 React、Next.js最佳实践的方方面面。对于任何希望将 AI 助手无缝、高效地集成到现有开发工作流中的团队或个人开发者而言这套规则集都是一个能显著提升产出质量和减少后期返工的核心工具。2. 核心设计理念与架构解析2.1 模块化按需组合的规则引擎llm-ruleset最核心的设计思想就是模块化。它没有试图用一个庞大、臃肿的单一文件来覆盖所有场景而是将规则按领域和技术栈拆分成一个个独立的、可复用的模块。这种设计带来了几个关键优势首先是灵活性。不同的项目技术栈迥异一个可能是 React TypeScript Tailwind CSS 的前端项目另一个可能是使用 FastAPI 的 Python 后端服务。llm-ruleset允许你像搭积木一样只引入与当前项目相关的规则模块。例如你的.cursorrules文件可能只包含general-code-style.md、typescript-strict.md和react-best-practices.md而完全不需要 Python 或 Go 相关的规则。这种按需加载的方式确保了传递给 AI 助手的上下文是最精简、最相关的避免了无关信息干扰 AI 的判断也减少了 token 的浪费。其次是可维护性。当某个特定技术的最佳实践更新时比如 React 推出了一个新的推荐模式你只需要更新对应的规则模块文件如react-best-practices.md所有引用了该模块的项目都会自动受益。这比在一个巨型文件中搜索和修改特定段落要高效、安全得多。团队内部也可以基于这些基础模块衍生出符合自身特殊约定的扩展模块实现规则的继承与定制。最后是清晰的职责分离。每个模块文件都聚焦于一个明确的主题。例如security-basics.md只关注安全编码规范如避免硬编码密钥、防范 SQL 注入和 XSS 等而testing-strategies.md则专注于测试的编写原则如测试命名、覆盖率要求、Mock 的使用规范等。这种分离使得规则本身更容易理解、审查和迭代。2.2 强观点性贯彻一致的最佳实践“强观点性”是llm-ruleset的另一个鲜明特征。它不追求面面俱到地罗列所有可能性而是明确地倡导一套经过实践检验的、特定的最佳实践。这听起来可能有些武断但实际上这对于约束 AI 的行为至关重要。AI 模型在缺乏明确指引时倾向于生成“平均的”、“常见的”解决方案但这往往不是“最优的”。例如在状态管理上一个没有观点的 AI 可能会根据训练数据等概率地建议使用 Context、Zustand、Redux 或 MobX。而一个具有强观点的llm-ruleset可以明确规定“在本项目中对于简单的组件间状态传递优先使用 React Context对于复杂的全局应用状态统一使用 Zustand并遵循以下模式……”。这样AI 生成的代码从一开始就符合团队的技术选型避免了不必要的技术栈争论和后续的迁移成本。这种观点性体现在方方面面代码风格不仅规定缩进是 2 个空格还是 4 个空格还会规定函数命名的风格是camelCase还是snake_case、组件是使用默认导出还是命名导出。依赖管理明确规定禁止使用哪些已知存在安全漏洞或维护状况不佳的第三方库推荐使用哪些经过审计的替代方案。错误处理规定是使用try-catch块、错误边界Error Boundaries还是自定义的错误类以及错误信息的记录格式。API 设计对于后端项目可以规定 RESTful 端点命名规范、响应体统一格式、分页参数标准等。通过灌输这些强观点llm-ruleset确保了 AI 助手成为团队编码规范坚定不移的执行者而非一个需要不断纠正的“新手”。2.3 技术栈感知深度定制的上下文“技术栈感知”意味着这些规则不是空中楼阁它们能深刻理解你当前项目所使用的具体技术并据此提供精准的指导。这是通过规则模块的精心设计和条件化引用来实现的。例如项目里可能同时存在nextjs-app-router.md和nextjs-pages-router.md两个模块。它们都是针对 Next.js 的但分别适用于不同的路由架构。你的项目根目录的package.json或next.config.js的某些特征可以帮助你或通过一个简单的脚本判断该引入哪一个。更细粒度的react-hooks.md模块中的规则会明确区分在普通函数组件中和在 Next.js 的 Server Component 中使用 Hook 的差异提醒 AI 在 Server Component 中避免使用useState、useEffect等客户端 Hook。这种感知能力还体现在对项目现有结构的尊重上。规则可以引导 AI“查看项目根目录下已存在的lib/utils.ts文件其中已有cn()函数用于合并 Tailwind CSS 类名。当需要处理类名时请直接导入并使用该函数不要重新实现。” 或者“本项目使用/作为别名指向src/目录所有导入语句必须使用此别名。” 这使得 AI 生成的代码能完美融入现有项目而不是创建一个孤立的、风格迥异的片段。3. 核心规则模块深度解析与实操配置3.1 通用代码风格与质量规则这是所有项目的基石通常是你需要引入的第一个模块。它不涉及任何具体框架而是奠定代码的“气质”。一个典型的general-code-style.md会包含以下硬性规定命名规范变量与函数强制使用camelCase。函数名应为动词或动词短语如fetchUserData、validateInput。布尔变量常以is、has、should开头如isLoading。类与组件强制使用PascalCase。React 组件名必须与文件名一致。常量使用UPPER_SNAKE_CASE且必须在文件顶部或独立的constants文件中定义。文件与目录使用kebab-case短横线连接。例如user-profile.tsxapi-client.ts。代码结构导入顺序明确规定导入的分组和排序。例如1. 第三方库如react,lodash2. 内部别名路径如/components/*3. 相对路径的父级目录4. 相对路径的同级或子级目录。每组内部按字母顺序排序。函数长度与复杂度建议单个函数不超过 30 行或 20 行。如果函数过长AI 应被引导将其拆分为多个更小、职责单一的函数。可以引入简单的圈复杂度概念提示 AI 避免过多的嵌套条件分支。注释哲学强调“为什么”而不是“是什么”。禁止对一目了然的代码添加冗余注释如// 增加计数器。要求对复杂的业务逻辑、非常规的解决思路、以及为了绕过某个已知问题而写的“坑位代码”添加清晰注释。实操配置示例在你的项目根目录创建或编辑.cursorrules文件内容可以这样开头!-- 引入通用代码风格规则 -- 请严格遵守以下代码规范这将作为所有代码生成的基石。 ### 命名约定 - 使用 camelCase 命名变量、函数、方法。 - 使用 PascalCase 命名类、接口、类型、React 组件。 - 使用 UPPER_SNAKE_CASE 命名常量。 - 使用 kebab-case 命名文件和文件夹。 ### 导入排序 严格按照以下分组顺序组织 import 语句 1. React / Next.js 等主要框架库 2. 其他第三方库如 lodash, axios 3. 来自 / 别名路径的绝对导入如 /lib/utils, /components/ui 4. 相对路径导入先上级目录../后同级或下级目录./ 每组内部按字母顺序A-Z排列。 **注意** 任何生成的代码在提交前都必须通过 ESLint配置为 eslint-config-airbnb-base和 Prettier 的检查。如果规则中未明确规定的细节以项目的 .eslintrc.js 和 .prettierrc 配置文件为准。3.2 TypeScript 严格模式规则对于使用 TypeScript 的项目一个强观点的规则集至关重要它能将 TypeScript 的类型优势发挥到极致避免生成any泛滥的“伪 TypeScript”代码。typescript-strict.md模块通常非常严格禁止使用any这是铁律。规则应要求 AI 在遇到无法立即确定类型的情况时优先使用unknown然后通过类型守卫type guards进行收窄或者定义明确的泛型。如果确实需要灵活性可以允许使用Recordstring, unknown这样的宽泛但仍有约束的类型。明确的类型定义要求所有函数参数、返回值、变量、状态都必须有显式的类型注解。即使 TypeScript 可以推断为了代码清晰度也鼓励显式声明。特别是公共 API 的接口如函数导出、组件 Props。接口Interface与类型别名Type Alias的选择规定统一的使用场景。一个常见的观点是使用interface定义对象形状尤其是需要扩展时如extends使用type定义联合类型、交叉类型或简单别名。例如// 使用 interface 定义可扩展的对象结构 interface User { id: string; name: string; } interface AdminUser extends User { permissions: string[]; } // 使用 type 定义联合类型或映射类型 type Status idle | loading | success | error; type PartialUser PartialUser;泛型的使用鼓励在创建可复用的工具函数、Hook 或组件时使用泛型并提供清晰的泛型参数名如T,K,V。规则应包含简单的泛型示例引导 AI 正确应用。实用类型工具要求 AI 熟悉并应用 TypeScript 内置的实用类型如PickT, K、OmitT, K、PartialT、RequiredT等以避免手动编写冗余的类型定义。配置示例补充到.cursorrules### TypeScript 严格规范 - **绝对禁止使用 any 类型。** 如果暂时不确定类型使用 unknown 并随后进行类型收窄。 - 所有函数、变量、React 组件 Props 必须显式声明类型。 - 定义对象形状优先使用 interface便于扩展定义联合类型、交叉类型使用 type。 - 积极使用泛型 (T, U) 来创建类型安全的通用函数和组件。 - 优先使用 Recordstring, unknown 而非 object。 - 使用 as 进行类型断言是最后的手段必须附上 // ts-expect-error 或详细的解释注释说明为何安全。3.3 前端框架特定规则以 React/Next.js 为例这是体现“技术栈感知”的核心。规则需要深入框架细节。React 组件设计函数组件优先强制使用函数组件和 Hooks。组件职责单一一个组件只做一件事。如果发现一个组件同时处理数据获取、业务逻辑和复杂渲染AI 应被引导将其拆分为一个负责数据获取的 Hook、一个负责逻辑处理的 Hook 或 Context以及多个负责渲染的展示组件。Hook 的使用规则useState应被用于简单的局部状态复杂的、涉及多个子状态或衍生状态的状态应被引导使用useReducer。useEffect的依赖数组必须完整且正确规则应提醒 AI 注意闭包陷阱和无限循环。性能优化提示在适当的时候引导 AI 使用React.memo包裹组件使用useMemo缓存昂贵的计算结果使用useCallback缓存函数以避免子组件不必要的重渲染。同时规则也应指出不要过度优化仅在性能瓶颈被证实后才应用这些优化。Next.js App Router 特定规则Server vs Client Components这是最重要的区分。规则必须明确默认所有组件都是 Server Component。只有当明确需要使用useState、useEffect、onClick等浏览器 API 或交互性时才在文件顶部添加use client指令。AI 应被训练去思考“这个组件真的需要在客户端运行吗”数据获取在 Server Component 中直接使用async/await调用数据获取函数如直接访问数据库或调用内部 API。禁止在 Server Component 中使用useEffect或SWR/TanStack Query来获取数据。路由与布局解释page.tsx、layout.tsx、loading.tsx、error.tsx等特殊文件约定。引导 AI 将共享的 UI 放在layout.tsx中将页面特定内容放在page.tsx中。元数据 API鼓励使用generateMetadata函数或静态/动态的metadata对象来定义页面 SEO 信息而不是在head标签中硬编码。配置示例### React/Next.js (App Router) 规范 #### 组件设计 1. 所有组件默认为 **Server Component**。仅在需要交互性、状态或浏览器 API 时在文件首行添加 use client。 2. 保持组件小巧、职责单一。如果组件超过 150 行考虑拆分。 3. 使用自定义 Hook (useXxx) 来封装可复用的状态逻辑和副作用。 #### 数据获取 - **Server Component 中** 直接使用 async/await 进行数据获取。例如const data await fetchData(); - **Client Component 中** 使用 useEffect 配合状态或使用我们项目约定的 useSWR 钩子从 /lib/swr 导入。 - 永远不要在 Server Component 中使用 useEffect、useState 来获取数据。 #### 性能与优化 - 不要滥用 React.memo、useMemo、useCallback。仅在以下情况使用 - useMemo: 计算成本高昂且依赖项变化不频繁。 - useCallback: 函数作为依赖项传递给子组件且该子组件被 React.memo 包裹。 - React.memo: 大型列表中的子组件且其 Props 在父组件重渲染时经常保持不变。4. 集成与工作流实践4.1 如何在 Cursor 中配置与使用Cursor 编辑器对.cursorrules文件有原生支持这是最直接的集成方式。初始化规则文件在你的项目根目录下创建一个名为.cursorrules的文件。你可以直接从llm-ruleset仓库中复制你需要的模块内容粘贴到这个文件中。更高效的做法是将每个模块保存为独立的.md文件如rules/general-style.md然后在.cursorrules文件里通过引用或拼接的方式引入。!-- .cursorrules -- # 项目 AI 编码规则 !-- 引入通用规则 -- {{ include: ./rules/general-style.md }} !-- 引入 TypeScript 规则 -- {{ include: ./rules/typescript-strict.md }} !-- 引入 React 规则 -- {{ include: ./rules/react-nextjs.md }} !-- 项目特定规则 -- ## 项目特定约定 - 所有 API 请求必须通过 /lib/api-client 封装的函数发起禁止直接使用 fetch 或 axios。 - 错误处理统一使用 /lib/error-handler 中的 handleError 函数。注意Cursor 原生支持类似{{ include: ... }}的语法具体语法请参考最新文档这能让你更好地组织规则。如果该语法不被支持你也可以使用构建脚本在开发前将多个.md文件合并成一个.cursorrules文件。验证规则生效创建或打开一个.tsx文件尝试让 Cursor 的 AI 助手通过CmdK完成一个任务例如“创建一个显示用户列表的 React 组件从/api/users获取数据”。观察生成的代码是否符合你的规则是否是函数组件是否正确地使用了async/await如果是 Server Component或useEffect/useSWR如果是 Client Component导入语句是否排序正确类型定义是否完整上下文管理Cursor 的 AI 会将.cursorrules文件的内容作为项目级上下文。这意味着在任何文件中发起对话或编辑请求AI 都会“记得”这些规则。你无需在每个对话中重复说明基础规范。4.2 在 Claude Desktop 或其他工具中的使用对于 Claude Desktop、Windscope 或其他支持自定义系统提示词System Prompt或拥有项目级配置文件的 AI 编码工具llm-ruleset同样适用。定位配置位置找到工具的配置项通常称为“系统提示词”、“项目指令”、“自定义指令”或“角色设定”。在 Claude Desktop 中你可以在设置中设置全局的“自定义指令”但更推荐在项目目录下放置一个特定的配置文件如果支持的话。导入规则内容将你整理好的规则文本即.cursorrules文件的内容或合并后的规则内容完整地粘贴到系统提示词或自定义指令的配置框中。由于这些工具可能对上下文长度有限制你需要更加精炼地总结核心规则或者采用“分层提示”策略在系统提示词中放置最核心、最通用的规则然后在具体的对话中针对当前任务引用更详细的规则模块。指令优化为了在其他工具中达到最佳效果你可能需要在规则文本的开头加上一个强有力的“角色设定”指令。例如你是一位资深的全栈工程师严格遵守以下项目开发规范。请你在生成任何代码、回答问题或提出建议时都必须无条件优先遵循以下规则。如果用户的要求与规则冲突请提醒用户并按照规则执行。 接下来粘贴具体的规则内容这有助于强化 AI 对规则的理解和遵循优先级。4.3 与现有开发工具链的融合llm-ruleset不应是一个孤立的系统而应与现有的代码质量工具链协同工作形成闭环。ESLint Prettier 作为最终守门员将 AI 生成的代码视为“初稿”。规则集引导 AI 生成符合规范的代码但最终的格式化和静态检查应交由 ESLint 和 Prettier 完成。在你的规则中明确写明这一点并告知 AI 项目使用的具体配置如eslint-config-airbnb、typescript-eslint插件集。你甚至可以要求 AI 在生成代码块后附带一条注释说明需要运行的检查命令例如// 请运行npm run lint:fix和npm run format以确保代码风格一致。预提交钩子Pre-commit Hooks利用 Husky 和 lint-staged 设置 Git 预提交钩子。当开发者或 AI 辅助提交代码时自动对暂存区的文件运行 ESLint 和 Prettier。这确保了所有进入仓库的代码无论来源如何都符合统一标准。llm-ruleset的目标是让 AI 生成的代码在第一次通过钩子时就有更高的通过率。CI/CD 流水线检查在持续集成如 GitHub Actions, GitLab CI中设置步骤运行完整的测试套件、类型检查和 Lint。如果 AI 生成的代码引入了类型错误或严重的风格问题CI 会失败并阻止合并。这为团队提供了另一层保障。融合工作流示例开发者或 AI基于llm-ruleset的引导编写代码。保存文件时编辑器自动格式化Prettier。提交前Husky 触发lint-staged对修改的文件自动运行eslint --fix。提交后CI 流水线运行全量检查确保没有引入回归问题。通过层层关卡后高质量、风格一致的代码被合并到主分支。5. 高级技巧与疑难问题排查5.1 规则冲突与优先级管理当引入多个规则模块时可能会遇到规则冲突的情况。例如一个通用规则说“函数不超过30行”但一个处理复杂业务逻辑的模块可能提供了一个合理的35行函数示例。这时需要明确的优先级管理。解决方案是建立清晰的规则层级项目特定规则最高优先级在.cursorrules文件末尾或开头明确声明的、针对本项目的特殊约定具有最高优先级。例如“在本项目中尽管通用规则建议使用axios但我们统一使用fetch封装”。技术栈规则次之针对特定框架如 React、Next.js的规则优先级高于通用规则。因为框架的约定通常更具体、更不可违背。通用规则作为基础通用代码风格和质量规则作为默认基础在所有其他规则未覆盖的领域生效。在规则文件中你可以使用明确的声明来处理冲突### 规则优先级说明 1. 本文件末尾的【项目特定约定】部分优先级最高。 2. 其次是【React/Next.js 规范】部分。 3. 最后是【通用代码风格】部分。 当出现模糊或冲突时AI 应主动询问澄清或遵循更高优先级的规则。5.2 处理 AI 的“创造性”偏差有时即使有明确的规则AI 也可能产生一些“创造性”的、但不符合规则的解决方案。这通常发生在规则描述不够绝对或者 AI 认为它有“更好”的主意时。应对策略使用绝对化语言在关键规则上使用“必须”、“禁止”、“总是”、“绝不”等词语避免使用“应该”、“可以”、“考虑”等弱约束词汇。提供反面示例在规则中不仅说明“应该怎么做”也明确说明“禁止怎么做”并解释原因。例如“禁止在map循环中使用索引index作为 React 组件的key除非列表项是静态且永不重排的。必须使用数据中唯一且稳定的 ID 作为key。因为使用索引key在列表顺序变化时会导致性能下降和状态错乱。”即时纠正与上下文强化当 AI 第一次偏离规则时立即在对话中纠正它并要求它根据规则重写。你可以将纠正的对话内容提炼成一条新的、更具体的规则补充到你的规则集中。这是一个迭代优化规则集的过程。5.3 规则集的维护与版本化llm-ruleset本身也是一个需要维护的项目。创建规则仓库建议在团队内部建立一个私有的 Git 仓库来存放这些规则模块。这可以是llm-ruleset的一个 fork也可以是你们自己从零搭建的。模块化版本管理每个规则模块如react-best-practices-v1.2.md可以有自己的版本号。当 React 发布新版本并带来新的最佳实践时你可以创建v1.3的模块而不影响仍在使用旧版本 React 的项目。项目订阅规则各个项目可以通过 Git Submodule 或直接复制文件的方式“订阅”特定版本的规则模块。在项目的.cursorrules中引用这些模块文件。更新与通知当核心规则更新时团队负责人可以通知各项目负责人评估并决定是否将项目升级到新版本的规则。这类似于管理一个内部的基础库或 ESLint 配置。5.4 常见问题速查表问题现象可能原因解决方案AI 完全忽略规则1. 规则文件未放置在项目根目录。2. 规则文件名称不正确非.cursorrules。3. 在其他工具中系统提示词未正确设置或长度超限。1. 检查文件路径和名称。2. 在 Cursor 中尝试在聊天框输入/rules查看当前加载的规则。3. 在其他工具中精简核心规则或确认配置已保存生效。AI 部分遵循部分违反1. 规则描述存在歧义或矛盾。2. AI 的“创造力”压过了规则约束。1. 审查并重写有歧义的规则使用更绝对、清晰的表述。2. 在对话中立即纠正并将纠正案例作为反面教材加入规则。生成的代码风格与现有项目不符1. 规则集未涵盖项目的某些特殊约定。2. 项目本身的代码风格不一致。1. 在规则文件中添加“项目特定约定”章节明确这些特殊规则。2. 建议先使用 Prettier 和 ESLint 统一格式化现有代码库再让 AI 基于此生成新代码。规则太多导致 AI 响应变慢或混乱上下文过长干扰了 AI 对核心任务的理解。1. 精简规则只保留最核心、最通用的部分。2. 采用分层策略基础规则放在系统提示词具体任务时再通过对话补充详细规则。3. 定期回顾和删除过时或不重要的规则。如何为新技术栈如 Svelte创建规则缺乏现成模块。1. 从官方风格指南和社区最佳实践开始。2. 先让 AI 生成代码然后人工审查将发现的不符合约定的点逐条总结成规则。3. 迭代几次后就能形成初版的规则模块。我个人在实际使用中的体会是llm-ruleset的价值不在于一蹴而就而在于持续迭代。最开始你的规则可能只有简单的几条代码风格约定。随着你在项目中不断与 AI 协作每次遇到它“犯错”或产生不符合你心意的代码时不要只是手动修改而是思考“能否增加或修改一条规则让 AI 下次不再犯同样的错误” 将这条新规则记录下来。几个月后你就会积累出一套高度定制化、能极大提升你和团队开发效率的“AI 编码宪法”。这个过程本身也是对你和团队编码规范的一次深度梳理和强化。