karpathy-guidelines 技能实操:给 AI 立下「先想清楚再动手」的四条规矩
四条原则,治 AI 写代码的四种老毛病
用 AI 写代码的人都撞过这几件事:它替你做了一堆假设闷头就跑;100 行能解决的活给你铺出 1000 行的抽象层;让它改个 bug,它顺手把旁边没坏的代码也「优化」了一遍。Andrej Karpathy 在 2026 年 1 月的一条推文里把这几种毛病点得很透,multica-ai 团队据此做成了 andrej-karpathy-skills(GitHub 仓库 multica-ai/andrej-karpathy-skills,220,569 star,MIT 协议,2026-10-18 经 GitHub API 实查)——一个可以挂进 Claude Code 插件系统、也可以直接贴进任何项目 CLAUDE.md 的行为准则技能包。
这篇教程过一遍安装的两种姿势、四条原则逐条讲透、两个官方正反例对照,最后给验收方法。全部素材整理自仓库的 README、SKILL.md、EXAMPLES.md 与插件清单文件,代码与引文均逐字引自官方原文。同类的 Agent Skill 接入教程本站已上线多篇(reverse-engineer-anything、domain-modeling 等),可搭配阅读。

README「问题→解决方案」官方对照表:左列是 Karpathy 推文原话(中文站译文),右列是每条原则强制 AI 做出的行为改变
它到底改了什么:从「能力」到「行为」
大部分技能包给 AI 加的是新能力——查数据库、调 API、逆向二进制。这个仓库走的是另一条路:不加任何能力,只约束行为。仓库自述写得很直白:
A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
(一个单一的 CLAUDE.md 文件,用于改善 Claude Code 行为,源自 Andrej Karpathy 对 LLM 编码陷阱的观察。)
值得留意的是仓库对自身的克制表述——README 的 Tradeoff 章节明说:
These guidelines bias toward caution over speed. For trivial tasks, use judgment.
(这些准则偏向谨慎而非速度。琐碎任务请自行判断。)
也就是说它不打算给每个拼写修正都上全套流程,目标是「减少非琐碎工作里的昂贵错误,而不是拖慢简单任务」。这个定位决定了它的适用面:日常用 AI 做正经功能开发、bug 修复、重构的团队受益最直接;拿 AI 跑一次性脚本的场景收益有限。
安装:插件与单文件两条路
仓库给了两种接入方式,按你用的工具选。
姿势一:Claude Code 插件(官方推荐)
在 Claude Code 会话里依次执行两条命令。先加插件市场:
/plugin marketplace add forrestchang/andrej-karpathy-skills
再装插件:
/plugin install andrej-karpathy-skills@karpathy-skills
装完重启 Claude Code,技能就对所有项目生效。两个细节值得说:其一,命令里的组织名还是 forrestchang——仓库原名 forrestchang/andrej-karpathy-skills,作者后来把组织迁到了 multica-ai,GitHub 对旧地址做了 301 重定向(本站 2026-10-18 用 API 实测:请求 forrestchang/... 返回 301,最终落在 multica-ai/...),所以照 README 原命令敲依然能装上,但建议以仓库当前页面为准。其二,插件清单 .claude-plugin/plugin.json 里只注册了一个技能("skills": ["./skills/karpathy-guidelines"]),版本 1.0.0,作者署名 forrestchang——这个包很小,就是一个纯文本行为准则,没有可执行代码。
姿势二:单文件 CLAUDE.md(任何支持项目指令的 AI 工具)
不想用插件系统的,直接把仓库根目录的 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
这份文件只有 2,345 字节(GitHub API 实测),内容就是四条原则的纯文本,天然适合合并——README 明确说它「设计用于与项目特定指令合并」,你可以在后面追加自己的规则,比如「使用 TypeScript 严格模式」「所有 API 端点必须有测试」。用 Cursor 的话,仓库还提交了一份现成的项目规则 .cursor/rules/karpathy-guidelines.mdc,把项目克隆下来用 Cursor 打开即自动生效,详见仓库 CURSOR.md。
四条原则逐条过
技能本体是 skills/karpathy-guidelines/SKILL.md,2.5KB,结构就是四节。逐条拆开看,每条都对着 AI 的一个具体坏习惯。
第一条:编码前思考(Think Before Coding)
纲领原文一句话:「不要假设。不要隐藏困惑。呈现权衡。」具体到行为层,SKILL.md 列了四条:动手前把假设摆到明面上,不确定就问;存在多种解释时全部列出,不许默默选一个;有更简单的方案要说出来,该反驳时反驳;哪里看不明白就停下来,指出困惑点再要澄清。
EXAMPLES.md 给的场景是「给用户数据加导出功能」。常见的 AI 写法是直接上一个 export_users(format='json') 函数,把全量用户查出来写文件——四个假设(导出全部用户、文件落在哪里、包含哪些字段、CSV 列名怎么定)全部埋进代码没打招呼。准则之下的回应是先发一段澄清:
Before implementing, I need to clarify:
1. Scope: Export all users or filtered subset? (privacy implications)
2. Format: You mentioned "export" - did you mean: a download file in browser, a background job with email notification, or an API endpoint returning data?
3. Fields: Which user fields? (some might be sensitive)
4. Volume: How many users typically? (affects approach)
(实现之前需要澄清:范围——全部还是筛选后的子集,涉及隐私;格式——浏览器下载、后台任务加邮件通知、还是 API 返回数据;字段——哪些用户字段,有的可能敏感;量级——通常多少条,影响方案。)另一个同款例子是「让搜索变快」:AI 不问就上缓存加索引加异步 200 行,而准则要求先分清你说的是响应时间、并发吞吐还是体感速度——三种「快」对应三套完全不同的改法。
第二条:简洁优先(Simplicity First)
「用最少的代码解决问题。不做任何投机性设计。」清单很具体:不加没被要求的功能;不为一次性代码建抽象;不加没人要的「灵活性」和「可配置性」;不为不可能发生的场景写错误处理;200 行能写成 50 行的,重写。自检标准引用原话:「资深工程师会说这过度复杂吗?会,就简化。」
官方对照示例是「加一个算折扣的函数」:

