AI编程助手行为准则：六大核心规则提升代码质量与开发效率-编程实验室

1. 项目概述：一份写给AI编程伙伴的“行为准则”

如果你和我一样，每天都在和Cursor、Claude、GPT这类AI编程助手打交道，那你一定经历过这种时刻：你只是想让它修个简单的bug，它却兴冲冲地给你重写了整个文件；或者，你让它实现一个功能，它二话不说就调用了最昂贵、最慢的模型，结果产出和用便宜模型没什么两样。更别提那些因为上下文过长导致的“失忆”，或者在不同任务间反复横跳、最终一事无成的“思维奔逸”了。这些体验，本质上是因为我们缺少一套和AI协同工作的“共同语言”和“游戏规则”。

今天要聊的这个项目，ycb/cursor-ai-coding-playbook，就是为解决这些问题而生。它不是一套复杂的框架，而是一份轻量级、高度实践性的“行为准则”集合。你可以把它理解为一本写给AI编程伙伴的“员工手册”，里面规定了在我们合作开发时，它应该遵循什么样的架构原则、代码风格、任务规划方式，以及最重要的——如何聪明地花钱（计算资源）。这套规则的核心目标非常明确：让AI写出更高质量的代码，显著降低不必要的计算成本，并让整个团队的开发流程保持高效、可预测。

这套规则适合所有正在或准备深度使用AI编程助手的开发者，无论你是独立开发者，还是团队中的技术负责人。如果你已经厌倦了AI的“自由发挥”，希望建立一种更稳定、更可控、更经济的协作模式，那么这个项目提供的思路和具体规则，将是你工具箱里不可或缺的一件利器。它不绑定于某个特定技术栈，其背后的思想——通过明确的约束来引导AI行为——适用于任何以LLM为核心的开发辅助场景。

2. 规则集核心设计哲学：约束即效率

在深入每条具体规则之前，我们必须先理解这个Playbook背后的核心设计哲学。它没有试图去创造一个无所不能的超级AI，相反，它承认当前AI模型的局限性，并通过精心设计的约束来扬长避短。这种思路，和我们管理一个才华横溢但经验不足的初级工程师非常相似：你需要给他清晰的边界和最佳实践，而不是放任自流。

2.1 轻量、固执己见与速度优先

项目描述中用了三个关键词来定义这些规则：Small（轻量）、Opinionated（固执己见）、Built for Speed（为速度而生）。这三点构成了整个规则集的基石。

轻量（Small）意味着每条规则都力求简洁、聚焦。一个.mdc文件只解决一个特定领域的问题，比如架构、代码风格或模型选择。这样做的好处是加载快、理解容易、组合灵活。你不会被一堆冗长的、相互耦合的规则搞晕，可以根据当前项目的需要，像搭积木一样启用或禁用某些规则。例如，一个快速原型项目可能只需要clean-simple-dry.mdc来保证代码可读性，而一个正式产品则需要加上architecture-principles.mdc来确保长期可维护性。

固执己见（Opinionated）是提升效率的关键。在编程领域，很多问题并没有唯一的“正确”答案，但往往存在经过验证的“更好”的实践。这个规则集不追求面面俱到，而是强硬地规定了一套它认为最优的实践。比如，它可能强制要求函数长度不超过某个阈值，或者优先使用组合而非继承。这种“固执”减少了AI的决策负担和不确定性。AI不需要在多种可行方案中纠结，只需遵循既定规则，从而产出更一致、更可预测的代码。这就像团队内部强制推行的代码规范，虽然有时会让人觉得不够灵活，但极大地提升了协作效率和代码质量。

为速度而生（Built for Speed）则直接呼应了“保持团队快速前进”的目标。这些规则的设计，处处考虑减少摩擦。例如，implement-plan.mdc中的规划模板强制任务原子化，避免了AI陷入一个庞大、模糊的需求中不断“思考”而无法产出。model-economy.mdc中的任务分类（CHEAP/STANDARD/PREMIUM）让AI能瞬间判断该用哪个模型，而不是每次都重新评估。速度不仅指AI响应的快慢，更指整个开发迭代周期的流畅度。

2.2 模块化与可组合性：规则即插件

