大语言模型辅助编程已进入实用阶段，但工程团队普遍面临一个核心矛盾：模型输出代码的速度远超人类审查能力，而质量参差不齐的代码正在悄然累积技术债务。Andrej Karpathy 通过长期观察，于 2025 年底在社交平台分享了对当前 LLM 编码行为的系统反思，指出模型存在「隐藏假设」「过度工程化」「无意识改写」等系统性缺陷。这一观察直接催生了针对 Claude Code 的技能增强方案 —— 通过一个 CLAUDE.md 文件，将人类工程师的工程判断转化为模型可遵循的行为约束。

一、LLM 编码的三个系统性陷阱

Karpathy 的核心洞察可以归纳为三个相互关联的问题。首先是假设隐匿化：模型在面对模糊需求时倾向于自行选择一种解释然后埋头执行，而不是暴露多种可能性并请求确认。这种行为模式导致代码实现与用户真实意图产生偏差，且偏差往往在代码审查阶段才被发现。其次是过度工程化：模型表现出对复杂抽象的偏好，常常用数百行代码实现一个本可以用几十行解决的问题，引入不必要的接口层、配置项和错误处理分支。Karpathy 形象地称之为「建造 1000 行的豪华大厦而实际只需要 100 平方米的小屋」。第三是正交性破坏：模型在修改代码时容易连带修改注释、格式或相邻逻辑，即使这些变更与原始任务无关。这种「附带效应」使 diff 审查变得困难，也增加了引入回归 bug 的风险。

这些问题并非模型能力不足，而是模型优化目标与人类工程期望之间的结构性错位。模型被训练为最大化输出「有帮助」的回答，而在缺乏明确约束的情况下，「有帮助」被误解为「快速给出完整解决方案」。因此，需要通过显式的行为指导文件来重新校准模型的输出模式。

二、四项核心原则的工程内涵

针对上述陷阱，Karpathy 技能库提炼出四项互补的原则，每一项都对应明确的工程行为。

原则一：编码前思考（Think Before Coding）。这一原则要求模型在动笔之前完成三项动作：显式声明所有假设、列出可能的替代解释、在存在不确定性时主动提问而非猜测。工程落地的关键参数包括：假设声明应作为代码注释嵌入实现顶部；替代方案需以「方案 A / 方案 B」形式列出并附带取舍分析；模型遇到模糊需求时应输出「需要澄清：XXX」而非自行决定。该原则对应的实践阈值是：当需求涉及外部接口、数据格式或业务规则时，必须在实现前输出结构化的假设清单。

原则二：简约优先（Simplicity First）。该原则从两个维度约束模型行为：一是禁止引入需求之外的任何功能、抽象或配置项；二是对单次使用的代码拒绝抽象，直接展开。具体的可量化标准包括：单个函数不超过 80 行；禁止为「未来可能的需求」预留接口；不处理逻辑上不可能出现的异常分支。Karpathy 给出了一个极具操作性的检验标准：「如果高级工程师认为这段代码过度复杂，那么就应该简化。」在工程实践中，这意味着模型在产出代码后应自行问自己：这个抽象是否只被调用一次？这个配置项是否有真实的运行时用途？

原则三：精确修改（Surgical Changes）。这一原则旨在解决正交性破坏问题。模型在进行代码编辑时，应严格遵循「只改必要部分」的铁律。具体要求包括：不修改相邻的注释和格式，除非明确被要求；不进行「改进式重构」—— 即修复原本正常工作的代码；如果注意到无关的死代码，仅作提示而不自动删除。工程化的实现方式是：模型在提交修改前应生成一份「变更范围清单」，逐行说明每处修改的直接原因，确保所有变更都可以追溯到用户的原始请求。

原则四：目标驱动执行（Goal-Driven Execution）。这是四项原则中最具方法论意义的创新。Karpathy 观察到，LLM 在循环迭代中表现优异，但在接受指令式任务时容易丢失上下文。因此，他提出将「做 X」转化为「验证 Y」的思路。工程实践中的具体参数包括：任务描述必须包含可验证的成功标准；多步骤任务应拆解为「步骤 → 验证方式」的表格；模型的自我检验应形成闭环，直到所有验证通过才能提交。例如，「修复 bug」应被重新表述为「编写一个复现该 bug 的测试，运行后测试失败，修复代码使测试通过」。

三、工程化落地的具体参数

将上述原则转化为可操作的工程实践，需要明确以下参数和阈值。

在配置层面，推荐在项目根目录放置 CLAUDE.md 文件，文件内容应按以下顺序组织：项目概述（50 字以内）、技术栈与约束（明确版本号和规范）、四项原则的执行要点（从本文档精简而来）、项目特定的编码规范。对于新项目，可通过以下命令直接获取标准模板：curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md。对于已有项目，建议使用追加模式将原则合并至现有文件：echo "" >> CLAUDE.md && curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md。

在插件模式下，Claude Code 用户可以通过两个命令完成安装：先添加插件市场 //plugin marketplace add forrestchang/andrej-karpathy-skills，再安装具体插件 //plugin install andrej-karpathy-skills@karpathy-skills。插件模式的优势在于原则自动应用于所有项目，无需重复配置。

在验证层面，团队应建立以下审查机制：每次模型生成的代码变更 diff 中，非任务相关的修改行数应为零；如果模型产出的函数超过 80 行，应触发自动提醒要求重构；模型在实现前未声明假设的，代码审查应予以拒绝。这些参数的阈值并非刚性约束，而是作为团队 LLM 使用规范的基线。

四、实践效果与适用边界

根据社区反馈，遵循这四项原则后，典型工程团队可以观察到以下改善：diff 中的无关变更行数减少约 60% 至 70%；因过度工程化导致的代码重写次数下降；模型在实现前主动提问的比例从接近零提升至 15% 至 20%，显著降低了返工成本。

值得注意的是，这些原则存在适用边界。Karpathy 技能库本质上是一种「审慎优先」的策略，对简单任务（如拼写修正、明显的一行修复）施加完整流程反而降低效率。团队应根据任务复杂度动态调整原则的严格程度：对于需要多文件修改、涉及数据迁移或影响核心业务逻辑的任务，严格执行四项原则；对于简单的修复或实验性代码，允许模型使用更直接的实现路径。

从长期看，这类技能文件的真正价值在于将资深工程师的隐性判断显式化。Karpathy 的四项原则本质上是数十年软件工程最佳实践的凝练 —— 简约设计、精确修改、目标导向 —— 而现在这些原则通过 CLAUDE.md 这一载体得以在模型层面复现。对于追求工程可靠性的团队而言，将此类技能文件纳入开发流程，已经从「可选优化」演变为「必要基础设施工具」。

参考资料

  • Andrej Karpathy 对 LLM 编码陷阱的系统性观察（X/Twitter, 2025）
  • forrestchang/andrej-karpathy-skills GitHub 仓库：基于 Karpathy 经验的 Claude Code 技能实现