从AI编码代理获得更好结果的10条规则
内容提要
AI编码工具虽强大，但需配合工程纪律。本文提出10条实用规则：明确规格而非模糊提示、使用AGENTS.md文件、保持指令简洁、先检查再编辑、复杂任务用规划、以测试为契约、提供风格示例、控制依赖权限、仔细审查AI改动、迭代指令。核心是：更好的输出始于更好的工程规范，而非更好的模型。
延伸解读
为什么规范比模型更重要
文章强调，AI编码代理的效果更多取决于工程纪律而非模型本身。HackerRank报告指出，97%的开发者使用AI助手，但近三分之一的代码由AI生成，这增加了交付压力。作者认为，明确的目标、项目上下文和验证规则是成功的关键。这提醒我们，在依赖AI时，不能忽视基本的工程实践，如编写清晰的规格说明和定义完成标准。
AGENTS.md文件的实际价值
AGENTS.md作为一种代理指令文件，被超过6万个开源项目采用，它集中存放项目规则，避免在每次提示中重复。文章提到，Codex和GitHub Copilot都支持此类文件，但需注意“配置异味”，如上下文膨胀和指令冲突。一份好的指令文件应包含构建、测试、代码风格等具体信息，而不是泛泛的通用建议。
测试作为反馈循环的关键
文章建议将测试作为代理的契约，先写失败测试，再实现最小修复，并运行相关测试。这为代理提供了反馈循环，使其优化目标是“可工作的代码”而非“看似合理的代码”。HackerRank也强调调试成为AI时代的核心技能，因为AI生成的代码仍需可靠性验证。这一方法能显著提升AI辅助开发的质量。
权限控制与人工审查的必要性
代理倾向于通过安装包或修改配置来解决问题，这可能带来长期维护风险。文章建议设置依赖策略，并利用工具提供的钩子或权限控制。同时，审查AI改动时，应关注是否解决原问题、是否改变无关行为、是否削弱安全性等。开发者仍需对架构、正确性和可维护性负责，代理只是加速实现。
Q&A
如何为AI编码代理编写有效的提示词？
应提供包含目标、范围、约束、可能更改的文件、验收标准和测试命令的详细规格，而不是模糊的提示。例如，明确构建客户流失仪表板的目标、范围、验收标准等。
AGENTS.md文件的作用是什么？
AGENTS.md是仓库级别的代理指令文件，用于存放持久性项目规则，如安装、测试命令、代码风格和完成前检查。它被超过6万个开源项目使用，Codex和GitHub Copilot等工具支持读取。
为什么代理指令文件应保持简洁？
因为指令文件加载后，每个token都会与任务上下文竞争，冗长或矛盾的指令会导致上下文膨胀和配置异味。研究发现，62%的流行仓库存在lint泄漏，42%存在上下文膨胀。应只包含必要的安装、构建、测试、架构说明和约束。
在让AI代理编辑代码前，应要求它做什么？
对于非平凡任务，应要求代理先检查相关文件并总结：哪些文件控制认证、bug可能在哪里、已有测试覆盖、最小安全更改。在获得总结前不要修改文件，以避免在错误位置进行修改。
哪些任务适合使用规划模式？
适合规划的任务包括迁移、多文件重构、认证更改、数据库更改、性能工作、生产bug修复以及涉及安全或支付的任务。而简单的打字错误修复、小测试添加、简单CSS更改和单函数重构则不需要过度规划。
如何利用测试作为AI编码代理的契约？
先为bug编写失败的测试，确认失败，然后实现最小修复，不要修改测试（除非测试本身错误），并在完成前运行相关测试套件。这为代理提供了反馈循环，使其优化工作代码而非看似合理的代码。
如何向AI代理提供代码风格示例？
提供具体示例，如“遵循src/features/billing/CreateInvoice.tsx的风格”或“使用与src/lib/apiClient.ts相同的错误处理模式”，而不是抽象地说“使其干净且生产就绪”。示例减少歧义，防止代理发明与现有代码库冲突的新风格。
如何控制AI代理的依赖和权限？
在指令文件中添加依赖策略，如“未经批准不得添加生产依赖”或“优先使用现有工具”。同时，利用工具支持的钩子或权限控制，如Claude Code的钩子，确保特定检查可靠执行。
审查AI生成的代码时应关注哪些问题？
应问：是否解决了请求的问题？是否改变了无关行为？是否添加了不必要的抽象？是否削弱了安全性？是否隐藏了错误而非修复？是否更新了测试？是否遵循项目约定？diff能否更小？
当AI代理犯错时，应如何改进指令？
不仅修复代码，还要修复允许错误的指令。例如，如果代理直接修改了生成文件，添加规则“不要编辑src/generated/中的文件，更新schema或生成器源”。如果代理每次运行完整测试套件，添加测试策略，先运行受影响的组件测试。
