CodeBuddy用户规则：让AI成为懂你项目的编码协作者

第一次用 CodeBuddy 跑一个前端改造任务，我的感受是：它确实能干活，但干出来的活儿不像我这个团队的人干的。函数命名方式不同，组件拆分粒度不同，注释风格不同，甚至连错误处理的位置，都跟我们平时写的不太一样。结果能用，但代码 review 时会非常痛苦。

后来我才意识到，问题不在 CodeBuddy 本身，而在我从来没有告诉过它我们这个项目的规矩。就像来了一个很聪明的新同事，能力很强，但你不告诉他团队的编码规范、技术选型和历史包袱，他交出来的第一版代码一定和你的预期差得很远。

CodeBuddy 里的“用户规则”，就是用来解决这个问题的。它不是情怀式的设定，而是给 AI 一份可执行的、属于你和团队的“工作守则”。规则写得好不好，直接决定 CodeBuddy 是“聪明但外行”的临时帮手，还是“懂你这个项目的老同事”。

1. 先想清楚：你是在给 AI 立规矩，还是在帮 AI 补记忆

很多人第一次听说“创建用户规则”，第一反应是：哦，就是给 AI 设定角色嘛，让它扮演一个资深前端工程师。这个理解没错，但太浅了。

1.1 CodeBuddy 为什么需要用户规则

先想一个很现实的问题：一个大语言模型，在训练阶段看过全世界的开源代码，它什么都懂一点。但“什么都懂”恰恰意味着它对你一无所知。

它不知道你的项目用的是 Vue 2 还是 Vue 3，不知道你们的组件库是 Element Plus 还是自研的，不知道你们是必须写 JSDoc 还是注释越少越好，不知道哪些历史函数是“虽然看起来很怪但绝对不能动”的。

这些信息，官方文档里查不到，开源代码里也不一定出现。它是一个团队的私有知识，是代码评审时反复强调的“隐性共识”。

在 CodeBuddy 创建用户规则，本质上是把这些隐性共识显式写下来，变成 AI 每次对话、每次补全、每次重构时都会参考的上下文。你可以把它理解成：给 AI 补上了一段“入职培训”。

我见过很多用户，规则里只写了“你是一名资深 Java 开发工程师，请给出高质量代码”。这种规则不能说没用，但它只是给 AI 设定了一个姿态，没有给它具体的行为约束。

1.2 规则不是在限制 AI，而是在降低 AI 的错误率

这里要纠正一个常见误区：规则越多越细，AI 是不是就越死板？恰恰相反。

对 CodeBuddy 这类工具来说，规则的作用是缩小它的猜测范围。模型在生成代码时，本质上是在做概率选择。没有规则时，它会在多种合理的写法里挑一个概率最高的。但概率最高不一定适合你的项目。有了明确规则，它就不用猜了，直接按你写明的方向走，出错的概率反而低很多。

所以，好的规则不是“限制 AI”，而是“给 AI 提供信息”。每一条规则，都是在消解一个不确定性。

2. 用户规则、项目规则、Agent 规则，先分清这三层

打开 CodeBuddy 的规则配置，很多新手会困惑：到底有哪些入口？我该配置哪一个？这里要先建立一个分层概念，否则后面很容易配置错地方，导致规则不生效，或者生效了但优先级不是你想要的样子。

2.1 三层规则的定位与优先级

按照通用实践，CodeBuddy 这类 AI 编程工具通常会有三种不同粒度的规则载体：

优先级的通用规则是：越具体、作用范围越小的规则，优先级越高。也就是说，如果用户级规则里写了“注释用中文”，项目级规则里写了“对外 API 注释必须用英文”，AI 通常会优先遵守项目级规则。

这个设计是合理的。用户级规则是你的个人习惯，项目级规则是团队在该项目上的共同契约。二者冲突时，项目利益通常优先于个人偏好。

2.2 什么时候创建用户规则，什么时候只用项目规则

我的建议是：

• 如果你只有一个人在用 CodeBuddy，或者你主要在个人项目里使用，那用户级规则就够了，直接配置当前账号的默认规则。
• 如果你是团队协作，项目代码共享，那建议优先配置项目级规则，并随仓库提交，让每个成员 clone 下来就自动生效，不需要各自手动设置。
• 如果你有比较固定的任务流程，比如“每次改完代码必须跑单测”，那可以把这部分写进项目规则，或者更进一步，做成一个 Agent / Skill。