EXAMPLES.md 官方正反例:同一个「算折扣」需求,左边是策略模式全家桶,右边是三行函数
左侧那种写法的问题不在语法,在于没人要求多策略、没人要求可配置——复杂度是 AI 自己「预防性」加的。官方给的补复杂度时机也写得很清楚:真出现第二种折扣类型时再重构,需求以后才来就到时候再动手。
第三条:精准修改(Surgical Changes)
「只碰必须碰的。只清理自己造成的残留。」编辑现有代码时四不做:不「改进」相邻的代码、注释和格式;不重构没坏的东西;匹配现有风格,哪怕你有别的偏好;看到无关的死代码提一嘴就好,不要删。反向的义务也有:你自己的改动产生的孤儿导入、孤儿变量、孤儿函数,要清干净。验收标准一句话:每一行改动都应该能直接追溯到用户的请求。
EXAMPLES.md 用 diff 展示了同一个 bug 修复(空邮箱字符串让校验器崩溃)的两种改法。常见的写法是顺手加 docstring、改注释、加强化的用户名校验——请求只提到邮箱,diff 里却多出一堆用户名规则。准则之下的 diff 只动处理空字符串所必需的那几行。
第四条:目标驱动执行(Goal-Driven Execution)
「定义成功标准。循环验证直到达成。」这条的依据是 Karpathy 推文里的另一段观察:
LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go.
(LLM 非常擅长循环执行直到达成特定目标……不要告诉它该做什么,给它成功标准,然后看着它完成。)
落到操作层就是把指令式任务翻译成可验证目标:

SKILL.md 的官方转换表:右列的写法让 AI 有明确的「完成」可判定,能自己循环到通过为止
多步任务则要求先报一个带验证点的计划,格式照抄 SKILL.md:
1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check]
每步动作后面跟着「怎么验证这步成了」。文档里的结论是:强标准让模型能独立循环,弱标准(「让它工作」)逼着人来回澄清。
怎么知道它起作用了
README 的「How to Know It's Working」给了四个可观察的信号:diff 里不必要的改动变少,只有请求的变更出现;因过度复杂导致的重写变少,代码第一版就写得克制;澄清问题出现在动手之前,而不是出错之后;PR 干净精简,没有顺带的重构和「改进」。把这几条当团队验收清单用,比「感觉 AI 听话了」实在得多。
边界与现状
几件如实要说的事。仓库最后一次提交停在 2026-04-20(GitHub API pushed_at 字段,2026-10-18 实查),此后没有新改动——四条原则本身是行为准则,不依赖具体模型版本,内容至今仍然适用,但别指望它频繁更新。插件命令里的组织名(forrestchang)是迁移前的旧地址,靠 GitHub 重定向兜底,遇到 404 时把组织名换成 multica-ai 即可。另外这套准则只能约束「读了它的模型」:它对 Claude Code、Cursor 这类会把项目指令注入上下文的工具有效,对一个不读 CLAUDE.md 的裸 API 调用没有任何强制力——准则不是护栏代码,是给模型的叮嘱。
小结
这个仓库的价值在于把 Karpathy 的观察翻译成了可以直接挂载的规则文件:两种安装姿势覆盖了 Claude Code 插件用户和任意工具用户,四条原则每条都有正反例兜底,验收信号可观察。如果你正被 AI 的「自作主张」和「过度工程」困扰,花两分钟装上它,比反复在提示词里写「不要乱改代码」省事。本站同系列已上线 reverse-engineer-anything(逆向分析)、rea-changelog-update(Release Notes 生成)等技能实操,可搭配阅读。
本文步骤、代码与引文依据 multica-ai/andrej-karpathy-skills 仓库 README / README.zh.md / SKILL.md / EXAMPLES.md / .claude-plugin 清单整理(2026-10-18 经 GitHub API 实查),版权归原作者所有。