这个Playbook在工程实现上采用了高度模块化的设计。所有规则都以独立的.mdc文件形式存放在/rules目录下。.mdc是Cursor规则文件的专用格式，本质上是一种Markdown的变体，其中可以包含自然语言指令和特定的元数据。

这种设计带来了巨大的灵活性：

按需取用：你可以只复制你需要的几个规则文件到你的项目中，而不是引入整个仓库。
渐进式采用：团队可以先从最迫切的规则（如model-economy）开始，熟悉后再逐步引入架构或全栈规则。
易于维护和贡献：每条规则独立，修改或优化一条规则不会影响其他规则。社区可以针对特定技术栈（如React/Next.js）贡献更细化的规则文件，与核心规则和平共处。

Cursor通过“Project Rules”功能自动加载并应用这些规则。当你将本仓库作为Git worktree链接到你的项目后，Cursor会识别这些.mdc文件，并将其中的约束和指令作为上下文的一部分，持续地影响AI助手在你项目中的每一次代码生成、重构和建议。这相当于为你的AI助手安装了一系列“行为插件”。

注意：规则的加载顺序有时会产生影响。通常，更通用、更基础的规则（如models.mdc这种元规则）应该先被加载，因为它定义了AI自身的行为模式。而具体的领域规则（如full-stack.mdc）则在其后生效。在组合多个规则时，需要注意它们之间是否存在冲突，一般来说，这些官方规则集设计时已考虑了兼容性。

3. 六大核心规则深度解析

这套Playbook包含了六条核心规则，每一条都针对AI协作中的一个痛点。下面我们来逐一拆解其设计意图、具体内容和实操要点。

3.1 架构原则：为AI划定设计的“护城河”

architecture-principles.mdc的目标是防止AI进行“过度设计”或产生不稳定的、难以演进的方案。对于中小型AI驱动产品而言，架构的核心是克制。

核心约束可能包括：

单一职责与清晰边界：强制每个模块、类或函数只做一件事。AI在生成代码时，会被要求明确说明当前单元的职责，如果发现它试图在一个函数里同时处理数据验证、业务逻辑和数据库操作，规则会提示进行拆分。
依赖方向稳定：遵循依赖倒置原则，鼓励定义稳定的抽象接口（如Repository模式），让具体实现依赖抽象，而非相反。这能引导AI生成更容易测试和替换的代码结构。
避免过早抽象：规则会警告AI不要在一开始就创建复杂的继承层次或过度通用的框架。鼓励“三次法则”——当同样的模式出现第三次时，再考虑抽象。这直接对抗了AI倾向于生成“漂亮但无用”的抽象模板的冲动。
显式优于隐式：要求配置、依赖和状态变化必须是显式的。这能减少AI生成那些依赖全局变量或魔法字符串的、难以调试的代码。

实操心得：这条规则在项目初期尤其重要。我曾经在一个新项目开始时启用了它，当我对AI说“为我们设计一个用户认证模块”时，它没有直接扔给我一个庞然大物，而是先反问：“认证的核心流程（注册、登录、令牌管理）和边界（与用户资料模块的关系）是什么？我们先定义接口。” 这迫使我和AI一起进行了一次简短但关键的设计对话，最终产出的结构清晰且后续扩展了多次也未出现腐化。

3.2 简洁、清晰与DRY：对抗“代码膨胀”的利器

clean-simple-dry.mdc可能是最直接提升代码可读性和可维护性的规则。它的敌人是“代码膨胀”——那些冗长、嵌套过深、重复且难以理解的代码。

规则的具体体现：

函数/方法长度限制：可能强制要求函数体不超过20-30行。如果AI生成的函数过长，规则会建议将其拆分为多个更小的、具有描述性名称的函数。
圈复杂度检查：提醒AI避免过高的条件嵌套（if/else, switch）。鼓励使用卫语句提前返回，或者用多态、策略模式来替代复杂的条件逻辑。
命名强制清晰：变量名如data、result，函数名如process()会被标记为不良实践。规则会推动使用userProfile、calculateOrderTotal这样具有业务含义的名称。
DRY（Don‘t Repeat Yourself）：当AI试图复制粘贴一段相似代码时，规则会提示“检测到重复模式，建议提取为公共函数/组件/钩子”。但它也会结合“避免过早抽象”的原则，智能判断是否真的需要提取。

