1. 为什么我要给 CodeBuddy 定一套自己的规则用了大半年 CodeBuddy从最开始把它当成一个“高级点的代码补全”来用到后来慢慢发现这东西真正的价值不在于它单次能写多少行代码而在于你能不能把它调教成一个懂你项目、懂你习惯、懂你技术栈的“结对搭档”。我见过太多人抱怨 AI 编程助手“不好用”“生成的代码跑不起来”“老是改坏我的文件”但仔细一问他们基本都是打开对话框直接甩一句“帮我写个登录功能”然后指望它一次性给出完美答案。这种用法换谁来都救不了。CodeBuddy 这类工具的核心能力是基于上下文的代码生成与修改它需要你提供足够清晰的约束条件才能输出符合预期的结果。而“规则”就是你和它之间的一份契约——你告诉它这个项目用什么框架、什么代码风格、什么目录结构、哪些文件不能碰、哪些操作必须先确认它才能在你的边界内干活。没有规则它就像一个刚入职的新人技术能力不差但对你的项目一无所知每次都要从头解释效率极低。我写这套规则的过程其实挺折腾的。最开始只是随手在对话里加一句“用 TypeScript”后来发现每次都要重复说就开始把常用约束整理成一个文档每次开新会话时先发给它。再后来 CodeBuddy 支持了项目级配置文件我就把这些规则固化下来变成了现在这套东西。实测下来有了这套规则之后代码生成的一次通过率大概从原来的三四成提升到了七八成返工次数明显减少尤其是涉及多文件修改的场景它基本能按照我预期的路径去操作不会到处乱改。这套规则适合谁如果你已经在用 CodeBuddy 或者类似的 AI 编程助手但总觉得“差那么点意思”那这套思路可以直接抄。如果你还没开始用那更好从一开始就养成定规则的习惯后面会省很多事。不管你写的是前端、后端、脚本还是全栈项目规则的核心逻辑是通用的只是具体内容要根据你的技术栈来调整。2. 我的 CodeBuddy 规则全貌与设计思路2.1 规则文件放在哪、叫什么名字CodeBuddy 支持在项目根目录放置规则文件我一般会建一个.codebuddy目录里面放几个不同用途的文件。这样做的好处是规则和项目代码在一起换电脑、换协作者都能直接带走不依赖本地配置。具体结构是这样的.codebuddy/ ├── rules.md # 核心规则每次会话必读 ├── style.md # 代码风格细则 ├── forbidden.md # 禁止操作清单 └── context.md # 项目背景与技术栈说明为什么拆成四个文件而不是全塞一个因为不同规则的更新频率不一样。rules.md基本不动style.md偶尔调整forbidden.md会根据踩坑经验不断增加context.md在项目架构变化时需要更新。拆开之后维护起来清晰CodeBuddy 读取时也能按优先级处理。实测发现如果把所有内容混在一起超过一定长度它对后面部分的关注度会下降拆分后每个文件都短小精悍执行效果更好。2.2 核心规则的设计逻辑rules.md是我这套体系的骨架它定义了 CodeBuddy 在我项目里的“行为准则”。我写这份规则的时候核心思路是三条先理解再动手、改动最小化、不确定就问。这三条听起来简单但真正落到文字上需要非常具体否则 AI 会用自己的方式理解结果往往不是你想要的。比如“先理解再动手”这条我具体写成在修改任何文件之前必须先读取该文件及其直接依赖确认理解了现有逻辑后再提出修改方案方案需要说明改什么、为什么改、影响范围是什么。这样写的好处是它不会上来就改代码而是先给你一个方案让你确认。我踩过的坑是早期没写这条它直接改了一个工具函数结果那个函数被十几个地方引用改完之后类型全对不上排查了半天。“改动最小化”这条也很关键。AI 有个通病就是喜欢“顺手优化”——你让它改个按钮样式它可能把整个组件的结构都重构了。所以我在规则里明确写了只改与当前任务直接相关的代码不主动重构、不主动优化、不主动删除看似无用的代码如果发现潜在问题在回复中单独指出但不擅自修改。这条规则帮我避免了很多“改一个 bug 引入三个新 bug”的情况。“不确定就问”这条是兜底。规则里写的是当需求描述存在歧义、当涉及多个可选方案、当需要修改配置文件或依赖版本时必须先向用户确认不得自行决定。这条规则让 CodeBuddy 从一个“自作主张的实习生”变成了“会请示的下属”用起来放心很多。2.3 技术栈上下文的写法context.md这个文件我觉得是被很多人忽略的。大家通常只告诉 AI“用什么语言”但不说“项目怎么组织的”。实际上后者对生成代码的质量影响更大。我的context.md大概长这样## 项目类型 Next.js 14 App Router 项目TypeScript 严格模式 ## 目录结构 - app/ 页面与路由 - components/ 通用组件每个组件一个目录 - lib/ 工具函数与第三方封装 - hooks/ 自定义 hooks - types/ 全局类型定义 ## 状态管理 Zustandstore 放在 lib/store/ 下 ## 样式方案 Tailwind CSS CSS Modules复杂组件用 ## 数据请求 SWR统一封装在 lib/fetcher.ts ## 命名约定 - 组件文件PascalCase.tsx - 工具函数camelCase.ts - 类型文件kebab-case.types.ts这份上下文看起来平平无奇但它让 CodeBuddy 生成的代码“像是我自己写的”。比如它知道组件要放在components/下且每个组件一个目录就不会把新组件随手扔在app/里它知道数据请求统一走lib/fetcher.ts就不会在组件里直接写fetch。这些细节单看很小但累积起来就是“能用”和“好用”的差距。2.4 禁止操作清单的积累forbidden.md是我踩坑踩出来的。每遇到一次 CodeBuddy 做了我不希望它做的事我就往这个文件里加一条。目前积累下来的主要有这些禁止修改package.json中的依赖版本需要新增依赖时先告知禁止修改.env系列文件禁止删除任何文件需要删除时先列出并确认禁止修改lib/fetcher.ts和lib/store/下的核心逻辑除非任务明确要求禁止在组件中直接使用any类型禁止提交代码它没有提交权限但有时会建议你执行 git 命令需要过滤这份清单的价值在于它把“隐性知识”变成了“显性规则”。你脑子里知道“这个文件不能动”但 AI 不知道写下来它就知道了。而且这份清单是可以复用的换项目时把项目特有的部分调整一下通用部分直接带走。3. 规则的具体内容与逐条解析3.1 对话开场规则让每次会话都有上下文我要求 CodeBuddy 在每次新会话开始时先做三件事读取.codebuddy/下的所有规则文件、读取当前打开文件及其直接依赖、用一句话复述它理解的任务目标。这三步看起来繁琐但实际执行下来也就多花几秒钟换来的是后续对话效率的大幅提升。具体规则文本是这样的## 会话初始化 1. 读取 .codebuddy/ 目录下所有 .md 文件 2. 读取当前活动文件及其 import 的直接依赖文件 3. 用一句话总结你理解的任务目标等待用户确认后再开始为什么要让它复述任务目标因为很多时候你以为自己说清楚了但它理解的是另一个意思。让它复述一遍你一眼就能看出偏差及时纠正避免它按错误理解写了一大堆代码你才发现不对。我统计过加了这一步之后因为“理解偏差”导致的返工减少了大概六成。3.2 代码生成规则约束越具体结果越可控代码生成是 CodeBuddy 最常用的功能也是规则最能发挥作用的地方。我的生成规则主要围绕几个维度类型安全、错误处理、命名规范、注释要求。类型安全方面我明确要求所有函数必须有明确的参数类型和返回类型禁止使用any不确定的类型用unknown并配合类型守卫。这条规则配合 TypeScript 严格模式基本杜绝了类型相关的运行时错误。实测下来它生成的代码在类型层面几乎不需要我再手动调整。错误处理方面规则要求所有可能失败的操作网络请求、文件读写、JSON 解析必须有 try-catch 或错误边界处理错误信息要包含足够的上下文便于排查。这条规则让生成的代码更健壮不会出现“请求失败了但页面白屏没有任何提示”的情况。命名规范方面我直接把项目的命名约定写进规则包括变量用 camelCase、常量用 UPPER_SNAKE_CASE、类型用 PascalCase、布尔值以 is/has/can 开头、事件处理函数以 handle 开头等。这些约定写清楚之后生成的代码风格就统一了不会出现同一个文件里几种命名风格混用的情况。注释要求方面我的规则是导出的函数和组件必须有 JSDoc 注释说明用途、参数和返回值复杂逻辑内部要有行内注释解释“为什么”而不是“是什么”。这条规则让代码的可维护性提升明显尤其是过几个月回头看自己和 AI写的代码时注释能帮你快速回忆起来。3.3 文件操作规则防止“手滑”改坏项目文件操作是 AI 编程助手最容易出问题的地方。我见过不少案例AI 为了“修复”一个问题把整个文件重写了结果丢了很多原有逻辑。所以我在规则里对文件操作做了严格约束## 文件操作规范 - 修改文件前必须先读取完整文件内容 - 使用精确的字符串替换禁止整文件重写 - 每次修改后说明改了哪几处、每处改了什么 - 涉及三个以上文件的修改先列出文件清单和修改要点确认后再执行 - 禁止创建新文件除非任务明确要求且已确认路径和命名“使用精确的字符串替换”这条特别重要。早期我没写这条的时候CodeBuddy 有时会“重写”整个文件虽然大部分内容一样但格式、空行、注释位置可能变了导致 git diff 一片红review 起来很痛苦。改成精确替换之后diff 干净多了每次改动一目了然。“涉及三个以上文件先确认”这条也帮我省了不少事。多文件修改往往涉及架构层面的调整AI 的方案不一定符合你的预期先看清单再执行避免改到一半发现方向不对。3.4 沟通风格规则让协作更顺畅沟通风格这块我的要求是直接、具体、不废话。具体规则包括回复用中文代码和专有名词保持英文不要用“好的”“没问题”“当然可以”等客套话开头解释方案时先说结论再说理由遇到不确定的地方直接说“不确定”不要编造每次回复末尾列出“下一步建议”但不要自动执行“先说结论再说理由”这条是我个人偏好因为我不喜欢看一大段铺垫才等到重点。AI 默认的风格往往是先解释背景再给方案我把它调整成结论先行阅读效率高很多。“不确定就说不知道”这条也很关键。AI 有时候会“幻觉”编造一些不存在的 API 或配置项。明确告诉它不确定就说不确定能减少很多误导。实测下来加了这条之后它编造内容的概率明显下降遇到不确定的地方会主动说“这个我不确定建议你查一下官方文档”。4. 实操从零搭建你的 CodeBuddy 规则体系4.1 第一步梳理你的项目上下文在写规则之前先花十分钟把你的项目情况理清楚。我一般会问自己几个问题这个项目用什么语言和框架目录结构是怎样的有哪些核心模块和工具函数代码风格有什么特殊约定哪些文件是“禁区”把这些问题的答案写下来就是context.md的雏形。不用写得很正式大白话就行关键是信息准确。比如“这个项目用 Next.js页面在 app 目录下组件在 components 目录下每个组件一个文件夹里面有 index.tsx 和 styles.module.css”这样写完全没问题CodeBuddy 能理解。4.2 第二步从最小可用规则开始不要一上来就写几十条规则那样维护成本高而且很多规则可能用不上。我的建议是从最小可用集开始先写这几条## 基础规则 1. 修改文件前先读取文件内容 2. 使用精确替换不重写整个文件 3. 所有函数标注参数和返回类型 4. 不确定的地方先问不要自行决定 5. 回复用中文代码用英文这五条覆盖了最核心的约束先跑一段时间遇到问题再往里面加。我自己的规则体系也是从五六条慢慢长到现在的规模的每一条都是实际踩坑之后加的所以每条都有存在的理由。4.3 第三步根据踩坑经验持续迭代规则不是写完就完了要持续迭代。我的做法是每次 CodeBuddy 做了我不希望它做的事就在forbidden.md里加一条每次发现它某个方面做得不够好就在rules.md里补充约束。举个例子有一次它在我没要求的情况下把console.log都删了说是“清理调试代码”。但那些 log 是我特意留的用于线上排查问题。于是我加了一条规则禁止删除 console.log除非任务明确要求。还有一次它把某个函数的参数顺序调整了说是“更符合直觉”但那个函数被多处调用改完之后全报错。于是我加了规则禁止修改现有函数的签名需要调整时先列出所有调用点。这种“踩坑-记录-迭代”的循环大概持续了两个月规则体系就基本稳定了。现在偶尔还会加新条目但频率已经很低了。4.4 第四步验证规则是否生效规则写完之后怎么验证有没有用我的方法是做几个测试任务观察 CodeBuddy 的行为是否符合预期。比如让它修改一个被多处引用的工具函数看它是否会先读取依赖、是否会提示影响范围让它新增一个组件看它是否放在正确的目录、是否遵循命名规范让它处理一个模糊需求看它是否会主动询问而不是自行猜测如果这些测试都通过了说明规则基本生效。如果有不符合预期的地方就针对性地补充或调整规则。我一般会在规则大改之后跑一遍这些测试确保没有引入新的问题。5. 常见问题与排查技巧实录5.1 规则不生效怎么办最常见的问题是规则写了但 CodeBuddy 好像没看到。排查思路是这样的首先确认规则文件路径是否正确.codebuddy/目录必须在项目根目录下其次确认文件格式必须是.md文件编码用 UTF-8然后确认规则内容是否太长如果单个文件超过一定长度后面的内容可能被截断建议拆分最后确认是否在会话开始时明确要求它读取规则有时候需要手动触发一下。如果以上都没问题但还是不生效可能是规则表述有歧义。AI 对模糊表述的理解可能和你想的不一样。比如“不要改太多”这种表述就很模糊改成“每次修改不超过 20 行”就具体多了。规则越具体执行越准确。5.2 规则冲突怎么处理当多条规则可能冲突时需要定义优先级。我的做法是在rules.md开头写一段优先级说明## 规则优先级 1. 用户当前指令 所有规则 2. forbidden.md rules.md style.md 3. 安全相关规则 效率相关规则这样当规则冲突时CodeBuddy 知道该听谁的。比如style.md说“函数不超过 50 行”但forbidden.md说“禁止拆分现有函数”那它就应该保持函数原样而不是为了满足行数限制去拆分。5.3 规则太多导致响应变慢规则条目太多确实会影响响应速度因为 CodeBuddy 每次都要读取和处理这些规则。我的经验是核心规则控制在 20 条以内细则可以放在单独文件里按需读取。另外定期清理过时规则也很重要有些规则是特定时期的产物项目变化后就不再适用了及时删掉能减轻负担。5.4 常见问题速查表问题现象可能原因解决方法规则完全不生效文件路径错误或格式不对确认.codebuddy/在根目录文件为 UTF-8 编码的 .md部分规则不执行规则表述模糊或有冲突具体化表述明确优先级响应明显变慢规则文件过长拆分文件核心规则精简到 20 条以内生成的代码风格不一致style.md 不够具体补充命名、格式、注释的具体要求擅自修改禁区文件forbidden.md 未覆盖把该文件加入禁止清单说明原因不理解项目结构context.md 缺失或过时更新目录结构和技术栈说明5.5 几个我踩过的坑第一个坑是规则写得太“人性化”。比如我写过“尽量保持代码简洁”结果它理解成“可以删掉它认为不简洁的代码”把我的一些防御性检查删了。后来改成“不主动删除任何代码除非任务明确要求”问题就解决了。规则要写成可执行的指令而不是模糊的期望。第二个坑是忘了更新规则。项目从 Pages Router 迁移到 App Router 之后我忘了更新context.md结果 CodeBuddy 还在按旧结构生成代码放在pages/目录下。这种问题不容易发现因为生成的代码本身没错只是位置不对。定期 review 规则文件确保和项目现状一致这个习惯很重要。第三个坑是规则文件被提交到了 git。.codebuddy/目录里有些内容是个性化的比如我自己的沟通风格偏好这些不适合团队共享。后来我把.codebuddy/加进了.gitignore只把通用的部分抽出来放在团队共享的文档里。个人规则和团队规则分开管理避免互相干扰。6. 规则体系的扩展与团队协作6.1 个人规则与团队规则的分离一个人用和团队用规则体系的设计思路不一样。个人用可以很随意怎么顺手怎么来团队用则需要考虑一致性和可维护性。我的做法是分两层个人层放在.codebuddy/里不提交到 git团队层放在项目文档里比如docs/ai-coding-guidelines.md提交到 git 供所有人参考。团队层的规则主要覆盖技术栈约定、目录结构、命名规范、代码审查要点。这些是所有人都需要遵守的。个人层则包含沟通风格偏好、个人快捷键习惯、特定任务的临时约束等。两层分开之后既保证了团队一致性又保留了个性化空间。6.2 规则模板的复用换项目的时候规则体系不需要从零开始。我把通用部分抽成了一个模板新项目直接复制过去改一下项目特有的部分就行。模板大概长这样## 通用规则模板 1. 修改前先读取文件 2. 精确替换不重写 3. 类型完整不用 any 4. 不确定先问 5. 中文回复英文代码 6. 禁止修改依赖版本 7. 禁止删除文件 8. 禁止提交代码这八条基本适用于所有项目新项目直接拿来用再根据项目特点补充技术栈相关的规则。这样起步快不用每次都想“该写哪些规则”。6.3 规则体系的长期维护规则体系不是一劳永逸的需要长期维护。我的维护节奏是每周花五分钟回顾一下这周有没有遇到规则没覆盖到的情况有就加一条每月花半小时整体 review 一遍删掉过时的、合并重复的、调整表述不清的项目大版本升级时同步更新context.md和相关的技术栈规则。这个维护成本其实很低但收益很明显。规则体系越用越顺手CodeBuddy 越来越懂你的项目协作效率持续提升。反过来如果放任不管规则会逐渐和项目脱节最后变成摆设。6.4 一个实际案例从混乱到有序最后分享一个我印象比较深的案例。有个老项目代码风格混乱有的文件用分号有的不用有的用双引号有的用单引号组件有的用函数式有的用类式。我接手之后先花了一天时间梳理现状写了一份context.md和style.md明确新代码统一用函数式组件、单引号、不加分号、2 空格缩进。然后把规则文件放进项目开始用 CodeBuddy 写新功能。刚开始几天它生成的代码偶尔还会“随大流”用旧风格因为它在读取文件时看到了旧代码的写法。我在规则里补充了一条新代码一律遵循 style.md不受现有文件风格影响。加了这条之后新生成的代码风格就统一了。三个月后新代码占比超过一半整个项目的风格逐渐收敛。这个过程让我意识到规则不仅能约束 AI也能间接推动项目本身的规范化。这套规则体系我用了大半年中间调整过很多次现在基本稳定了。如果你也在用 CodeBuddy 或者类似的工具建议花点时间把自己的规则整理出来前期投入一两个小时后面能省几十个小时的返工时间。规则不用一次写完美先跑起来遇到问题再补慢慢就成型了。