Claude Code 编码指南

一份受 Andrej Karpathy 观察启发的 CLAUDE.md 文件，针对大语言模型在编程时的常见误区提出约束。

背景与问题

Karpathy 指出当前 LLM 编程存在三类典型缺陷：替用户做出错误假设而不澄清；倾向于把简单问题过度工程化，动辄写出上千行可压缩到百行的代码；在修改过程中顺手改动与任务无关的注释或代码。这份指南将上述问题归纳为四个可操作的原则。

四大原则

思考先于编码

禁止静默地选择某一种解释。要求显式陈述假设，在歧义存在时给出多种解读，必要时主动反对过于复杂的方案，遇到困惑时停下并提出澄清问题，而不是带着猜测继续推进。

简洁优先

只写解决当前问题所必需的代码，不为假想需求预留扩展空间：不写仅为单次使用的抽象，不增加未要求的"灵活性"或"可配置性"，不为不可能发生的错误路径添加处理逻辑。如果 200 行能精简到 50 行，就重写。判断标准是：一位资深工程师是否会认为这段代码过度复杂。

外科手术式修改

编辑既有代码时，禁止顺手"优化"相邻代码、注释或排版，禁止重构未损坏的部分，必须匹配既有风格，即使个人偏好不同。看到无关的死代码可以指出，但不擅自删除。如果自己的改动造成了孤立代码（例如未使用的 import、变量、函数），则必须清理。判断标准是：每一处修改都能直接追溯到用户的请求。

目标驱动执行

将命令式任务转换为可验证的目标，使 LLM 能够在无人干预的情况下循环迭代直到达成标准：

命令式指令	转换为目标
添加校验逻辑	先为非法输入编写测试，再让测试通过
修复 Bug	先写能复现该 Bug 的测试，再让测试通过
重构 X	确保重构前后测试均通过

多步任务应列出简短的执行计划，每一步附带验证手段：

1. [步骤] → 验证: [检查手段]
2. [步骤] → 验证: [检查手段]
3. [步骤] → 验证: [检查手段]

强验证标准允许模型独立循环，弱标准（例如"让它跑起来"）则需要不断澄清。

安装方式

方式 A：作为 Claude Code 插件（推荐）

# 在 Claude Code 中添加市场源
/plugin marketplace add forrestchang/andrej-karpathy-skills

# 安装插件
/plugin install andrej-karpathy-skills@karpathy-skills

安装后指南会在所有项目中作为 skill 自动加载。

方式 B：直接放置 CLAUDE.md（按项目）

# 新项目
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

与 Cursor 协同使用

仓库内置了一份 Cursor 项目规则文件 .cursor/rules/karpathy-guidelines.mdc，打开 Cursor 后会自动应用相同的约束。

项目特定扩展

该指南设计为可与项目自有规则合并使用。在 CLAUDE.md 中追加如下段落即可叠加约束：

## Project-Specific Guidelines

- 使用 TypeScript strict 模式
- 所有 API 接口必须有测试覆盖
- 遵循 src/utils/errors.ts 中既有的错误处理模式

适用边界

指南偏向"谨慎优先于速度"的取舍。对于简单错别字修复、明显的一行改动这类琐碎任务，不需要套用全部原则；对于非琐碎的工作，重点在于避免代价高昂的失误。

效果判据

指南生效时通常表现为：差异中只出现用户请求的改动；很少因过度复杂而重写；在实现之前提出澄清问题；合并请求干净、最小，没有顺手的重构或"改进"。