在 AI 辅助编程实践中，如何有效约束大语言模型的编码行为，一直是工程团队关注的核心议题。Andrej Karpathy 通过一份定制的 CLAUDE.md 文件，系统性地总结了 LLM 编码过程中的常见陷阱，并给出了可操作的约束规则。本文将深入解析这份配置文件的指令设计思路，提取可复用的工程模式，为 AI 助手指令工程的落地提供参考。

一、CLAUDE.md 的定位与设计哲学

CLAUDE.md 是 Claude Code 项目中用于指导 AI 行为的核心配置文件，其本质是一种前置约束机制 —— 在模型执行任务之前，通过显式的规则声明来塑造其行为模式。Karpathy 版本的设计哲学可以概括为「谨慎优先于速度」，这一点在文件开篇的 Tradeoff 声明中得到了明确表达：这些指南倾向于谨慎而非快速，对于 trivial 任务则需要自行判断。

这种设计思路反映了一个重要的工程认知：AI 助手在缺乏约束时，往往倾向于过度发挥 —— 添加未请求的功能、创建不必要的抽象、实现过度的灵活性。这些行为在人类工程师看来是「过度工程化」，但在 AI 的训练目标中可能是「展现能力」的表现。因此，通过显式规则进行行为约束，就成为了必要的工程手段。

从指令工程的角度看，CLAUDE.md 的设计采用了「负面清单 + 正面原则」的混合模式。负面清单通过明确禁止某些行为来划定边界，正面原则通过指导性建议来引导行为方向。这种组合策略比单纯的禁止性规则更具灵活性，同时也更容易被 AI 模型理解和遵循。

二、四大核心原则的结构化解析

2.1 Think Before Coding：思考先于编码

这一原则的核心是要求 AI 在动手之前显式声明其假设和不确定性。具体规则包括：不要假设、不要隐藏困惑、表面权衡取舍。在实现之前，需要明确陈述假设，如果不确定则应该提问；当存在多种解释时，不应该默默选择而应该呈现所有选项；如果存在更简单的方案，应该主动提出；在遇到不清晰之处时应该停止并明确提出问题。

这一原则的工程价值在于将 AI 的「推理过程」外化。在传统的 AI 交互中，模型往往直接给出结果，其推理过程隐藏在黑盒中。通过要求显式声明假设，开发者可以在早期阶段发现理解偏差，从而避免实现完成后的返工。从指令设计角度看，这种「先推理后行动」的模式可以通过 few-shot 示例进一步强化，例如在指令中包含「在回答之前，先列出你对问题的理解」的提示。

2.2 Simplicity First：简洁优先

简洁优先原则是整个 CLAUDE.md 中最具操作性的指导方针。其核心规则包括：不添加超出请求的功能、不为单次使用的代码创建抽象、不添加未被请求的「灵活性」或「可配置性」、不为不可能的场景添加错误处理。文件还给出了一个具体的量化参考：如果写了 200 行代码而可以用 50 行完成，就应该重写。

这一原则直指 AI 编码的最大痛点 —— 过度工程化。AI 模型在训练过程中学习到的代码模式往往包含大量的设计模式和「最佳实践」，但在具体任务场景中，这些模式可能完全是多余的。Karpathy 的策略是将「简洁」定义为「刚好解决问题」，并通过「 senior engineer test 」来量化判断标准：询问「一位资深工程师会说这过于复杂吗？」

从工程落地的角度，简洁优先原则可以通过代码行数阈值来监控。例如，定义单次修改的增量代码不超过特定行数，或者要求 AI 在提交前解释每个新增函数的必要性。这种量化约束可以作为 CI/CD 流程中的一部分，自动检测潜在的过度工程化。

2.3 Surgical Changes：精准修改

「外科手术式修改」是 Karpathy 对 AI 修改代码行为的核心期望。这一原则包含两个层面：在编辑现有代码时，不要「改进」相邻代码、注释或格式；不要重构没有坏掉的东西；即使风格不同也要匹配现有风格；如果注意到无关的死代码，只需提及而非删除。在清理方面，只有自己修改导致的孤儿代码（未使用的导入、变量、函数）才需要移除，预先存在的死代码除非被明确要求否则不要删除。

这一原则的工程意义在于控制变更范围。AI 在修改代码时容易「顺手」做很多「改进」，这些变更看起来是善意的，但实际上会增加代码审查的负担、引入潜在的回归风险，也违背了最小变更原则。Karpathy 提出的检验标准非常实用：每一行修改都应该可以直接追溯到用户的原始请求。