另外，从实际工程经验来看，项目级规则一定要放进版本控制。代码是团队资产，规则同样也是。没有纳入版本控制的规则，换一台机器就丢了，New 一个同事进来也看不到，时间一长就又变成了某个人电脑里的私有配置。

3. 创建 CodeBuddy 用户规则：从哪里进，怎么写

确认了层级之后，下一步就是实际操作。CodeBuddy 目前主要在 IDE 插件和独立应用里使用，不同版本的设置入口可能略有差异，但整体思路是一致的。

3.1 先确认入口和生效范围

常见做法是，在 CodeBuddy 设置面板里找到“规则”或“自定义规则”相关入口，创建用户级规则。如果你用的是 IDE 插件，通常在插件设置页里能找到；如果是独立应用，一般在账号设置或个人偏好里。

有一点要注意：入口不同，生效范围就不同。如果你在某个项目的工作区设置里写的规则，它只对这个项目生效；如果你在用户设置或账号设置里写的规则，它会对当前账号的所有项目生效。创建之前，先想清楚你要写的是哪一个层级的规则。

还有一个容易忽略的地方：规则保存之后，通常不会立即对已经打开的会话生效。很多工具会要求新会话才会重新加载规则，或者在修改规则后需要刷新一下。遇到“明明改了规则但行为没变化”的情况，先别急着怀疑工具，先重新开一个对话试试。

3.2 一份能用的用户规则，至少包含五个模块

我建议不要从网上复制一份看起来很全面、很长很长的规则就完事。规则不是越全越好，而是越贴近你自己的使用场景越好。一份真正能用的规则，至少应该覆盖五个模块：

1. 身份与目标定位：你希望 CodeBuddy 在你这个场景里扮演什么角色，优先解决什么问题。
2. 通用编码行为约束：命名规范、注释语言、函数拆分粒度、错误处理方式、代码风格。
3. 技术栈与项目背景：你常用的语言、框架、版本、构建工具、UI 组件库、目录结构。
4. 任务执行流程：改代码前要不要先解释方案、写完要不要自测、要不要给出改动清单。
5. 明确禁止事项：哪些事情绝对不能做，比如不要随意改公共配置、不要删除看似无用的代码、不要使用某些依赖。

下面是一个参考模板，你可以按自己的情况裁剪：

# CodeBuddy 用户规则模板 ## 身份定位 你是一名熟悉前后端全栈开发的工程师，当前主要协助我完成 Web 项目的编码、调试和代码评审。 ## 通用行为约束 - 代码注释一律使用中文，但命名（变量、函数、类）使用英文。 - 函数命名使用 camelCase，组件命名使用 PascalCase。 - 先分析现状再给出方案，不要直接输出一整个文件的重写代码。 - 每次修改后列出变更清单，标注涉及的文件和改动原因。 ## 技术栈约定 - 前端：Vue 3 + TypeScript + Vite，组件库使用 Element Plus。 - 后端：Node.js + Express，使用 Prisma 作为 ORM。 - 涉及接口返回时，统一使用 { code, message, data } 结构。 ## 任务流程 - 接到需求后，先简要复述需求，再给出实现方案。 - 涉及核心逻辑修改时，要求我确认后你再生成代码。 - 代码生成后检查是否存在类型错误和边界条件问题。 ## 禁止事项 - 不要修改 vite.config.ts 之外的构建配置。 - 不要新增没有经过确认的第三方依赖。 - 不要删除测试用例或跳过测试。

这个模板可以用，但它只是骨架。真正用起来之后，你会慢慢往里面加自己的习惯。比如你发现自己特别容易被 AI 的“额外发挥”困扰，那就加一条：“只完成要求的事，不要顺手改动无关代码”。比如你发现 AI 总喜欢把简单问题复杂化，那就加一条：“优先给出最小改动方案，而不是大范围重构方案”。

4. 规则不是越多越好，关键要写“让 AI 能执行”的话

规则写得好不好，判断标准只有一个：AI 拿到这段话之后，能不能稳定地按照它执行。很多规则写得很漂亮，但 AI 看完之后还是不知道该怎么做，这不是 AI 的问题，是规则本身不够“可执行”。

4.1 无效规则和有效规则的差别

先看两组对比。

无效写法：

• “请生成高质量代码。”
• “注意代码的可维护性。”
• “请遵守社区最佳实践。”

