1. 为什么我要给 CodeBuddy 定一套自己的规则用 CodeBuddy 这类 AI 编程助手的人大概都经历过同一个阶段刚开始觉得它挺神写个函数、补个测试、解释一段祖传代码都很顺手用了一段时间之后开始觉得它不听话——同样的项目它一会儿用这个风格一会儿用那个风格生成的代码要改半天才能合进主分支。问题往往不在模型本身而在于你从来没告诉过它在这个项目里规矩是什么。我把它叫做我的 CodeBuddy 规则。说白了就是一套写给 AI 看的项目约定代码风格怎么定、目录结构长什么样、哪些库能用哪些不能用、提交信息怎么写、遇到不确定的需求该问还是该猜。这套规则不是官方文档里的标准答案而是我在实际项目里反复踩坑、反复调整之后沉淀下来的个人配置。它解决的核心问题是让 AI 的输出从能跑变成能直接合进我的代码库。这篇文章适合三类人看。第一类是刚上手 CodeBuddy、还在摸索怎么让它稳定输出的人第二类是已经用了一阵子、但每次都要手动改格式改到烦的人第三类是把 CodeBuddy 当成团队协作工具、想让多个人的 AI 输出保持一致的人。不管你是写前端、后端还是脚本规则的设计思路是通用的具体条款可以按自己的技术栈替换。我下面会把这套规则拆成几个部分讲先讲清楚规则到底该管什么、不该管什么再讲具体条款怎么写然后是规则怎么落地到实际工作流里最后是我踩过的几个典型坑。全程都是我自己在用的东西不吹不黑能抄的直接抄。2. 规则到底该管什么边界比条款更重要2.1 先想清楚哪些事值得写进规则很多人第一次写规则恨不得把整本代码规范手册塞进去结果 AI 记不住自己也维护不动。我的经验是规则只写那些AI 默认会做错、但你又特别在意的事。默认就做得对的事不用写你不在意的事也不用写。举个具体的例子。CodeBuddy 默认生成的 Python 代码函数命名基本是 snake_case这个不用你教。但它默认可能给你写一堆print调试语句或者在没有类型注解的情况下生成复杂函数这些就是值得写进规则的。再比如它默认喜欢用最流行的库解决问题但你的项目可能因为历史原因锁定了某个老版本库这个必须写清楚。我一般把规则分成四类来管理类别管什么举例风格类命名、缩进、注释语言注释用中文、函数不超过 50 行结构类目录、文件、模块划分新组件放src/components/下依赖类能用/不能用哪些库禁止引入 lodash用原生方法流程类提交、测试、分支每次改动必须带单测这四类里风格类和依赖类是最容易见效的写进去之后 AI 的输出立刻就不一样了。结构类和流程类需要配合项目实际情况写起来更费劲但收益也更大。2.2 哪些事千万别写进规则规则写多了会有一个副作用AI 变得畏手畏脚遇到稍微复杂的需求就开始请示反而降低效率。我踩过这个坑早期写了一条任何不确定的地方都要先问我结果它连这个变量叫什么名字都要问一遍烦得我直接删了。我的建议是规则里不要写遇到 X 就停下来问这种模糊的兜底条款而是写具体的判断标准。比如不要写不确定就问而是写涉及数据库 schema 变更时先输出变更方案再动手。前者会让 AI 频繁打断你后者只在真正重要的节点上触发。另外不要把业务逻辑写进规则。规则是给 AI 看的工作方式不是业务知识库。业务知识应该放在项目的 README 或者专门的文档里让 AI 按需读取。规则文件保持精简最好控制在一屏能看完的长度这样你自己也愿意经常维护它。2.3 规则的载体放在哪里最合适CodeBuddy 读取规则的机制通常是扫描项目根目录下的特定配置文件。不同版本可能略有差异但思路是一样的把规则放在项目根目录用纯文本或 Markdown 格式文件名固定。我习惯用CODEBUDDY.md或者.codebuddy/rules.md这种命名一眼就能看出是干什么的。为什么不放在全局配置里因为规则是跟项目走的。A 项目用 ReactB 项目用 Vue全局规则没法同时满足。放在项目根目录跟着 Git 走团队里每个人拉下来就自动生效新人也不用额外配置。这一点在多人协作时特别重要——规则文件本身就是最好的项目约定文档。提示如果你的项目有多个子包monorepo可以在每个子包目录下各放一份规则文件根目录放一份通用的。CodeBuddy 一般会就近读取子包规则覆盖根规则。3. 我的规则条款逐条拆解3.1 代码风格条款让输出直接能过 lint风格条款是规则里最基础的部分目标只有一个AI 生成的代码不用手动格式化就能过项目的 lint 检查。我以 JavaScript/TypeScript 项目为例列几条我实际在用的缩进统一用 2 个空格不用 Tab字符串统一用单引号模板字符串除外语句末尾不加分号这个看团队我们团队不加函数参数超过 3 个时必须用对象解构注释用中文只在为什么这么做的地方写不写做了什么这几条看起来琐碎但效果立竿见影。以前 AI 生成的代码我要先跑一遍 Prettier再手动改几个命名现在基本是复制粘贴就能用。关键是把 lint 规则和 AI 规则对齐——你项目里 ESLint 怎么配的规则文件里就怎么写两边一致AI 就不会生成能跑但过不了检查的代码。这里有个细节值得说注释语言这条特别重要。CodeBuddy 默认用英文注释但如果你团队里都是中文交流英文注释反而增加阅读成本。我在规则里明确写了注释用中文变量名和函数名用英文这样既保证了代码的可读性又照顾了团队习惯。这条规则写进去之后AI 生成的注释质量明显提升因为它知道要写给人看而不是写给编译器看。3.2 目录与文件结构条款新代码该放哪结构条款解决的是AI 把文件放错地方的问题。默认情况下AI 生成新文件时倾向于放在根目录或者它觉得合理的地方但每个项目都有自己的目录约定。我的规则里会明确写新组件放src/components/按功能分子目录工具函数放src/utils/一个文件一个功能类型定义放src/types/按模块拆分测试文件与被测文件同目录命名加.test.后缀这几条写进去之后AI 生成的文件位置基本不用调整。更重要的是它会在生成代码时自动 import 正确的路径省掉了手动改 import 的麻烦。我试过不写这几条结果 AI 把组件生成在根目录import 路径全是错的改起来比重新写还费劲。结构条款还有一个隐藏价值它让 AI 理解项目的模块边界。当你告诉它工具函数放 utils组件放 components它在生成代码时会自动判断这段逻辑属于哪一类从而选择更合适的实现方式。这比单纯告诉它写个函数要精准得多。3.3 依赖与技术选型条款哪些库碰不得依赖条款是我认为性价比最高的一类规则。AI 默认喜欢用最流行、最省事的库但你的项目可能因为包体积、历史兼容、团队熟悉度等原因明确不用某些库。把这些写进规则能避免大量返工。我的规则里会分两栏写允许用的和禁止用的。允许用的部分我会写清楚优先用哪个。比如日期处理优先用dayjs不用moment状态管理用项目已有的zustand不引入 ReduxHTTP 请求统一用封装好的request工具不直接用fetch禁止用的部分我会写清楚为什么禁。比如禁止引入lodash用原生数组方法替代包体积考虑禁止用any类型实在不确定用unknown加类型守卫禁止在组件里直接写console.log用项目的 logger写为什么禁这一点很关键。AI 理解了原因在遇到边界情况时能做出更合理的判断。比如你告诉它禁 lodash 是因为包体积它在遇到一个 lodash 能一行解决的问题时会倾向于用原生方法多写几行而不是偷偷引入。规则不只是命令也是上下文。3.4 提交与协作条款让 AI 的输出符合团队流程如果你的项目用 Git 管理提交信息规范也值得写进规则。AI 生成提交信息时默认是英文的、比较随意的但很多团队有 Conventional Commits 之类的规范。我的规则里会写提交信息格式type(scope): 描述描述用中文type 只能是 feat/fix/docs/style/refactor/test/chore每次提交只做一件事不混合多个改动这条规则的效果在 code review 时特别明显。以前 AI 生成的提交信息是 update code现在会自动写成 feat(user): 新增用户头像上传功能review 的人一眼就知道改了什么。协作条款里还有一条我强烈建议加上生成代码时必须同时生成对应的单元测试。AI 写测试的能力其实不错但默认不会主动写。你在规则里明确要求每个新函数必须附带测试用例它就会养成习惯。我现在的项目里AI 生成的代码测试覆盖率比我自己写的还高因为它是真的会为每个分支写 case。4. 规则怎么落地从写下来到用起来4.1 规则的初始化第一次怎么配第一次配规则不要想着一步到位。我的做法是先写 5 条最痛的用一周再补。具体步骤在项目根目录新建规则文件写 3-5 条你最在意的条款正常用 CodeBuddy 干活观察它哪些地方还是不符合预期每发现一个反复出现的问题就往规则里加一条一周后回顾一遍删掉那些写了但从来没触发过的条款这个迭代过程很重要。规则不是写给别人看的文档是给自己用的工具。只有真正触发过的条款才有价值没触发过的要么是写得太虚要么是 AI 本来就做对了。我第一版规则只有 4 条注释用中文、缩进 2 空格、不用 lodash、新文件放对目录。用了两周之后加到 12 条再后来稳定在 15 条左右。这个数量我觉得刚好一屏能看完维护起来不累。4.2 规则的验证怎么知道它生效了写完规则怎么验证 AI 真的读了我的方法是故意制造一个规则能拦截的场景。比如规则里写了不用 lodash我就让它写一个数组去重的函数看它是用原生Set还是偷偷 import lodash。如果它用了原生方法说明规则生效了如果还是 import 了 lodash说明规则没被读到或者写得不够明确。还有一种验证方式是看它主动引用规则。好的规则会让 AI 在生成代码时主动说明根据项目规则这里用了 X 而不是 Y。如果你发现它开始这样解释自己的选择说明规则已经进入它的决策流程了。注意不同版本的 CodeBuddy 对规则文件的读取时机可能不同。有的在会话开始时读一次有的每次生成都读。如果你改了规则但没生效试试重启会话或者重新加载项目。4.3 规则的维护什么时候该改规则不是写完就不管的。我一般在这几种情况下会更新规则同一个问题被 AI 犯了三次以上说明规则里没写或者写得不清楚项目技术栈变了比如从 Vue2 升到 Vue3相关条款要跟着改团队来了新人新人常犯的错往往也是 AI 常犯的错值得写进规则规则条款超过 20 条该合并的合并该删的删保持精简维护规则的成本很低但收益是持续的。我现在的习惯是每次 code review 发现 AI 生成的代码有问题先想一下这个问题能不能用规则避免能的话就顺手加一条。这样规则会随着项目一起成长越来越贴合实际需求。5. 我踩过的几个典型坑5.1 规则写太细AI 变得死板早期我在规则里写了函数不超过 30 行结果 AI 为了满足这条把一个逻辑完整的函数硬拆成三个小函数可读性反而下降了。后来我把这条改成函数尽量不超过 50 行超过时优先考虑拆分但不要为了拆而拆。规则要留出判断空间不能太机械。类似的还有每个函数必须有注释。这条写进去之后AI 给每个 getter/setter 都加了注释全是废话。后来改成只在逻辑复杂或有不明显意图的地方写注释输出质量立刻上来了。5.2 规则之间互相冲突有一次我同时写了优先用函数式写法和避免过度使用链式调用结果 AI 在遇到数组操作时左右为难生成了一段又像函数式又像命令式的四不像代码。规则之间要自查一致性写完通读一遍看看有没有互相矛盾的条款。冲突的根源往往是规则写得太绝对。把优先用 X改成在 Y 场景下用 X在 Z 场景下用 W冲突就消失了。规则的本质是决策指南不是非黑即白的命令。5.3 忘了规则是给这个项目写的我犯过一个错把一个项目的规则直接复制到另一个项目结果新项目用的是不同的框架规则里的目录结构、依赖条款全都不适用AI 被误导得很惨。规则必须跟项目绑定换项目就要重新审视一遍该改的改该删的删。现在我每个项目的规则文件都是独立维护的虽然有些通用条款会重复但我不介意这种重复。因为每个项目的规则都是为那个项目量身定做的复制粘贴反而容易出问题。5.4 规则文件本身没人维护最隐蔽的坑是规则文件写完之后就忘了项目都重构两轮了规则还停留在一年前。AI 读着过时的规则生成着不符合当前项目的代码你还以为是 AI 变笨了。把规则文件纳入 code review 范围每次大改动时顺手看一眼规则要不要更新这个习惯能省掉很多困惑。我现在的做法是在项目的 CONTRIBUTING 文档里加一条修改技术栈或目录结构时同步更新 CodeBuddy 规则文件。这样团队里每个人都知道规则是需要维护的不会让它烂掉。6. 一套可以直接抄的规则模板说了这么多最后给一份我实际在用的模板以 TypeScript React 项目为例。你可以直接复制到项目根目录的规则文件里按自己的情况改。# 项目 CodeBuddy 规则 ## 代码风格 - 缩进 2 空格字符串用单引号语句末尾不加分号 - 注释用中文只在逻辑复杂处写不写废话注释 - 函数参数超过 3 个时用对象解构 - 禁止使用 any不确定用 unknown 加类型守卫 ## 目录结构 - 组件放 src/components/按功能分子目录 - 工具函数放 src/utils/一个文件一个功能 - 类型定义放 src/types/按模块拆分 - 测试文件与被测文件同目录后缀 .test.ts ## 依赖约束 - 日期处理用 dayjs不用 moment - 状态管理用 zustand不引入 Redux - 禁止引入 lodash用原生方法替代 - HTTP 请求用封装的 request 工具不直接用 fetch ## 提交流程 - 提交信息格式type(scope): 中文描述 - type 限 feat/fix/docs/style/refactor/test/chore - 每个新函数必须附带单元测试 - 涉及 schema 变更时先输出方案再动手这份模板大概 15 条一屏能看完。我建议你先用这份跑一周然后根据自己的项目往里加条款。记住那个原则只写 AI 会做错、你又在意的事。其他的交给 AI 自己判断就好。规则这东西说到底是你和 AI 之间的工作默契。写得越清楚它就越像你团队里那个靠谱的同事而不是一个需要反复纠正的实习生。我在实际使用中最大的体会是花在写规则上的每一分钟都会在后续的每一次生成里省回来。刚开始可能觉得麻烦用顺了之后你会发现自己已经很久没有手动改过 AI 生成的代码格式了。