一个典型的交互场景：你让AI“添加一个表单验证”。没有此规则时，AI可能生成一个包含所有验证逻辑的、80行长的巨型函数。有了此规则，AI可能会产出如下结构：

// 1. 定义验证规则函数（每个都很短小） const validateEmail = (email) => { /* ... */ }; const validatePasswordStrength = (password) => { /* ... */ }; // 2. 组合验证器的函数 const createValidator = (rules) => (data) => { /* ... */ }; // 3. 针对特定表单的应用 const loginFormValidator = createValidator([validateEmail, validatePasswordStrength]);

这种代码不仅更易读，而且每个小函数都易于单独测试。

注意：盲目追求极致的DRY有时会导致过度抽象，产生“错误的抽象”，这比重复的代码更难维护。好的规则会平衡DRY和“可读性优先”原则。有时，为了清晰表达意图，少量的重复是可以接受的。

3.3 全栈编程指南：确保AI的“上下文”不脱节

full-stack.mdc解决了AI在前后端分离开发中一个常见问题：上下文断层。AI可能会为你写一个完美的React组件，却完全忘了它需要对应的API端点；或者设计了一个数据库表，但没有生成与之匹配的TypeScript接口。这条规则强制AI进行“全栈思维”。

它的工作方式是建立跨层的契约和映射：

API契约先行：当AI开始实现一个前端功能时，规则会要求它先定义或引用一个清晰的API接口（如OpenAPI/Swagger描述，或简单的类型定义）。这确保了前后端对话的基础一致。
类型共享：鼓励（或强制）使用像tRPC、GraphQL Code Generator或共享TypeScript类型库这样的工具，确保从数据库实体到前端组件的props，类型定义只有一份单一事实来源。
数据流连贯性：从数据库查询 -> 后端序列化 -> API响应 -> 前端状态管理 -> 组件渲染，这条规则会提示AI检查每个环节的数据转换是否一致、高效。例如，它会提醒AI避免在后端加载整个实体然后在前端过滤，而应该将过滤条件推到数据库查询中。

实操案例：假设你要求AI“添加一个显示用户待办事项列表的页面”。在full-stack.mdc规则下，AI的产出可能是一个包含以下步骤的规划：

数据库：确认todos表结构，或创建之。
后端：创建GET /api/todos端点，包含查询参数（状态、分页）。
共享类型：定义Todo接口（包含id, title, status, createdAt等字段）。
前端：
- 创建useTodos钩子，用于调用API并管理加载/错误状态。
- 创建TodoList组件，接收todos数组作为props。
- 创建TodoItem组件用于渲染单条待办。
集成：将上述部分组合到页面组件中。

整个过程是连贯的，AI不会只给你一个孤零零的前端组件。

3.4 高效规划：将模糊需求转化为可执行原子任务

implement-plan.mdc可能是最能提升人机协作效率的规则。它的核心思想是：任何非琐碎的任务，都必须先有一个计划。这直接针对了AI容易“思维奔逸”和产生“巨型差异”的问题。

规划模板通常强制包含以下要素：

任务标题：一句话说清要做什么。
背景/上下文：为什么需要做这个？关联的Issue或需求是什么？
验收条件：具体、可验证的完成标准。例如：“用户点击提交后，数据应持久化，并看到成功提示；表单错误应高亮显示。”
原子步骤：将任务分解为顺序执行的、尽可能小的步骤。每个步骤都应该能独立产生一个清晰的、可审查的代码变更。例如：
1. 在models目录下创建User.ts类型定义。
2. 在api/users.ts中实现createUser函数。
3. 创建components/UserForm.tsx组件。
4. 在pages/signup.tsx中集成表单组件并调用API。
模型选择建议：根据任务复杂度，标注使用CHEAP、STANDARD还是PREMIUM模型（与model-economy规则联动）。

这样做的巨大好处：

对齐认知：在你批准计划之前，你和AI对“完成”的理解已经达成一致。
控制范围：防止AI一次性修改50个文件来实现一个“小功能”。
便于回滚：如果某个步骤出了问题，你可以轻松回滚到上一步，而不是面对一个混乱的、混合了多个功能的大提交。
提升AI表现：有了清晰的步骤，AI更不容易“迷失”，它能更专注地完成当前小目标。

