andrej-karpathy-skills:把 AI 的“顺手重构“管住

andrej-karpathy-skills:把 AI 的"顺手重构"管住

【免费下载链接】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 修一个空指针,diff 回来,整个模块被它重构成了策略模式,注释也换了一套说法。andrej-karpathy-skills 是写给 Claude Code 的行为指南,用四条规则管住 LLM 的乱假设、过度设计和顺手重构,直接影响你拿到的 LLM 代码质量。

一份单文件的 AI 编程规范

它不是框架,也不是代码库,就是一个CLAUDE.md文件,内容是四条行为规则。来源是 Andrej Karpathy 对 LLM 编程缺陷的公开观察:模型会替你默默做假设,然后一路跑下去,不核对、不澄清、不指出矛盾;爱把抽象层层堆高,百行能解决的事写成千行;修 bug 时顺手改动并不相关的注释和代码。这个项目的做法很直接:把观察逐条翻译成 AI 能执行的指令。

🧭 四条规则逐条拆

把假设写在前面

最常见的翻车是这样:你说"让搜索变快",AI 默默选了"降低响应时间"这一种解释,加缓存、加索引、改异步,一路写下去,你发现它理解的根本不是你要的那个"快"。规则要求它反过来:假设必须显式说出来;存在多种解释就全部列出来,不许私下挑一个;有更简单的做法要主动讲;遇到不清楚的,停下,说清哪里不清楚,然后问。落地动作只有一个——让它在动手前交一份"假设清单",你确认一句,它再写代码。

拿不准就停下来问,比写完再返工便宜。

只写解决问题的代码

加一个算折扣的函数,回来的可能是抽象基类、两个策略子类、一个配置数据类,调用它要多写三十行样板代码。规则把话说死:不实现没被要求的功能,不为只用一次的代码建抽象,不加没人要的"灵活性"和"可配置性",不处理不可能发生的错误场景。写完自问一句"资深工程师会不会说这太复杂",答案是会,就重写。

# 反例:为唯一一次折扣计算引入策略模式 class DiscountStrategy(ABC): @abstractmethod def calculate(self, amount): ... # 改法:一个函数就够 def calculate_discount(amount, percent): return amount * percent / 100

够用就停手,复杂度留给真正需要的日子。

只动该动的行

修"空邮箱导致校验器崩溃",回来的 diff 里注释换了、文档串加了、还多出一段没人要的用户名校验,你得花不少时间确认修复逻辑有没有被动过。规则是:不"顺手改进"相邻的代码、注释和格式;不重构没坏的东西;现有风格照抄,哪怕你会写得更好;发现无关的死代码,提一句,但别删。自己改动造成的孤儿代码要清掉,别人留下的不动。

# 反例:修空邮箱崩溃,顺手加了没人要的用户名校验 if not user_data.get('email'): raise ValueError("Email required") if len(user_data.get('username')) < 3: raise ValueError("Username too short") # 改法:只动空邮箱这一处判断 if not (user_data.get('email') or '').strip(): raise ValueError("Email required")

每行改动都要能对应到这次的需求。

先定义"什么叫做完"

"修复认证系统"这类指令,默认的回应是"我会审查代码、找出问题、做些改进",然后开始一轮又一轮没有终点的修改。规则要求把祈使句翻译成可验收的目标:"加校验"改成"为无效输入写测试,然后让它通过";"修 bug"改成"先写一个能复现它的测试,再修到通过";"重构 X"改成"保证重构前后测试都是绿的"。多步任务让 AI 先给一个简短计划,每一步后面跟一个验证方式。标准写得清楚,它就能自己循环;标准模糊,你就得全程陪聊。

有验收标准,它才能自己转起来。

🔁 一组前后对照:需求澄清

同一个请求:"加一个导出用户数据的功能。"

传统输出:直接落地一段导出函数——默认导出全部用户、字段固定、写进本地文件,每个假设都不是你要的,返工从确认字段开始。

约束后的输出:

动手前确认四件事:

1. 范围:全部用户,还是筛选后的子集?
2. "导出"具体指浏览器下载、后台任务加邮件,还是 API 直接返回?
3. 包含哪些字段?有些可能敏感。
4. 用户量级大概多少?它决定实现方式。

最简单的做法是一个返回分页 JSON 的接口;文件导出需要更多信息。你倾向哪种?

差别不在代码质量,而在假设的归属:前者的假设是 AI 替你做的,后者的假设是你确认过的。审一份确认过假设的实现,比审一份自己脑补的实现快得多。

接入方式:Claude Code 配置最短路径

两条路,都只要一步命令。插件方式一次配置、所有项目生效;文件方式把规则放进单个项目。

# 方式一:Claude Code 插件,一次配置全部项目生效 /plugin marketplace add forrestchang/andrej-karpathy-skills /plugin install andrej-karpathy-skills@karpathy-skills # 方式二:clone 仓库,将 CLAUDE.md 放入项目根目录 git clone https://gitcode.com/GitHub_Trending/an/andrej-karpathy-skills

已有CLAUDE.md的项目,把规则追加进去就行,它本来就是为合并项目专属指令而设计的。仓库里还有 skills 目录下的 SKILL.md 与 CURSOR.md,供 Cursor 等其他工具复用同一套规则。

适用边界:什么时候该用,什么时候不用

该用:非平凡的功能开发、多人协作的项目、你希望 diff 里每一行改动都有明确理由的场景。可以不用:拼写错误、明显的单行修复、用完即弃的原型。规则本身偏向"谨慎优先于速度",给琐碎任务上全套流程,只会拖慢节奏。

收束

工具只有一个文件,真正起作用的是那套判断顺序:先想清楚,简单实现,精确修改,用验收标准收尾。好的代码是简单解决今天的问题,而不是提前解决明天的问题。

【免费下载链接】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