Andrej Karpathy 在 2025 年多次公开分享了他对大型语言模型编程行为的深度观察，这些观察揭示了当前 LLM 作为编程助手时存在的系统性缺陷。基于这些观察，社区开发者构建了一套完整的技能定义框架，通过 CLAUDE.md 文件为 Claude Code 等 AI 编程代理提供行为约束机制。这一框架的核心理念是：与其告诉 AI “怎么做”，不如给它定义 “做到什么程度算完成”，让 AI 具备自我验证和 surgical（精确）编辑的能力。
Karpathy 观察到的 LLM 编程四大陷阱
Karpathy 指出，LLM 在编程任务中表现出四类典型问题。第一类是隐藏假设不报告：模型 silently（默默地）做出解释并沿用，从不验证这些假设是否正确，当发现假设错误时已经造成了大量返工。第二类是不寻求澄清：面对模糊需求，AI 倾向于自行猜测而非主动提问，这种 “先行先试” 的心态导致方向性错误频发。第三类是过度工程化：模型表现出对复杂代码和抽象的偏好，常常用上千行代码实现一个几百行就能完成的功能，引入不必要的灵活性和可配置项。第四类更具破坏性：随意修改不相关的代码，即使是与其任务正交的部分，AI 也会在 “优化” 或 “美化” 的名义下改动注释和逻辑。
这些问题源于训练数据中大量存在 “执行指令” 而非 “定义目标” 的范式。人类工程师在接收模糊需求时会追问细节、提出备选方案、权衡复杂度与可维护性，但当前的 LLM 更倾向于展示 “服从性” 而非 “专业判断力”。Karpathy 的核心洞察在于：LLM 非常擅长在明确目标下循环迭代直到达成目标，问题在于人类总是用命令式语言（imperative）而非声明式语言（declarative）来描述需求。
四项核心原则的工程化实现
基于上述观察，Karpathy 技能框架提取出四项可操作的原则，每项原则都对应明确的行为检查点。
原则一：Think Before Coding（编码前先思考）。这一原则要求 AI 在动笔之前明确陈述所有假设。具体实现时，AI 需要在处理任何非平凡任务前输出类似 “基于我的理解，该任务的目标是 X，我将采用 Y 方案，假设前提是 Z” 的声明。当发现假设存在歧义时，必须在实现前提出澄清问题而非自行猜测。这一原则的量化标准是：每完成一次代码生成后，检查生成的代码是否依赖于任何未经验证的假设。实践中建议在任务开始时先用自然语言列出三点假设清单，任何一条无法确认都必须停止并询问。
原则二：Simplicity First（简单性优先）。该原则直接对抗 LLM 的过度工程化倾向。其核心规则是：不做超出需求的功能、不为单次使用的代码创建抽象、不添加未被要求的 “灵活性”、不为不可能的场景编写错误处理。框架提供的检验标准是：如果一段代码可以从 200 行缩减到 50 行而功能不变，就应该重写。另一个实用的判断维度是 “高级工程师会认为这过度复杂吗”—— 如果答案是肯定的，立即简化。这一原则在实践中需要与项目的实际约束条件结合，例如在遗留代码库中可能需要保留一定的冗余以保持风格一致性。
原则三：Surgical Changes（外科手术式变更）。这一原则解决了 AI 随意扩散修改范围的问题。其核心要求是：只修改任务直接涉及的文件和代码行，不对相邻代码进行 “改进”，不修改与任务正交的注释或格式，保持与现有代码风格的一致性 —— 即使个人偏好不同。如果在修改过程中产生了孤立的导入、变量或函数，必须清理这些由自己引入的副作用，但不要主动删除预先存在的死代码，除非用户明确要求。量化标准是：每次 Pull Request 的 diff 中，每一行变更都应该可以直接追溯到用户的原始请求。
原则四：Goal-Driven Execution（目标驱动执行）。这是将命令式任务转化为声明式目标的关键原则。框架要求将 “添加验证” 转化为 “编写针对无效输入的测试用例，然后让测试通过”；将 “修复 bug” 转化为 “编写能复现 bug 的测试用例，然后让测试通过”；将 “重构 X” 转化为 “确保重构前后测试都通过”。对于多步骤任务，建议采用 “步骤→验证” 的结构化格式，例如 “一、修改配置文件 → 验证：启动服务无报错；二、运行集成测试 → 验证：全部通过；三、清理构建产物 → 验证：目录大小减少 30% 以上”。这种格式让 LLM 可以在获得明确成功标准后自主循环迭代，直到所有验证点通过。
CLAUDE.md 技能文件的工程实践
将上述原则落实为可安装的技能，需要遵循 CLAUDE.md 的最佳实践。首先，文件应当简短且行动导向。根据社区经验，优秀的 CLAUDE.md 应该包含项目核心结构（主要目录和关键文件位置）、构建和测试命令、特殊的环境配置要求以及已知陷阱，但不应包含已由 linter 或 formatter 强制执行的代码风格规则。文件长度建议控制在 200 至 500 词之间，确保 AI 能够有效利用其中的信息。
渐进式披露是另一个重要设计模式。最关键、最高频使用的规则放在 CLAUDE.md 主体中，更深层的专项指南（如数据库迁移流程、发布流程）通过链接指向独立文件，只在相关任务被激活时才加载。子目录级别的 CLAUDE.md 可以覆盖更严格的上下文约束，例如在 packages/core/ 目录下放置更严格的类型检查要求。
安装方式分为插件模式和单文件模式。插件模式通过两条命令完成：/plugin marketplace add forrestchang/andrej-karpathy-skills 添加技能市场，然后 /plugin install andrej-karpathy-skills@karpathy-skills 安装技能。这种方式让技能在所有项目中自动生效。单文件模式则适合项目级别的定制，通过 curl 命令拉取模板后追加到项目根目录的 CLAUDE.md 文件中。两种模式的选取取决于团队对一致性要求与项目特定灵活性之间的权衡。
可落地的行为检查清单
为便于在日常使用中验证框架效果，整理以下实用检查点。在每次任务开始前，检查是否已明确陈述假设清单且每项假设都有验证路径。在代码编写阶段，检查单文件修改行数是否超过原始需求的必要范围，是否存在未被请求的抽象或配置项。在提交前审查阶段，检查 diff 中的每一行变更是否都能直接关联到用户原始请求的描述，清理因自己的修改产生的孤立代码但保留预先存在的死代码。在验证阶段，检查是否为任务定义了可量化的成功标准，测试是否覆盖了边界条件。
值得注意的是，这套框架偏向 “谨慎优先” 而非 “速度优先”。对于简单的 typo 修复、一目了然的小修改等 trivial tasks，不需要启用完整的四原则检查流程。框架的设计目标是降低非平凡工作中的错误成本，而非降低简单任务的处理效率。使用者需要培养判断力，区分 “需要谨慎处理的任务” 和 “可以快速放行的情况”。
资料来源：主要参考 forrestchang/andrej-karpathy-skills 项目，该项目将 Karpathy 的观察整理为可直接安装的 Claude Code 技能框架，同时结合了 Arize 关于 CLAUDE.md 最佳实践的社区经验。