让 Claude Code 少犯错的编码行为指南-开发者社区

让 Claude Code 少犯错的编码行为指南

【免费下载链接】andrej-karpathy-skillsA single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.项目地址: https://gitcode.com/GitHub_Trending/an/andrej-karpathy-skills

让 AI 修一个"空邮箱导致崩溃"的 bug，它顺手把整个函数的引号重排了，加了一堆没人要的类型注解，diff 里三百行改动只有一行和 bug 有关。andrej-karpathy-skills 就是为这种场面准备的：一个源自 Karpathy 对 LLM 编码陷阱观察的指南，用单一的 CLAUDE.md 文件约束 Claude Code 的编码行为。

📌 这是一个什么文件的项目

andrej-karpathy-skills 仓库里没有什么框架，核心是一份可以直接合并进任何项目的说明文件。它的来源是 Andrej Karpathy 的公开观察：模型会代你做错误假设然后不假思索地执行，偏爱堆砌抽象，把一百行能解决的事写成一千行的臃肿架构，还会改动自己并不理解的注释和代码。

这个项目的做法很直接：把四条行为准则写进 CLAUDE.md，让 Claude Code 在开始编码前先读到它。你不需要理解 LLM 的内部机制，把文件放进项目，助手就会按这份纪律行事。把 CLAUDE.md 放进项目根目录，下一条指令就会受影响。

🩺 你可能见过的四个症状

需求有歧义时，AI 默默选一种解释直接开写，方向偏差到代码评审时才暴露
一个三十行的计算被包成抽象类加配置对象，没人敢读也没人敢改
修一个小 bug 的 diff 混入格式重排、注释改写、无关重构，审查成本翻倍
验收标准是"让它能跑"，AI 反复循环却说不清做到哪一步，你也无法判断

下次 diff 超出预期，先对照这份清单找原因。

🗺️ 四条原则如何联动

四条原则分别卡在流程的四个关口：想清楚、写简单、改精准、验到位。**前两条管"写什么"，后两条管"改多少、何时算完"。**对照这张图，你可以检查 AI 是否跳过了提问环节。

🚀 三分钟落地：两种安装方式

# 方式一：Claude Code 插件（推荐，全局生效） /plugin marketplace add forrestchang/andrej-karpathy-skills /plugin install andrej-karpathy-skills@karpathy-skills # 方式二：CLAUDE.md 放进单个项目 git clone https://gitcode.com/GitHub_Trending/an/andrej-karpathy-skills cp andrej-karpathy-skills/CLAUDE.md 你的项目路径/CLAUDE.md

方式一把指南装成 Claude Code 插件，你机器上的所有项目都能用；方式二只影响单个项目，但文件随仓库分发，团队共享同一套纪律。已有 CLAUDE.md 的项目把内容追加到文件末尾即可，指南本身设计为可合并。

落地方式	生效范围	适合谁
Claude Code 插件	全局，跨项目	主力使用 Claude Code 的开发者
CLAUDE.md 放项目根目录	单个项目，随仓库分发	想让团队共享同一套编码纪律的项目

把上面对应的命令粘进终端，今天就能用上。

🎬 四个真实场景里的表现

场景一：模糊需求"导出用户数据"

你只说了"加个导出功能"，AI 默认导出全部用户、猜了文件格式和字段，写完才发现敏感字段也被导出了。装上指南后，它先抛出四个问题：导出范围、交互形态、包含哪些字段、数据量级，然后给出最简方案——一个分页 JSON 接口——等你确认再动手。

场景二："加一个折扣计算"

AI 习惯性地搬出策略模式、抽象基类、配置对象，几十行代码只为了算一次乘法。指南要求先自问"资深工程师会不会说这太复杂"，结果收敛成一个三行函数；真出现多种折扣类型时再重构不迟。

场景三："修一下空邮箱崩溃"

AI 顺手给整个校验函数加了类型注解和文档字符串，还给用户名补了一堆没人要求的校验。指南规定每行改动都要能追溯到你的原始请求，所以最终 diff 只有修空值的两行；它顺带发现的无关死代码只会在对话里提一句，不会直接删。

场景四："修认证系统的 bug"

"让它工作"是弱标准，AI 会不停回头问或盲目改代码。指南把它翻译成可验证目标：先写一个能复现 bug 的测试，改到测试通过，再跑全量测试确认没有回归。每一步都有明确的验证动作，你可以只看结果。

把你最常踩的场景直接告诉 AI，并要求"按 karpathy 四原则处理"。

⚖️ 同一个需求，两种交付

没装指南时的典型产物：

from abc import ABC, abstractmethod class DiscountStrategy(ABC): @abstractmethod def calculate(self, amount: float) -> float: ... class PercentageDiscount(DiscountStrategy): def __init__(self, pct): self.pct = pct def calculate(self, amount): return amount * self.pct / 100

装了指南之后：

def calculate_discount(amount: float, percent: float) -> float: """计算折扣金额。percent 取 0-100。""" return amount * (percent / 100) # 使用 discount = calculate_discount(100.0, 10.0) # 10 美元折扣

两者功能一样，差别在代码能否一眼读懂、三行改完。验收时问一句：每一行改动能追溯到我的需求吗。

✅ 指南生效的信号

diff 里只剩下你要求的改动，没有顺带的格式和注释调整
第一版代码就是简单版本，不用为过度设计返工重写
澄清问题出现在动手之前，而不是错误修复之后
PR 干净精简，没有夹带的重构或"改进"

把这四条贴进你的 PR 模板，当作合入前的验收项。

💡 一个反直觉的判断

过度工程化的代码其实不算"错"——它遵循设计模式，符合最佳实践。问题出在时机：复杂性被提前塞进不需要它的地方，代码更难读、测试更难写，改动更慢。简单版本反而更容易理解和测试，需要时随时可以重构。

另一个反直觉点：给 LLM 步骤清单不如给它成功标准。"修好它"会让它不断回头问，"写一个复现 bug 的测试并让它通过"能让它自己循环验证直到结束。好的代码是简单解决今天的问题，而不是提前解决明天的问题。

下个大任务开工前，先花两分钟把成功标准写出来。

📂 仓库里该看哪几个文件

CLAUDE.md：主指南文件，四原则的完整条文，放进项目根目录即可生效
EXAMPLES.md：四组真实前后对照，每个原则配完整案例
README.zh.md：中文说明与安装步骤
skills/karpathy-guidelines/SKILL.md：技能化定义文件，插件安装时加载的就是它
CURSOR.md：在 Cursor 中应用同一套指南的方法

先从 CLAUDE.md 读起，十分钟就能通读。

今晚就能开始

diff 变小，代码评审时间省在刀刃上
第一版代码更简单，减少过度设计导致的返工
澄清前移，需求偏差在写代码之前就被拦下
验收有测试背书，"修好了"不再靠感觉

把 CLAUDE.md 放进你手头最乱的那个项目，下一个任务就能见效。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

让 Claude Code 少犯错的编码行为指南