从指令设计角度看，「Surgical Changes」原则可以通过具体的操作约束来实现，例如在指令中明确说明「本次任务只修复 XXX bug，不要涉及其他模块的优化」。这种明确的范围界定可以有效抑制 AI 的「改进冲动」。

2.4 Goal-Driven Execution：目标驱动执行

目标驱动执行原则要求将模糊的任务描述转化为可验证的目标。文件给出的转换示例包括：「添加验证」变为「为无效输入编写测试，然后让它们通过」；「修复 bug」变为「编写能复现 bug 的测试，然后让测试通过」；「重构 X」变为「确保重构前后测试都通过」。

对于多步骤任务，该原则还要求在执行前声明简要计划，格式为「步骤 → 验证方式」。这种设计将任务分解为可独立验证的子任务，使得每个阶段的成功标准清晰可见。文件强调：强成功标准允许独立循环，弱成功标准则需要不断澄清。

从工程实践角度看，目标驱动执行与测试驱动开发（TDD）理念高度契合。Karpathy 的创新在于将 TDD 的思想延伸到了 AI 任务规划中，要求 AI 在实现之前先定义「什么是成功」，而非盲目开始编码然后询问「这样可以吗」。

三、指令工程的可复用模式

通过解析 Karpathy 的 CLAUDE.md，我们可以提炼出 AI 助手指令工程的几个可复用模式。

第一个模式是「权衡声明模式」。在文件开篇明确声明 Tradeoff（权衡），让 AI 知道存在相互冲突的目标需要平衡。例如「这些指南倾向于谨慎而非速度」就是一个成功的权衡声明，它帮助 AI 在具体场景中做出合理取舍。工程落地时可以针对不同任务类型定义不同的权衡策略：对于关键系统选择可靠性优先，对于原型开发选择速度优先。

第二个模式是「量化判断标准」。简洁优先原则中的「200 行 vs 50 行」就是一个具体的量化阈值。虽然这个数字不是绝对的，但它提供了一个可操作的判断依据。类似地，可以在指令中定义其他量化标准：单次修改不超过 X 行、每个函数不超过 Y 行、注释率不低于 Z% 等。

第三个模式是「成功标准外化」。Goal-Driven Execution 原则要求将隐含的「做好」转化为显式的「做到什么程度」。这种模式可以通过模板来实施：为每个任务强制要求声明「验收标准」，格式为「输入 → 预期输出」或「功能点 → 验证方法」。

第四个模式是「变更范围控制」。Surgical Changes 原则本质上是一种变更范围控制机制。工程落地可以通过「变更清单」来实现：要求 AI 在提交前列出所有变更，并标注每项变更与原始需求的对应关系。

四、工程落地要点

将 CLAUDE.md 的设计理念转化为工程实践，需要关注以下几个落地要点。

首先，指令文件需要与项目特性适配。Karpathy 的版本是一个通用模板，实际项目中应该基于技术栈、团队规范、代码复杂度等因素进行定制。例如，对于遗留代码项目，应该强化 Surgical Changes 原则；对于快速迭代的创业团队，可以放宽简洁优先的限制。

其次，量化阈值需要根据团队实际情况校准。文件中的具体数字（如 200 行）应该被视为参考起点而非绝对标准。团队可以通过收集 AI 交付物的质量指标，逐步调整阈值，找到适合本团队的平衡点。

第三，监控与反馈机制是持续改进的关键。文件末尾提到「这些指南有效运作的标志是：diff 中的不必要变更减少、因过度复杂导致的返工减少、澄清问题出现在实现之前而非错误之后」。这些指标可以量化并纳入团队的质量监控体系。

第四，指令文件本身需要版本控制。CLAUDE.md 应该被视为代码库的一部分，纳入版本控制，并在团队内共享。当发现某些规则过于严格或过于宽松时，应该有明确的反馈和迭代机制。

五、总结

Karpathy 定制的 CLAUDE.md 提供了一种系统化的 AI 助手指令工程方法论。通过 Think Before Coding、Simplicity First、Surgical Changes、Goal-Driven Execution 四大原则，它有效地约束了 LLM 在编码过程中的常见不良行为。从工程落地的角度看，这些原则可以通过权衡声明、量化判断标准、成功标准外化、变更范围控制等模式来实现具体化操作。最终，成功的指令设计应该让 AI 的行为可预测、可控制、可度量，同时保持足够的灵活性以适应不同任务场景的需求。

资料来源：