Karpathy-Inspired Claude Code Guidelines

大语言模型（LLM）在编程辅助上展现出巨大潜力，但其生成的代码常常伴随着令人头疼的问题。正如前特斯拉AI总监安德烈·卡帕西（Andrej Karpathy）所尖锐指出的，这些模型普遍存在三大顽疾：

• 擅自做主：模型会基于错误的假设直接执行，既不核实也不澄清，更不会主动指出需求中的矛盾或提供替代方案。
• 过度设计：倾向于用上千行臃肿的代码和复杂的抽象去解决一个百行内就能搞定的问题，堆砌未经请求的“灵活性”和冗余的错误处理。
• 误伤无辜：在修改代码时，常常会“顺手”改动甚至删除与任务无关的注释、格式或逻辑，破坏原有代码的上下文。

为系统性地解决这些问题，社区开发者提炼出了一份名为 CLAUDE.md 的行为指南。这份简洁的文档包含四项核心原则，旨在引导像Claude这样的AI助手产出更可靠、更简洁、更精准的代码。

原则一：先思考，后编码

这条原则的核心是显式推理，杜绝AI的“自作聪明”。

• 明确假设：如果对需求有不确定之处，必须清晰地陈述出来，并主动询问，而不是自行猜测。
• 呈现选项：当需求存在多种解读可能时，应列出所有合理的方案及其权衡，而非默默选择其一。
• 敢于质疑：如果发现有更简单、更直接的实现路径，应该明确提出来，而不是盲目遵循看似复杂的指令。
• 及时止步：一旦遇到无法理解的部分，应立即停止生成，并具体说明困惑点，请求用户澄清。

原则二：简洁至上

对抗过度工程化的本能，追求最小可行实现。

• 严守边界：只实现明确要求的功能，绝不添加任何额外的、推测性的特性。
• 拒绝无谓抽象：对于仅使用一次的逻辑，不要创建新的类、接口或函数来包装它。
• 克制“灵活性”：除非用户明确提出，否则不要添加配置项或可扩展点。
• 务实处理异常：只为真实可能发生的错误场景编写处理逻辑，忽略那些理论上存在但实践中不可能出现的情况。
• 持续精简：如果一段代码能从200行压缩到50行而不损失功能，就必须重写。评判标准很简单：一位资深工程师会觉得这段代码太复杂吗？

原则三：精准修改

在编辑现有代码库时，必须像外科手术一样精确。

• 专注任务：只修改与当前任务直接相关的代码行，绝不“优化”邻近的、风格不同的或看似不完美的代码。
• 尊重现状：即使你有更好的编码风格，也应严格遵循项目现有的规范。
• 谨慎清理：如果在修改过程中产生了未使用的变量、函数或导入，应当清理掉这些“自己制造的垃圾”。但对于原本就存在的死代码，只能指出，不能擅自删除。
• 可追溯性：每一处改动都必须能清晰地回溯到用户的原始需求。

原则四：目标驱动执行

将模糊的指令转化为可验证的成功标准，利用LLM擅长的“循环直到成功”能力。

与其给出“修复这个bug”这样模糊的指令，不如将其转化为：

1. 编写一个能复现该bug的测试用例。
2. 修改代码，使该测试用例通过。

这种模式同样适用于其他任务：

• “添加验证” → “为无效输入编写测试，然后让它们通过”。
• “重构X” → “确保重构前后的所有测试都能通过”。

对于复杂的多步骤任务，AI应先输出一个简要计划，每一步都附带明确的验证点，确保整个过程可控、可测。

如何应用这份指南？——完整的安装与使用方法

你可以通过以下两种方式，将这份指南立即应用到你的开发流程中：

选项A：作为Claude代码插件全局安装（推荐）
这将使指南在你所有的项目中生效。

claude plugins add https://github.com/forrestchang/andrej-karpathy-skills

选项B：在单个项目中使用 CLAUDE.md 文件

• 新建项目：在项目根目录下执行以下命令，创建 CLAUDE.md 文件。

  curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
  

• 现有项目：如果你想将指南追加到已有的 CLAUDE.md 文件末尾，可以运行：

  echo "" >> CLAUDE.md
  curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
  

此外，你还可以在 CLAUDE.md 中添加项目特定的规则，例如：

## 项目特定指南

- 使用TypeScript严格模式
- 所有API端点必须有测试
- 遵循`src/utils/errors.ts`中现有的错误处理模式

这份指南真的有效吗？

根据设计者的观察，当指南生效时，你会看到以下变化：

• 代码差异（diff）；
• 因过度复杂化而导致的返工大幅减少，代码第一次提交就是简洁的；
• 澄清性问题出现在实现之前，而不是在错误发生之后；
• 拉取请求（PR），没有附带的、未经请求的“改进”。

需要强调的是，这份指南偏向于谨慎而非速度。对于简单的拼写修正或明显的一行修改，无需套用全部规则。它的核心目标是在处理非平凡的复杂任务时，减少那些代价高昂的AI“自由发挥”错误，让你的开发流程更高效、更可靠。