我的使用习惯：我现在养成了一个习惯，对于任何超过“修一个简单bug”的任务，我都会先对AI说：“请根据implement-plan规则，为【任务描述】制定一个执行计划。” 审阅并微调计划后，再说：“好的，请开始执行步骤1。” 这就像和一个可靠的开发伙伴进行任务分解和派工，体验流畅得多。

3.5 模型经济：聪明地花掉每一个Token

model-economy.mdc是直接关乎“钱包”的规则，也是这个Playbook最具特色的部分之一。它的目标是在效果和成本/速度之间取得最佳平衡。AI模型（如Claude Sonnet, GPT-4, Codex）的能力和价格差异巨大，盲目使用最强模型是最大的资源浪费。

核心机制：任务三级分类法规则会引导AI（以及你）在开始任何任务前，先对其进行分类：

CHEAP（廉价）：适用于简单、模式化的任务。例如：代码格式化、重命名变量、根据现有模式添加一个类似的函数、简单的语法错误修复。这类任务应使用最快、最便宜的模型（如Cursor的快速模式或较弱的模型）。
STANDARD（标准）：大多数日常开发任务。例如：实现一个已有清晰设计的业务逻辑函数、编写单元测试、完成一个中等复杂度的组件。使用平衡了能力和成本的通用模型（如Claude Sonnet Haiku或GPT-3.5级别）。
PREMIUM（高级）：适用于需要深度推理、创造性设计或处理极其复杂上下文的任务。例如：设计一个新模块的架构、重构一团混乱的遗留代码、解决一个涉及多步骤的复杂bug。这时才动用“重型武器”（如Claude Sonnet Opus或GPT-4）。

如何实现分类？规则可能通过多种方式实现：

model-check文件头：在项目根目录或特定文件顶部，可以有一个注释，如// model-check: STANDARD，来提示AI该文件的默认处理级别。
基于启发式的判断：规则本身内嵌了一些启发式逻辑，例如，如果任务描述中包含“设计”、“架构”、“重构”、“复杂逻辑”等词，会建议PREMIUM；如果只是“修复拼写错误”、“调整样式”，则建议CHEAP。
用户手动指定：在你给AI指令时，可以直接加上[CHEAP]或[PREMIUM]标签。

其他成本控制策略：

上下文窗口管理：提醒AI避免无意义地加载整个代码库的上下文。优先加载相关文件，对于大型文件，尝试只加载必要部分（如特定函数）。
避免无效重写：设置守卫条件，防止AI仅仅为了微小的风格调整而重写一个几百行的文件。应该使用更精准的编辑指令。
批量处理建议：将多个小的CHEAP任务攒在一起，一次性提交给AI处理，减少交互次数和上下文加载开销。

实测效果：在我一个中型项目中，启用model-economy规则并配合自觉分类后，月度AI计算成本估计下降了40%以上，而开发效率并未受影响。因为大多数任务（代码补全、小修小改）确实不需要动用最强大的模型。

3.6 模型元规则：约束AI自身的“思考”方式

models.mdc是一条“元规则”，它不直接约束产出的代码，而是约束Cursor AI模型自身在处理任务时的行为模式。这是确保以上所有规则能被有效执行的基础。

它可能包含如下约束：

输出格式标准化：要求AI在回复时，必须使用清晰的结构，比如先输出“计划”，再输出“代码变更”，并且用特定的Markdown标题分隔。这让你能快速定位信息。
强制确认与澄清：对于模糊的需求，规则会强制AI先提出澄清问题，而不是基于猜测开始编码。例如，用户说“让它更快”，AI应追问“是指减少页面加载时间，还是提高函数执行速度？是否有可量化的目标？”
遵守成本分类：强化model-economy规则，如果用户没有指定，AI应主动根据任务性质建议一个分类，并在执行前征得同意。
变更范围最小化：强调“除非必要，否则不要动无关的代码”。在生成差异时，尽量使变更集（diff）保持小巧、聚焦。

这条规则相当于给AI套上了一个“行为矫正器”，让它从一个才华横溢但莽撞的助手，变成一个严谨、专业、可预测的合作伙伴。

4. 实战部署与集成指南

理解了规则是什么以及为什么之后，最关键的一步是如何将它们应用到你的实际开发 workflow 中。项目提供了几种方式，各有优劣。

