如何教会 AI 编码代理遵循项目规范

为什么要把项目规范告诉代理

AI 编码代理能读取代码并修改文件，但它通常不知道团队约定：测试应放在哪里、组件如何命名、哪些文件不能改，或提交前必须运行什么命令。只在每次对话里临时提醒，容易遗漏，也难以复用。更可靠的做法是把规范写进仓库，让代理在开始任务时就能找到，并用检查和示例帮助它正确执行。

下面以常见的 Git 仓库为例。不同工具读取指令文件的方式有所不同，先确认你使用的代理支持哪些文件，再按其文档配置。Claude Code、Codex 和 Gemini CLI 等工具都可用于这类工作流；ApiCabin 提供一个密钥和按量付费的 API 接入方式，兼容这些编码工具及 OpenAI 兼容 SDK。需要配置模型时，可以先用 Claude Sonnet 5.5 或 GPT-6 Astra 这类当前提供的模型作为示例。读者可注册 ApiCabin，按实际用量使用所需服务。

第一步：盘点现有约定

不要先凭空制定一套规则。检查项目中的 README、贡献指南、格式化配置、CI 工作流和测试目录，找出已经存在的约定。观察最近几次合并的改动：文件如何命名，错误如何处理，测试覆盖哪些行为。把结论分成两类：已经通过工具强制执行的规则，以及仍需代理在编写代码时主动遵守的规则。

优先记录能减少返工的事实，例如使用哪个包管理器、如何启动测试、模块的边界，以及新增功能必须补哪些测试。避免把个人偏好写成全团队强制要求；遇到尚未统一的做法，明确说明暂时应沿用相邻代码的模式。

第二步：选择代理会读取的位置

将通用指令放在仓库根目录中代理能识别的指令文件里。若工具支持目录级规则，可把前端、后端或测试专属约定放在对应目录，避免一份文件塞入所有细节。文件名和格式应遵循当前工具的官方说明；不要假定不同代理会自动读取彼此的配置。

根目录指令可说明项目目标、重要目录、常用命令和全局禁区。目录级规则只写局部知识，例如某模块的接口约束。README 面向人类读者，代理指令则应更直接地告诉执行者要检查什么、要做什么。

第三步：把规则写成可执行要求

每条规则尽量包含触发条件和预期动作。“代码要简洁”不够明确；“修改 API 响应结构时，同时更新对应的契约测试，并运行指定测试命令”更容易验证。规则可以覆盖以下方面：

• 修改前先阅读相关模块及相邻测试，不要仅凭文件名推断行为。
• 遵循现有命名和错误处理方式；新增依赖前先说明必要性。
• 修改公开接口时更新文档、类型定义或兼容性测试。
• 不要覆盖用户已有改动，也不要编辑生成文件或密钥文件。
• 完成后运行与改动范围匹配的检查，并报告未能运行的项目。

把必做事项与建议事项分开。指令过长会让重点被淹没；可以链接到详细架构文档，但关键的安全限制和验证命令应留在代理会实际读取的位置。

第四步：给出正反示例

示例能消除抽象规则的歧义。选取仓库中的一段典型实现，说明新代码应复用哪个函数、测试如何组织。若常见错误是直接访问数据库而绕过仓库层，写出禁止的做法和正确替代方案。示例必须真实、简短，并保持与现行代码一致；过时示例会让代理学错。

也可以补充任务完成时的输出约定，例如列出改动文件、运行过的检查以及仍存在的风险。这样团队不仅能评估代码，也能快速判断代理是否完成了必要验证。

第五步：用小任务测试指令

选一个范围明确、风险较低的任务，让代理先阅读规则，再执行改动。检查它是否找到正确目录、遵循现有模式、补充测试并报告验证结果。遇到偏差时，区分是规则没写、规则位置不对，还是仓库本身缺少一致做法，然后只调整对应部分。

不要因为一次成功就认为规则已完善。用另一类任务再试一次，例如修复缺陷和增加小功能，确认指令不会只适用于单一场景。

第六步：让规则持续有效

规范会随工具链和架构变化。每次重要重构或新增目录后，检查指令是否仍准确；命令有变化时同步更新；删除不再适用的例外。把指令文件和代码一起纳入评审，避免它变成无人维护的说明。

最后，把可自动检查的要求交给格式化工具、测试或 CI，而不是只依赖代理记忆。清晰的规则、真实的示例和可重复的验证彼此配合，才能让 AI 编码代理稳定融入项目工作流。