这些话不是不对，而是太抽象了。什么叫高质量？什么叫可维护？每个工程师的理解都不一样，AI 更不知道你的标准指什么。

有效写法：

• “工具函数必须放在 src/utils 目录，并导出为具名函数。”
• “新增组件时必须拆分为基础组件和业务组件两层。”
• “所有接口请求必须经过 request.ts 封装，禁止在页面里直接调用 axios。”

这些规则每一句都可以被验证：AI 生成代码后，你扫一眼就知道它有没有遵守。规则写得越具体，AI 的执行率就越高，你后续纠偏的成本就越低。

这里有一个很实用的判断标准：如果一条规则连你的同事都能一眼看懂并执行，那它大概率可以被 AI 执行。如果还需要解释、举例、补充背景，那它就还需要继续拆细。

4.2 规则数量要克制，别把上下文塞爆

另一个常见问题是：规则越写越长，从几行膨胀到几千字。要知道，规则并不是无限免费的空间。

CodeBuddy 每次处理任务时，会把规则作为上下文的一部分传给模型。规则越长，留给用户对话和代码内容的上下文空间就越小。规则写到一定程度，收益会急剧下降，甚至因为过度占用上下文，导致模型忘记用户真正想让它做的事情。

从经验看，用户级规则控制在 300 到 600 字左右比较合适。项目级规则可以稍微长一点，但也不要超过 1000 字。重要的不是全，而是精。

如果你发现自己需要写的规则非常多，那就要反思一下：是不是这些规则其实更适合放到 Skill 或者 Agent 里？规则管理的是“默认状态”，Skill 管理的是“特定任务”，两者分工不同。

一个很现实的建议：规则只写那些你反复纠正过 AI 多次的行为。如果某个问题你只遇到一次，那就不要写进规则。规则的价值在于长期稳定生效，不是记录所有偶发问题。

5. 规则建好后，为什么有时还是“不听话”

配置好规则，和规则真正生效，中间还隔着一层。我在实际使用中，遇到过几次“规则没生效”的情况，排查下来发现原因五花八门。

5.1 排査链路：从现象到原因

遇到规则不生效，建议按下面的顺序排查，不要上来就怀疑是工具 bug：

1. 看现象：是完全没有遵守，还是部分遵守？是完全无视，还是优先级不对？先搞清楚具体是哪种“不听话”。
2. 看入口和层级：你配置的是用户级规则，还是项目级规则？当前打开的项目有没有它自己的项目级规则把用户级行为覆盖掉了？
3. 看保存状态：规则有没有保存成功？保存后有没有重新开一个会话？很多工具不会对旧会话重新加载规则。
4. 看内容本身：规则里有没有相互矛盾的描述？比如一边说“不要使用第三方库”，一边又说“优先使用成熟的库”，这种冲突会让 AI 陷入两难。
5. 看上下文占用：规则是不是太长了，导致模型实际生成时已经“记不住”前面的规则内容。
6. 看 IDE 或版本差异：CodeBuddy 在插件和独立应用里的行为可能不完全一致。如果你在两个环境之间切换使用，规则文件未必同步。

这六步里，最容易被忽略的是第 2 步。团队项目里经常存在多份规则文件，比如项目根目录有自己的规则文件，团队仓库里还有一份通用规范。当多份规则同时存在时，AI 会按优先级机制处理，但处理结果不一定符合你的直觉。

5.2 常见坑点：规则冲突、过度约束、版本切换

规则写多了之后，还会出现一个反向问题：约束过强，AI 变得畏手畏脚。

比如你写了一条规则“所有修改都必须列出影响范围”，AI 每次都会在任务开始前先输出一大段分析，即使只是改一个变量名也不放过。这个时候，规则就从“帮助判断”变成了“降低效率”。

处理办法是给规则加边界条件。比如改成：“涉及接口协议变更或公共组件改动时，必须列出影响范围；常规参数修改可以直接完成。”也就是说，规则也要分主次、分场景，不能一刀切。

再有一个坑：CodeBuddy 相关的工具链迭代很快，规则配置本身也可能随版本更新发生变化。比如 WorkBuddy 时代的项目和规则配置，迁移到 CodeBuddy 后，某些路径、文件名、格式可能不再兼容，需要重新调整。迁移旧项目时，不要假设所有配置都能原样使用，先检查规则文件是否被正确识别，再逐步补齐。