4.1 方式一：Git Worktree（推荐方式）

这是最优雅、最便于同步更新的集成方式。Worktree 允许你在一个仓库的同一个本地副本上，签出多个分支到不同的目录，但它们共享大部分对象存储。

操作步骤：

进入你的项目目录。
添加Worktree：执行以下命令，这会在你的项目根目录下创建一个名为.cursor（或你指定的其他名字）的文件夹，里面是cursor-ai-coding-playbook仓库的内容。

git worktree add .cursor <playbook-repo-url> --no-checkout # 或者，如果你已经克隆了playbook仓库到本地，可以指向本地路径 git worktree add .cursor /path/to/cursor-ai-coding-playbook

在Cursor中启用：打开你的项目，进入Cursor的设置或规则管理界面（通常叫“Project Rules”或类似名称）。添加规则路径，指向<your-project>/.cursor/rules目录。Cursor会自动加载该目录下所有的.mdc文件。

优点：

自动更新：当Playbook仓库有更新时，你只需要进入.cursor目录，执行git pull，所有项目即刻享用最新规则。
隔离干净：规则文件独立于你的项目代码，不会污染你的主仓库。
一键复用：在任何新项目中，只需重新执行git worktree add即可。

缺点：

需要稍微了解Git worktree的概念。
在你的项目目录中会多出一个子文件夹。

4.2 方式二：克隆并复制规则文件夹

这是最直接、门槛最低的方式。

操作步骤：

将cursor-ai-coding-playbook仓库克隆到本地任意位置。
将其/rules文件夹整个复制到你的项目根目录下（或某个你认为合适的子目录，如.cursor/rules）。
在Cursor中，将规则路径指向你项目内的这个rules文件夹。

优点：

简单粗暴，无需理解Git高级功能。
规则文件成为你项目的一部分，适合需要定制化修改规则的项目。

缺点：

更新麻烦：如果Playbook更新，你需要手动复制/替换文件，容易遗漏或产生冲突。
污染项目：规则文件可能会被意外提交到你的代码仓库中（记得在.gitignore中添加rules/或.cursor/）。

4.3 方式三：选择性导入单条规则

如果你只想尝试其中一两条规则，或者你的项目有特殊约束，这是最灵活的方式。

操作步骤：

浏览Playbook仓库的/rules目录，找到你需要的.mdc文件（例如model-economy.mdc）。
将该文件内容复制出来。
在你的项目中创建一个新的.mdc文件（例如my-economy-rule.mdc），将内容粘贴进去。
根据你的项目实际情况，对规则进行微调。例如，在model-economy.mdc中，你可以修改CHEAP任务的具体定义，以更符合你的项目技术栈。
在Cursor中启用你这个自定义的规则文件。

优点：

极致灵活，完全定制。
学习规则内部结构的好方法。

缺点：

失去了与官方规则集同步更新的好处。
需要自己维护。

重要提示：无论采用哪种方式，在启用规则后，建议先从一个小型、非关键的任务开始试水。观察AI的行为变化，感受规则是否过于严格或存在不适应你项目的地方。你可以随时在Cursor的规则界面中禁用或调整规则加载顺序。

5. 规则调优与常见问题排查

即使是最好的通用规则，也可能需要根据团队或项目的独特文化进行微调。此外，在规则应用过程中，你可能会遇到一些预期之外的情况。

5.1 如何定制化规则？

.mdc文件本质上是文本文件，你可以像编辑文档一样编辑它们。定制化通常发生在两个层面：

参数调整：规则中可能有一些可配置的阈值。例如，在clean-simple-dry.mdc中，函数行数的上限可能是硬编码的30。如果你认为40更适合你的团队，直接修改这个数字即可。
逻辑增补：你可以为特定技术栈添加细节。例如，在full-stack.mdc中，你可以增加关于你团队使用的特定状态管理库（如Zustand, Jotai）或API客户端（如React Query, SWR）的最佳实践指引。
风格统一：如果团队有独特的代码风格（如特定的命名约定、文件组织方式），可以将这些要求写入clean-simple-dry.mdc或新建一个team-style.mdc文件。

定制化示例：假设你的团队大量使用React Query，你可以在full-stack.mdc末尾或单独创建一个react-query-patterns.mdc，加入如下内容：

