分享约束Coding Agent不乱改的AGENTS.md规则集

背景

在当前的 AI 辅助编程实践中，尽管大型语言模型（LLM）展现出强大的代码生成能力，但许多开发者仍面临一个共同痛点：AI 往往“过度热情”。它倾向于在未经充分确认的情况下进行大规模重构、引入不必要的抽象层、修改无关代码，甚至掩盖潜在的歧义。这种行为不仅增加了代码审查的成本，还可能导致引入新的 Bug 或破坏现有系统的稳定性。

为了解决这一问题，知名 AI 研究者 Karpathy 分享了一套用于约束 Coding Agent（编码智能体）行为的规则集。这套规则旨在通过结构化的指令，强制 AI 在编码前进行深度思考，减少假设，避免过度工程化，并确保每一次代码变更都有明确的验证标准。将其放入项目级的 AGENTS.md 文件中，可以显著改善 AI 生成代码的质量和相关性，使其行为更加可控和可预测。

核心内容

该规则集基于四大核心原则，旨在规范 AI 的编码逻辑与行为模式：

1. 编码前思考 (Think Before Coding)

这一原则的核心在于消除 AI 的“静默假设”。LLM 经常在没有明确指示的情况下自行解读需求并执行，这容易导致偏差。该原则要求 AI 显式地展示其推理过程：

• 显式陈述假设：如果存在不确定性，AI 应当提问而非猜测。
• 呈现多种解释：当需求存在歧义时，不要 silently pick（默默选择）一种解释，而应列出多种可能性供用户决策。
• 适时反驳：如果存在更简单的解决方案，AI 应当主动指出，而不是盲目执行复杂指令。
• 困惑时停止：如果无法理解需求，应明确指出不清楚的地方并请求澄清，而不是强行生成代码。

2. 简单优先 (Simplicity First)

这一原则旨在对抗过度工程化（Overengineering）的倾向，强调“最小代码解决最小问题”。具体要求包括：

• 不添加多余功能：只实现用户明确要求的功能，不添加任何推测性的特性。
• 避免无用抽象：对于仅使用一次的代码，不要创建抽象层。
• 拒绝未请求的灵活性：除非用户要求，否则不要添加配置项或可扩展性设计。
• 不处理不可能场景：避免为逻辑上不可能发生的错误情况编写错误处理代码。
• 精简代码量：如果 200 行代码可以简化为 50 行，必须重写。
• 验证标准：自问“资深工程师会认为这段代码过于复杂吗？”如果是，则必须简化。

3. 外科手术式变更 (Surgical Changes)

这一原则强调代码修改的精确性和局部性，要求 AI 像外科医生一样精准操作，只触碰必要的部分：

• 不美化无关代码：不要“改进”相邻的代码、注释或格式，除非它们是当前任务的一部分。
• 不重构正常代码：不要重构那些没有问题的代码。
• 保持风格一致：即使你偏好不同的风格，也必须匹配现有代码的风格。
• 不删除遗留死代码：如果注意到无关的死代码，应提及它，但不要删除它。
• 清理自身遗留物：如果 AI 的变更导致某些导入、变量或函数变得未使用，AI 应当移除这些由自己变更产生的“孤儿”代码。
• 不主动清理历史遗留：除非被明确要求，否则不要移除预先存在的死代码。
• 验证标准：每一行被修改的代码都应能直接追溯到用户的原始请求。

4. 目标驱动执行 (Goal-Driven Execution)

这一原则要求将命令式任务转化为可验证的目标，通过测试驱动开发（TDD）的思维来确保结果的正确性：

• 定义成功标准：将模糊的任务转化为具体的验证步骤。
  • 将“添加验证”转化为“为无效输入编写测试，然后使其通过”。
  • 将“修复 Bug”转化为“编写复现该 Bug 的测试，然后使其通过”。
  • 将“重构 X”转化为“确保重构前后测试均通过”。
• 多步骤计划与验证：对于多步骤任务，AI 应制定简要计划，并为每一步设定验证检查点：
  • Step 1 → verify: [检查点]
  • Step 2 → verify: [检查点]
  • Step 3 → verify: [检查点]
• 强成功标准：强大的成功标准允许 LLM 独立循环验证，而弱标准（如“让它能运行”）则需要不断的澄清和干预。

关键要点

• 显式优于隐式：强制 AI 在编码前公开其假设和推理过程，减少因“静默猜测”导致的错误。
• 克制过度工程：严格限制代码的复杂性，拒绝未请求的抽象、配置和错误处理，追求极简实现。
• 最小化变更范围：AI 应仅修改解决当前问题所必需的最小代码集，保持对现有代码库的尊重和不干扰。
• 测试驱动验证：将任务转化为可测试的目标，通过编写测试来定义成功标准，确保代码变更的正确性。
• 自我清理机制：AI 应负责清理由其自身变更引入的未使用代码，但不触碰项目原有的遗留问题。
• 结构化交互：通过 AGENTS.md 等配置文件将规则固化，使 AI 的行为模式标准化，提升长期协作效率。

意义与影响

这套规则集对 AI 辅助编程工作流具有深远的意义：

1. 提升代码质量与可维护性：通过限制过度工程和无关改动，生成的代码更加简洁、专注，降低了后续维护的难度和出错概率。
2. 增强可控性与可预测性：将 AI 的行为从“黑盒”转化为基于明确规则的“白盒”操作，开发者可以更准确地预测 AI 的输出，减少意外破坏。
3. 优化人机协作效率：通过强制 AI 在困惑时提问、在变更前思考，减少了因误解需求而导致的反复修改和沟通成本。
4. 推动 TDD 思维普及：将测试验证嵌入到 AI 的执行流程中，有助于培养开发者以测试驱动设计的习惯，提升整体软件工程素养。
5. 标准化 AI 行为：通过 AGENTS.md 等文件将最佳实践制度化，使得不同团队成员使用的 AI 工具能够遵循一致的标准，促进团队协作的一致性。

总之，这套规则不仅是约束 AI 的技术手段，更是将资深工程师的工程思维注入 AI 工作流的桥梁，有助于在享受 AI 效率红利的同时，保持代码库的健康与稳定。