--- title: "Karpathy 定制 CLAUDE.md 的指令设计模式解析" route: "/posts/2026/04/11/karpathy-claude-md-instruction-design/" canonical_path: "/posts/2026/04/11/karpathy-claude-md-instruction-design/" canonical_url: "https://blog2.hotdry.top/posts/2026/04/11/karpathy-claude-md-instruction-design/" markdown_path: "/agent/posts/2026/04/11/karpathy-claude-md-instruction-design/index.md" markdown_url: "https://blog2.hotdry.top/agent/posts/2026/04/11/karpathy-claude-md-instruction-design/index.md" agent_public_path: "/agent/posts/2026/04/11/karpathy-claude-md-instruction-design/" agent_public_url: "https://blog2.hotdry.top/agent/posts/2026/04/11/karpathy-claude-md-instruction-design/" kind: "research" generated_at: "2026-04-11T19:18:12.647Z" version: "1" slug: "2026/04/11/karpathy-claude-md-instruction-design" date: "2026-04-11T19:28:11+08:00" category: "ai-systems" year: "2026" month: "04" day: "11" --- # Karpathy 定制 CLAUDE.md 的指令设计模式解析 > 深入解析 Andrej Karpathy 定制的 CLAUDE.md 配置文件，提取 AI 助手指令工程的结构化设计模式与工程落地要点。 ## 元数据 - Canonical: /posts/2026/04/11/karpathy-claude-md-instruction-design/ - Agent Snapshot: /agent/posts/2026/04/11/karpathy-claude-md-instruction-design/index.md - 发布时间: 2026-04-11T19:28:11+08:00 - 分类: [ai-systems](/agent/categories/ai-systems/index.md) - 站点: https://blog2.hotdry.top ## 正文 在 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 的行为可预测、可控制、可度量，同时保持足够的灵活性以适应不同任务场景的需求。 --- **资料来源**： - forrestchang/andrej-karpathy-skills: https://github.com/forrestchang/andrej-karpathy-skills ## 同分类近期文章 ### [MarkItDown 多格式文档转 Markdown 的工程实践](/agent/posts/2026/04/12/markitdown-multi-format-conversion/index.md) - 日期: 2026-04-12T02:49:49+08:00 - 分类: [ai-systems](/agent/categories/ai-systems/index.md) - 摘要: 深入解析微软 MarkItDown 的插件架构、依赖分组与流式处理设计，提供批量转换的工程参数与配置建议。 ### [VoxCPM2: Tokenizer-Free多语言语音生成的技术架构与部署实践](/agent/posts/2026/04/12/voxcpm2-tokenizer-free-multilingual-tts/index.md) - 日期: 2026-04-12T02:25:59+08:00 - 分类: [ai-systems](/agent/categories/ai-systems/index.md) - 摘要: 深度解析VoxCPM2如何通过tokenizer-free架构在连续潜空间完成跨语言TTS、声音设计与克隆，并给出生产环境部署的关键参数。 ### [Archon：开源 Harness 构建器如何实现 AI 编码的确定性工作流](/agent/posts/2026/04/12/archon-ai-coding-harness-builder/index.md) - 日期: 2026-04-12T00:50:16+08:00 - 分类: [ai-systems](/agent/categories/ai-systems/index.md) - 摘要: 解析首个开源 AI 编码 harness builder 的架构设计，探讨基于 YAML 的可复现工作流与隔离测试框架的工程实践。 ### [Multica 托管代理平台的任务调度与进度追踪机制解析](/agent/posts/2026/04/12/multica-agent-task-scheduler/index.md) - 日期: 2026-04-12T00:25:54+08:00 - 分类: [ai-systems](/agent/categories/ai-systems/index.md) - 摘要: 解析开源托管代理平台 Multica 的任务分配、进度追踪与技能叠加机制，给出工程化参数与监控要点。 ### [小模型自动化代码审计：漏洞发现的效果与成本差异实战](/agent/posts/2026/04/12/small-models-automated-code-audit-cost-performance/index.md) - 日期: 2026-04-12T00:00:00+08:00 - 分类: [ai-systems](/agent/categories/ai-systems/index.md) - 摘要: 对比大语言模型与小参数模型在漏洞发现任务上的效果与成本差异，给出工程化落地的参数与决策清单。