## React Query 模式 - 对于数据获取，优先使用 `useQuery`。 - 查询键（query keys）必须结构化，遵循数组格式，例如 `['posts', 'list', { filter }]`。 - 突变（Mutations）使用 `useMutation`，并在 `onSuccess` 中使相关查询失效（invalidate）。 - 避免在组件中直接手动管理加载和错误状态，使用 `useQuery` 返回的 `isLoading`, `error` 等状态。

然后让Cursor同时加载这条补充规则。

5.2 常见问题与解决方案

在应用这些规则时，你可能会遇到一些挑战。下表总结了一些常见问题及其应对思路：

问题现象	可能原因	排查与解决思路
AI变得“迟钝”或响应变慢	1. 启用了过多或过于复杂的规则，增加了AI处理提示词的负担。 2.`model-economy`规则错误地将任务分类为`CHEAP`，使用了能力较弱的模型处理复杂任务。	1.精简规则：暂时禁用非核心规则，观察性能变化。确认是否是规则文件本身过大。 2.检查分类：在任务指令中显式指定`[PREMIUM]`，看是否解决问题。如果是，可能需要调整`model-economy.mdc`中的分类启发式逻辑。
AI产出不符合预期，甚至更差	1. 规则之间存在冲突或歧义。 2. 规则与项目现有代码风格或架构严重不符，导致AI陷入矛盾。	1.检查规则顺序：调整规则加载顺序，将更基础、更通用的规则（如`models.mdc`）放在前面。 2.审查规则内容：逐条检查启用的规则，看是否有相互矛盾的指令。例如，一条规则要求“函数简短”，另一条要求“避免过早抽象”，在边界情况下可能冲突。 3.渐进启用：不要一次性启用所有规则。先启用1-2条最关心的，磨合好后再增加。
AI频繁要求澄清，影响流畅度	`models.mdc`中的“强制澄清”规则过于严格，对某些在你看来很明确的上下文也要求确认。	调整元规则：编辑`models.mdc`，放宽对澄清的要求。例如，可以修改为“仅在需求涉及核心业务逻辑或安全时要求澄清”，或者为常见、模式化的任务设置白名单。
规则对某些文件或目录不生效	Cursor的规则作用范围可能设置有误，或者某些文件被排除在外。	1.检查规则路径：确认Cursor中配置的规则路径是否正确指向了包含`.mdc`文件的目录。 2.检查全局/项目设置：查看Cursor设置中是否有全局规则覆盖了项目规则。 3.使用文件头注释：在特定文件顶部添加`// cursor-rule: enable`或类似的注释来显式启用（如果规则支持此功能）。
团队成员体验不一致	成员本地的Cursor版本、规则文件版本或配置不同。	统一管理：强烈推荐使用Git Worktree方式，并将`.cursor`目录的更新纳入团队工作流（如每次拉取主分支后，也进入`.cursor`目录执行`git pull`）。确保所有成员加载同一套规则。

5.3 规则失效的深度排查

如果以上方法都不能解决问题，可以进行深度排查：

查看Cursor的调试信息：一些AI编程助手会提供“调试”或“日志”面板，显示它实际接收到的提示词（包括加载的规则内容）。检查你的规则是否被正确加载并插入到了系统提示中。
简化测试：创建一个全新的、最小的测试项目（例如一个空的Node.js或React项目），只启用一条有问题的规则，然后给AI一个非常简单的指令，看规则是否生效。这可以排除项目复杂性的干扰。
检查规则语法：.mdc文件虽然是Markdown，但可能有特定的元数据格式或指令语法。确保你的修改没有破坏文件结构。对比官方仓库的原版文件。
模型差异：不同的AI模型（Claude Sonnet, GPT-4, Codex）对规则的理解和遵循程度可能有细微差别。尝试切换模型，看是否是特定模型的问题。

最后，也是最重要的，保持耐心和迭代的心态。将AI编程助手与规则协同工作，看作是一个需要不断调试和优化的系统。没有一劳永逸的配置，随着项目演进、团队成长以及AI模型本身的更新，这套“行为准则”也需要不断地被审视和调整。这正是该项目开源并欢迎贡献的意义所在——它不是一个死的规范，而是一个活的、由社区共同驱动的协作智慧结晶。