给CodeBuddy定规矩：AI编程助手规则体系实战指南

1. 为什么我要给 CodeBuddy 定一套自己的规则用了大半年 CodeBuddy从最开始把它当个高级补全工具到后来让它深度参与整个项目的开发流程中间踩过的坑真不少。最典型的一次是它给我生成了一段看起来没问题的数据库查询代码结果上线后才发现没有处理连接池耗尽的情况半夜被叫起来排查问题。从那以后我就意识到想让 AI 编程助手真正成为生产力工具光靠它默认的行为模式远远不够你得给它立规矩。这套规则不是官方文档里抄来的是我在实际项目中反复调整、验证、推翻再重建的结果。它解决的核心问题是让 CodeBuddy 的输出从“看起来能用”变成“直接能用”。如果你也在用 CodeBuddy 或者类似的 AI 编程助手不管你是刚上手的新手还是已经用了一段时间的老手这套规则都能帮你省下大量返工和调试的时间。先说清楚这套规则不是让你去改 CodeBuddy 的底层配置而是在使用过程中通过提示词、项目结构、工作流设计来约束它的行为。你可以把它理解成给一个能力很强但不太懂你项目习惯的新同事写的一份详细入职指南。规则的核心围绕三个维度展开代码风格一致性、错误处理完备性、架构决策合理性。下面我会逐条拆解每个规则背后的逻辑、具体怎么落地、以及我踩过哪些坑。2. 规则体系的核心设计思路2.1 从“对话式编程”到“契约式编程”的转变刚开始用 CodeBuddy 的时候我的交互方式很随意想到什么问什么它给什么我就看什么。这种方式在写小脚本或者做原型验证时还行但一旦进入正式项目问题就暴露了。最明显的是代码风格飘忽不定同一个文件里它给我生成的函数有时候用驼峰命名有时候用下划线错误处理有的地方用 try-catch有的地方直接抛出去不管。后来我换了个思路把每次和 CodeBuddy 的交互都当成一次“契约签订”。什么意思呢就是在让它写代码之前我先明确告诉它这个项目的技术栈、代码规范、错误处理策略、日志格式等约束条件。这些约束不是一次性说完就完了而是要在每个关键节点反复强调。比如我会在项目根目录放一个.codebuddy-rules文件里面写清楚这个项目的所有约定每次开始新会话时先让它读这个文件。这个转变带来的效果非常明显。以前它生成的代码我平均要改 30% 左右才能用现在基本上改个 5% 到 10% 就能直接提交。更重要的是代码审查的时候同事不会再问“这里为什么用这种写法”这种问题了因为风格是统一的。2.2 三条核心规则的设计逻辑我最终沉淀下来的规则体系围绕三条核心原则展开每条原则下面有具体的执行细则。第一条显式优于隐式。CodeBuddy 很擅长“猜”你的意图但猜对了是惊喜猜错了就是事故。所以我要求它在任何有歧义的地方必须显式声明。比如类型定义必须写全不能依赖类型推断函数参数必须有默认值或者明确的必填标记配置项必须写清楚默认行为和可选值范围。这条规则的本质是降低代码的“隐含知识”含量让任何人拿到代码都能看懂。第二条错误处理必须完整。这是我最看重的一条。AI 生成的代码有个通病就是只关注“正常路径”对异常情况的处理非常敷衍。我要求 CodeBuddy 在生成任何涉及 I/O、网络请求、数据库操作、文件读写的代码时必须同时给出完整的错误处理方案包括错误分类、重试策略、降级方案、日志记录。这条规则直接来自我前面提到的那个半夜排查问题的教训。第三条架构决策必须有据可查。当 CodeBuddy 建议使用某个设计模式或者引入某个依赖时它必须给出理由并且说明替代方案是什么、为什么不选替代方案。这条规则是为了防止“过度设计”和“盲目引入依赖”两个极端。我见过太多项目因为 AI 建议引入了一个重型框架结果 90% 的功能用不上还增加了维护成本。2.3 规则落地的载体设计光有原则不够得有具体的落地方式。我用了三个载体来承载这些规则。第一个是项目根目录的规则文件。这个文件用 Markdown 格式写内容包括项目概述、技术栈版本、代码风格约定、错误处理模板、日志规范、测试要求等。每次和 CodeBuddy 开始一个新的功能开发会话时第一句话就是让它先读这个文件。第二个是代码模板库。我把项目中常用的代码结构抽象成模板比如 API 路由模板、数据库操作模板、中间件模板、单元测试模板等。当 CodeBuddy 需要生成类似代码时我直接让它参考模板库中的对应文件而不是从零生成。这样既保证了风格统一又减少了它“自由发挥”的空间。第三个是检查清单。在让 CodeBuddy 完成一个功能模块后我会用一份检查清单来验收它的输出。清单内容包括是否有未处理的异常、是否有硬编码的配置、是否有未使用的导入、是否有类型不安全的操作、是否有性能隐患等。这份清单我整理成了一个 Markdown 文件每次验收时逐条核对。3. 代码风格一致性规则详解3.1 命名规范的强制约束命名这件事看起来小但在多人协作的项目里命名不一致带来的沟通成本非常高。我要求 CodeBuddy 严格遵守以下命名规则并且在生成代码后自动检查是否符合。变量和函数名使用小驼峰命名法比如getUserInfo、orderList。类和接口使用大驼峰命名法比如UserService、OrderRepository。常量使用全大写下划线分隔比如MAX_RETRY_COUNT、DEFAULT_TIMEOUT_MS。私有成员变量使用下划线前缀比如_cache、_connectionPool。这里有个细节值得展开说。CodeBuddy 有时候会生成一些“语义模糊”的命名比如data、info、temp、result这种。我要求它在命名时必须包含“业务语义”和“数据类型”两个维度。比如不要叫data要叫userProfileData不要叫result要叫queryResult或者validationResult。这条规则执行下来代码的可读性提升非常明显。还有一个容易被忽略的点是布尔变量的命名。我要求布尔变量必须以is、has、can、should开头比如isValid、hasPermission、canRetry、shouldNotify。这样在条件判断语句里读起来非常自然if (isValid)比if (valid)清晰得多。3.2 代码格式的自动化约束格式问题不应该靠人肉检查我直接用工具链来约束。项目里配置了 Prettier 和 ESLint并且把配置文件也放进了规则文件里让 CodeBuddy 读取。具体配置包括缩进用 2 个空格、行尾用分号、字符串用单引号、对象属性最后一项加逗号、每行最大长度 100 字符。但光有配置不够我要求 CodeBuddy 在生成代码后主动运行格式化命令并且在输出中说明它执行了哪些格式化操作。这样我一眼就能看出它有没有遵守格式规则。如果它生成的代码格式不对我会直接让它重新生成而不是手动去改。几次之后它就记住了。这里有个实操心得把格式检查集成到 Git 的 pre-commit hook 里。每次提交前自动运行格式检查和修复这样即使 CodeBuddy 偶尔“忘记”了格式规则提交的代码也是格式统一的。这个 hook 脚本我也是让 CodeBuddy 帮我写的写完让它自己测试通过才用。3.3 注释和文档的生成规则注释这件事上我的规则是“解释为什么而不是解释是什么”。CodeBuddy 默认生成的注释经常是“获取用户信息”这种废话函数名已经说明了一切。我要求它只在以下三种情况下写注释第一代码逻辑有非直观的边界条件处理第二代码实现依赖于外部系统的特殊行为第三代码有性能优化相关的取舍。对于公开的 API 和工具函数我要求必须写完整的 JSDoc 注释包括参数类型、返回值类型、可能抛出的异常、使用示例。这个要求我写进了规则文件并且给了一个模板。CodeBuddy 按照模板生成质量很稳定。还有一个技巧是让 CodeBuddy 在生成复杂函数时先在注释里用自然语言描述实现步骤然后再写代码。这样我可以在它写代码之前就检查逻辑对不对避免写完一大段再返工。这个“先注释后代码”的方式我强烈推荐尤其是在实现算法或者复杂业务逻辑的时候。4. 错误处理完备性规则详解4.1 错误分类与处理策略错误处理是我规则体系里最核心的部分。我要求 CodeBuddy 把所有错误分成四类每类有不同的处理策略。第一类是用户输入错误比如表单验证失败、参数格式不对。这类错误的处理策略是立即返回明确的错误信息给用户不需要记录错误日志或者只记录 debug 级别不需要重试。第二类是系统错误比如数据库连接失败、网络超时、文件不存在。这类错误的处理策略是根据配置的重试策略进行重试重试失败后记录 error 级别日志返回友好的错误提示给用户同时触发告警。第三类是编程错误比如空指针引用、数组越界、类型转换失败。这类错误的处理策略是记录 fatal 级别日志包含完整的堆栈信息立即中断当前操作返回通用错误提示不暴露内部细节触发告警。第四类是外部服务错误比如第三方 API 返回异常、消息队列不可用。这类错误的处理策略是根据服务的重要程度决定是降级还是重试记录 warn 或 error 级别日志监控外部服务的可用性指标。我让 CodeBuddy 在生成任何可能出错的代码时先判断错误属于哪一类然后按照对应的策略处理。这个分类框架我写进了规则文件并且配了具体的代码示例。4.2 重试机制的具体实现重试不是简单地“再试一次”里面有很讲究。我要求 CodeBuddy 实现重试时必须考虑以下参数最大重试次数、重试间隔、退避策略、超时时间、幂等性保证。最大重试次数我一般设置为 3 次。为什么是 3 次因为根据经验大部分临时性故障在 3 次重试内都能恢复超过 3 次还失败的基本上是持久性故障再重试也是浪费资源。重试间隔我要求使用指数退避策略第一次间隔 1 秒第二次 2 秒第三次 4 秒。这样可以避免在系统繁忙时大量重试请求同时涌入造成雪崩效应。超时时间我要求每个操作都必须设置不能使用无限等待。具体超时时间根据操作类型来定数据库查询 5 秒外部 API 调用 10 秒文件操作 30 秒。这些数值我写进了规则文件CodeBuddy 生成代码时会自动引用。幂等性保证是最容易被忽略的。我要求 CodeBuddy 在实现重试逻辑时必须确认被重试的操作是幂等的。如果不是要么改成幂等操作要么在重试前做状态检查。比如创建订单的操作重试前要先查询订单是否已经创建成功。4.3 日志记录的规范日志是排查问题的生命线但日志写不好就是噪音。我要求 CodeBuddy 遵守以下日志规范。日志级别使用要准确。debug 用于开发调试信息info 用于正常的业务流程节点warn 用于可恢复的异常情况error 用于需要人工介入的错误fatal 用于导致系统不可用的严重错误。日志内容必须包含足够的上下文。我要求每条日志至少包含时间戳、日志级别、请求 ID用于追踪完整调用链、用户 ID如果适用、操作名称、关键参数、执行结果。对于错误日志还必须包含错误码、错误信息、堆栈信息。日志格式我要求使用 JSON 结构化格式方便后续的日志收集和分析。这个格式我定义了一个模板CodeBuddy 按照模板生成日志代码。还有一个重要的规则是不要在循环里打日志。如果确实需要记录循环中的信息要么聚合后一次性输出要么使用采样日志。这个规则帮我避免了好几次日志量爆炸的事故。5. 架构决策合理性规则详解5.1 依赖引入的审批流程CodeBuddy 有个倾向遇到问题就建议引入一个新的依赖包。有时候确实需要但更多时候是过度设计。我制定了一个依赖引入的审批流程要求 CodeBuddy 在建议引入新依赖时必须回答以下问题。这个依赖解决什么问题现有依赖能不能解决自己实现需要多少代码量这个依赖的维护状态如何最近更新时间、issue 响应速度、社区活跃度这个依赖的体积有多大有没有已知的安全漏洞这个依赖的许可证是否兼容只有以上问题都有满意答案时才允许引入新依赖。我让 CodeBuddy 在建议引入依赖时自动生成一份简短的评估报告。这个规则执行下来项目的依赖数量减少了将近 40%构建速度和安全性都有明显提升。5.2 设计模式的选择依据CodeBuddy 对设计模式的使用有时候过于“热情”动不动就建议用工厂模式、策略模式、观察者模式。我的规则是设计模式是为了解决特定问题而存在的没有问题就不要用模式。我要求 CodeBuddy 在建议使用某个设计模式时必须说明当前代码面临的具体问题是什么这个模式如何解决这个问题以及如果不使用模式会有什么后果。如果它说不清楚那就说明不需要用模式。举个例子之前它建议用一个策略模式来处理不同类型的订单折扣计算。我让它解释为什么它说“这样可以方便扩展新的折扣类型”。我追问现在有几种折扣类型未来半年预计会增加几种它回答现在有 2 种未来不确定。我说那用简单的 if-else 就够了等真的有 5 种以上折扣类型时再重构。这个判断帮我避免了很多过度设计的代码。5.3 代码分层与模块边界我要求 CodeBuddy 严格遵守项目的分层架构不能跨层调用。我们的项目分为四层接口层、服务层、领域层、基础设施层。接口层只负责参数校验和响应格式化服务层负责业务流程编排领域层负责核心业务逻辑基础设施层负责数据库、缓存、消息队列等技术细节。CodeBuddy 在生成代码时必须明确说明这段代码属于哪一层以及它调用了哪些层的哪些接口。如果它生成的代码跨层了我会让它重新生成。这个规则保证了代码的架构清晰度后续维护和测试都方便很多。模块边界方面我要求每个模块必须有明确的对外接口模块内部实现不对外暴露。CodeBuddy 在生成模块代码时必须同时生成接口定义文件并且接口定义要包含完整的类型声明和文档注释。6. 实操流程与核心环节实现6.1 规则文件的编写与维护规则文件是整个体系的基础我来说说具体怎么写。文件放在项目根目录命名为.codebuddy-rules.md。文件结构分为五个部分项目概述、技术栈、代码风格、错误处理、架构约束。项目概述部分写清楚项目是做什么的、主要功能模块有哪些、当前的开发阶段。技术栈部分列出所有使用的语言、框架、库的版本号以及版本选择的原因。代码风格部分就是我前面说的命名规范、格式规范、注释规范。错误处理部分写清楚错误分类、重试策略、日志规范。架构约束部分写清楚分层规则、模块边界、依赖管理规则。这个文件不是写完就不管了我每个月会 review 一次根据项目的变化更新内容。每次更新后我会让 CodeBuddy 重新读一遍确保它使用的是最新规则。6.2 与 CodeBuddy 的交互模板每次开始一个新的功能开发时我会用以下模板和 CodeBuddy 交互。第一步让它读规则文件。我会说“请先阅读项目根目录的.codebuddy-rules.md文件了解本项目的开发规范。”第二步描述需求。我会用结构化的方式描述“我需要实现一个用户注册功能。输入是邮箱和密码输出是用户 ID 和 token。需要处理邮箱已存在、密码强度不足、数据库连接失败三种异常情况。请先给出实现思路不要直接写代码。”第三步审查思路。CodeBuddy 给出思路后我会检查它是否遵守了规则文件中的约定。如果有问题我会指出并让它修改。第四步生成代码。思路确认后让它按照思路生成代码并且要求它同时生成单元测试。第五步验收检查。用检查清单逐条核对生成的代码有问题的地方让它修改。这个流程看起来繁琐但熟练之后每个步骤都很快整体效率比“想到什么问什么”的方式高很多。6.3 检查清单的具体内容检查清单是我验收 CodeBuddy 输出的主要工具包含以下条目。代码风格方面命名是否符合规范格式是否通过 Prettier 检查注释是否解释了“为什么”而不是“是什么”是否有未使用的导入或变量错误处理方面是否处理了所有可能的异常错误分类是否正确重试策略是否合理日志是否包含足够上下文是否有硬编码的错误信息架构方面是否遵守了分层规则是否跨层调用了是否引入了不必要的依赖设计模式使用是否有明确理由模块边界是否清晰测试方面是否有对应的单元测试测试覆盖率是否达标是否测试了异常路径测试数据是否独立可重复性能方面是否有 N1 查询问题是否有不必要的循环嵌套是否有内存泄漏风险是否有阻塞主线程的操作这份清单我整理成了一个 Markdown 文件每次验收时逐条打勾。用了几个月后CodeBuddy 生成的代码质量明显提升很多问题在生成阶段就被它自己避免了。7. 常见问题与排查技巧实录7.1 CodeBuddy 不遵守规则怎么办这是最常见的问题。我的经验是CodeBuddy 不遵守规则通常有三个原因规则文件没读、规则描述有歧义、规则之间互相冲突。如果是规则文件没读我会在对话开始时明确要求它先读文件并且让它复述一遍关键规则。如果它复述错了说明没认真读我会让它重新读。如果是规则描述有歧义我会把规则改得更具体。比如“使用合适的错误处理”这种描述太模糊改成“数据库操作失败时重试 3 次间隔 1 秒、2 秒、4 秒重试失败后记录 error 日志并返回 500 错误码”就清晰多了。如果是规则之间冲突我会重新梳理规则体系消除冲突。比如之前有一条规则说“所有函数必须有返回值”另一条规则说“错误情况下抛出异常”这两条就冲突了。后来我改成“正常情况返回结果异常情况抛出异常”冲突就解决了。7.2 生成的代码质量不稳定有时候 CodeBuddy 生成的代码质量很高有时候又很差。我总结下来质量不稳定的主要原因是上下文不足。CodeBuddy 生成代码的质量很大程度上取决于它掌握的上下文信息。如果我只给它一个简单的需求描述它就只能靠猜。如果我给它完整的规则文件、相关的代码模板、类似的已有实现、明确的输入输出示例它生成的质量就稳定得多。所以我的做法是在让它生成代码之前先给它足够的上下文。具体包括相关的已有代码文件、接口定义、数据模型、测试用例、错误处理示例。这些信息给得越全生成质量越稳定。7.3 如何处理 CodeBuddy 的“过度设计”CodeBuddy 有时候会生成过于复杂的代码比如为了一个简单的功能引入多个设计模式、创建过多的抽象层、使用过于复杂的泛型。我的处理方式是先让它解释为什么这么设计然后问它如果简化会有什么问题。如果它说不出简化会有什么实质性问题那就说明可以简化。我会让它用最简单的方式重新实现然后对比两种方案的代码量和可读性。大多数情况下简单方案都更好。这里有个判断标准如果一段代码需要超过 3 句话来解释它的设计意图那它可能就太复杂了。好的代码应该是自解释的不需要太多额外的解释。7.4 常见问题速查表问题现象可能原因排查方法解决方案代码风格不一致规则文件未读取或描述模糊让 CodeBuddy 复述规则重新读取规则文件细化规则描述错误处理缺失规则中未强调或需求描述不完整检查规则文件和需求描述补充错误处理规则明确异常场景过度设计缺乏约束或需求理解偏差让 CodeBuddy 解释设计理由要求简化实现对比方案依赖引入过多未执行依赖审批流程检查依赖评估报告严格执行审批流程定期清理依赖测试覆盖不足未要求生成测试或测试规则不明确检查测试规则和覆盖率报告明确测试要求补充测试模板性能问题未考虑性能约束代码审查和性能测试补充性能规则增加性能测试7.5 独家避坑技巧第一个技巧让 CodeBuddy 自己 review 自己的代码。生成代码后我会让它以“代码审查者”的身份重新审视一遍找出潜在问题。这个方式很有效它经常能发现自己之前忽略的问题。第二个技巧用具体的反例来约束。与其说“不要写太复杂的代码”不如给它一个具体的反例说“不要像这样写”然后附上一段复杂代码。具体的反例比抽象的描述有效得多。第三个技巧定期更新规则文件。项目在变化规则也要跟着变。我每个月会花半小时 review 规则文件把过时的规则删掉把新踩的坑加进去。这个习惯让规则体系始终保持活力。第四个技巧把规则文件纳入版本控制。规则文件的变化也要有记录这样当 CodeBuddy 的行为发生变化时可以追溯是不是规则文件改了导致的。第五个技巧不要完全依赖 CodeBuddy 的自我检查。它说“我已经检查过了”不代表真的没问题。关键代码还是要人工审查尤其是涉及安全、资金、用户数据的部分。8. 规则体系的持续优化这套规则体系不是一成不变的我在实际使用中一直在调整。最近的一次调整是增加了“性能约束”部分因为发现 CodeBuddy 生成的代码有时候会有 N1 查询问题。调整后我要求它在生成数据库操作代码时必须考虑查询效率避免在循环中执行查询。另一个调整是增加了“安全约束”部分。我要求 CodeBuddy 在生成涉及用户输入的代码时必须考虑 SQL 注入、XSS 攻击、CSRF 攻击等安全风险并且使用参数化查询、输入转义、CSRF token 等防护措施。还有一个正在考虑的方向是让规则体系更加“个性化”。不同的项目、不同的团队可能有不同的偏好我希望这套规则能够灵活配置而不是一刀切。比如有的团队喜欢用 class 组件有的喜欢用函数组件规则应该能够适配这些差异。最后分享一个我最近发现的小技巧把规则文件拆分成“基础规则”和“项目规则”两部分。基础规则是所有项目通用的比如命名规范、错误处理原则项目规则是特定项目独有的比如技术栈版本、业务约束。这样在新项目启动时只需要复制基础规则再补充项目规则就行省去了很多重复工作。这套规则体系帮我节省了大量时间也让我对 AI 编程助手的使用有了更深的理解。工具再强大也需要正确的使用方法。希望这些经验对你有帮助。