注意：规则配置是一个需要长期维护的对象。不是写完一次就永远不用管，每次工具大版本升级、项目技术栈变化、团队规范调整，都要同步检查规则是否仍然适用。

6. 从规则到 Skill 再到 Agent：把 CodeBuddy 用成一套工作流

用户规则只是 CodeBuddy 使用的第一层。真正想把它从“对话助手”变成“能稳定交付任务的协作工具”，你还需要把规则、Skill、Agent 这三件事串起来。

6.1 规则、Skill 和 Agent 怎么配合

规则负责定义“AI 在所有场景下的默认行为”，它是底座。Skill 负责定义“某个特定领域的专业知识和操作方式”，比如常见的“前端页面脚手架生成 Skill”“代码评审 Skill”“数据库变更脚本 Skill”。Agent 则是在 Skill 基础上，结合具体任务上下文，形成一个可以自主执行多步骤任务的流程单元。

用一个类比来理解：规则像是公司的员工手册，它规定了所有员工的基本原则；Skill 像是岗位说明书，它定义了某个岗位需要掌握的操作方法；Agent 则是一个在明确任务驱动下，按照手册和岗位要求去完成一件具体事情的人。

如果你只写规则，不配置任何 Skill，码 CodeBuddy 也能干活，但它的能力上限是“通用工程师”。如果你配置了符合你项目场景的 Skill，再配合规则里的行为约束，CodeBuddy 就更像一个“熟悉你们项目的老工程师”。

从社区讨论的热度来看，很多人在找 CodeBuddy 的常用前端 Skill，说明大家已经意识到：单靠提示词和规则，覆盖不了深度任务。Skill 的价值在于把复杂的专业知识打包好，让 AI 在调用时不需要临时从零组织思路。

对大多数开发者，我的建议路径是：

1. 先用规则把你的“默认偏好”固定下来。
2. 再为高频任务创建 Skill，比如代码生成、测试编写、日志分析。
3. 最后再去尝试 Agent 类的多步任务编排。

不要一开始就追求完整的 Agent 流程。先让规则和 Skill 跑顺，再考虑自动化，会稳妥很多。

6.2 把规则当成团队资产来维护

聊到这里，我想再把话题拉回一个持续价值的问题：用户规则怎么维护？

很多个人开发者一开始兴致勃勃写了一套很详细的规则，用了一个月之后就再也不更新了，因为后面发现 AI 犯的错逐渐减少了，规则也就没必要动了。这是好现象，但不代表规则不需要维护。

更值得推荐的做法是，把规则当成代码来管理。它有版本，有讨论，有变更记录。团队内部每隔一段时间，比如一个迭代或一个月，review 一次规则文件，看看哪些规则已经失效，哪些行为反复被纠正但规则里还没覆盖。这个习惯的价值，会在团队规模变大、项目复杂度上升之后越来越明显。

另外有一个现实问题：有用户反馈 CodeBuddy 消耗积分很快。规则在这里也能帮上忙。规则写得好，AI 第一次生成的结果就更接近你的预期，不需要反复对话修正，自然就减少了无效调用。反过来，如果规则缺失或写得模糊，AI 每次都要靠多轮对话来“猜”你的意图，积分消耗自然更大。所以，与其抱怨积分不够用，不如先检查一下自己的规则是不是太笼统了。

建议：如果你发现 CodeBuddy 经常需要多轮纠正才能给出可用结果，先别急着换工具，回头看看自己的规则文件。很多时候不是模型不够聪明，是你没有把“什么是可用”说清楚。

这篇文章写到这里，核心想传递的其实就一句话：CodeBuddy 的规则系统，是你和 AI 协作的“接口”。接口设计得清晰，协作效率就高；接口模糊，任何模型都很难稳定地产出你满意的结果。

如果你现在还没有写过任何规则，下一步最该做的事很简单：打开 CodeBuddy 的规则设置，先写四条规则——我是谁、我用的什么技术栈、代码要遵守哪些基本规范、什么东西绝对不能碰。先写这四条，跑一次真实任务，再根据结果逐步补充。

规则这个东西，不追求一次到位，追求的是不断靠近你真实的工作方式。它有价值，不是因为写得长，而是因为它让 AI 变成了一个知道你的规矩、记得住你的规矩、愿意遵守你的规矩的协作对象。