当前位置： 首页 > news >正文

一天一个开源项目（第108篇）：Andrej Karpathy Skills - 用一个 CLAUDE.md 文件修复 LLM 编码的四个顽疾

news 2026/5/31 20:18:40

引言

“LLMs excel at looping until they meet specific goals — so provide success criteria rather than imperative instructions.”

这是"一天一个开源项目"系列的第108篇文章。今天带你了解的项目是andrej-karpathy-skills。

这个项目非常特别：它的核心不是一个工具、框架或库——就是一个 CLAUDE.md 文件。

故事起点是 Andrej Karpathy 在大量使用 Claude Code 之后发的一个 X 帖子，记录了他发现 LLM 在编码任务中反复出现的失效模式：不问清楚就动手、把简单问题工程化成复杂方案、顺手改了不该改的代码……

multica-ai 团队把这些观察提炼成了四条可操作的行为准则，打包进一个 CLAUDE.md 文件——你把它放进项目，Claude Code 就会改变行为方式。同时提供 Claude Code 插件和 Cursor 规则两种格式，覆盖主流 AI 编码工具。

这个项目很好地回答了一个常被忽视的问题：与其教 LLM 具体做什么，不如告诉它怎么思考。

你将学到什么

  • Karpathy 观察到的 LLM 编码四大失效模式是什么
  • 四条行为准则的具体内容与实际案例
  • 三种安装方式：独立 CLAUDE.md / Claude Code 插件 / Cursor 规则
  • 为什么"给出成功标准"比"给出操作步骤"更有效
  • 如何验证这套准则是否真的在起作用

前置知识

  • 使用过 Claude Code 或 Cursor 等 AI 编码工具
  • 有一定的日常开发经验，能感受到 LLM 编码的痛点

项目背景

项目简介

andrej-karpathy-skills 的核心是一份行为配置文件。它的设计哲学来自一个关键洞察：

LLM 编码的问题，往往不是能力不够，而是行为没有约束。

模型有能力写简单的代码，但没人告诉它"不要写复杂的"。模型有能力先问清楚需求，但没有压力让它问。模型知道不该动无关的代码，但"顺便改一下"的习惯很难克制。

这份 CLAUDE.md 文件把这些约束显式化，让每次对话都带着这些行为准则进入上下文。

项目同时提供了三种分发格式，适配不同的使用场景和工具链。

作者/团队介绍

  • 维护方：multica-ai（Multica AI 团队）
  • 灵感来源：Andrej Karpathy 在 X 上分享的 LLM 编码使用笔记
  • 原始作者：该 CLAUDE.md 内容最初由 forrestchang 整理，multica-ai 将其扩展为插件生态

关于 Andrej Karpathy：OpenAI 联合创始人之一，前特斯拉 AI 负责人，现独立研究者，以 nanoGPT、Neural Networks: Zero to Hero 等教学项目在 AI 社区广为人知。他对 AI 工具的实际使用反馈，在业内有很强的参考价值。

项目数据

  • 📄 核心文件:CLAUDE.md（行为准则）
  • 🔌 Claude Code 插件 + Cursor 规则
  • 📖 附带:EXAMPLES.md（四原则的对比示例）
  • 📄 License: MIT
  • 🌐 仓库: multica-ai/andrej-karpathy-skills

主要功能

核心作用

这份 CLAUDE.md 直接对抗 LLM 编码中最常见的四个失效模式：

LLM 编码常见失效 ├── 静默假设（不问清楚直接动手） ├── 过度工程化（把简单问题变复杂） ├── 扩大改动范围（顺手改了不相关代码） └── 模糊执行（缺乏可验证的完成标准） ↓ CLAUDE.md 注入四条行为准则 行为改变 ├── 编码前先思考（Think Before Coding） ├── 简单优先（Simplicity First） ├── 外科手术式修改（Surgical Changes） └── 目标驱动执行（Goal-Driven Execution）

快速开始

方式一：Claude Code 插件（推荐，全局生效）

/plugin marketplaceaddforrestchang/andrej-karpathy-skills /plugininstallandrej-karpathy-skills@karpathy-skills

安装后对所有项目生效，无需在每个项目中单独配置。

方式二：项目级 CLAUDE.md（只对当前项目生效）

cdyour-projectcurl-oCLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

如果项目中已有 CLAUDE.md，可手动将内容合并进去。

方式三：Cursor 规则

仓库中已包含.cursor/rules/karpathy-guidelines.mdc，设置了alwaysApply: true。将该文件复制到你的项目中即可：

mkdir-p.cursor/rulescppath/to/karpathy-guidelines.mdc .cursor/rules/

验证是否生效：打开 Cursor → Settings → Rules，查看规则是否出现在列表中。

验证准则是否在起作用的信号：

  • 实现前 Claude 会主动提问而不是直接开始写
  • PR diff 里的改动更干净，只涉及被请求的部分
  • 不再出现"顺便优化了一下"的代码变动

四条准则详解

准则一：编码前先思考（Think Before Coding）

针对的问题：LLM 在遇到模糊需求时倾向于做出隐性假设并直接执行，而不是把不确定性暴露出来。

错误行为示例：

用户: 给我导出用户数据的功能 LLM: [直接开始写代码] → 假设导出 CSV，假设所有字段，假设同步下载 → 但用户实际需要的是后台任务 + 特定字段 + JSON 格式

正确行为（准则要求先把不确定性表面化）：

用户: 给我导出用户数据的功能 LLM: 在开始之前，有几个问题需要确认： 1. 范围：导出所有用户还是按条件过滤？ 2. 格式：CSV / JSON / Excel？ 3. 交付方式：浏览器直接下载、后台任务发邮件，还是 API 接口？ 4. 字段：需要哪些字段？是否包含敏感数据？

另一个典型案例——"让搜索更快"有三种完全不同的含义：

解释实际需求解决方案
响应时间API 返回慢加索引、缓存、优化查询
吞吐量并发量高水平扩展、队列
体感速度用户觉得慢预加载、骨架屏、即时反馈

三种解释需要完全不同的方案，任何一个都不能"默认"。

准则要求：当存在多种合理解释时，呈现所有解释让用户选择，而不是悄悄选一个。在真正困惑时停下来说"我不确定这里应该如何处理"，而不是硬撑下去。

准则二：简单优先（Simplicity First）

针对的问题：LLM 有强烈的过度工程化倾向，在复杂性真正需要之前就引入抽象、框架和"灵活性"。

错误行为示例——折扣计算：

# 用户要求：实现一个简单的折扣计算# ❌ LLM 给出的"方案"（10 倍代码量）：classDiscountStrategy(ABC):@abstractmethoddefcalculate(self,price:float)->float:...classPercentageDiscount(DiscountStrategy):def__init__(self,config:DiscountConfig):...defcalculate(self,price:float)->float:...classDiscountCalculator:def__init__(self,strategy:DiscountStrategy):...defapply(self,cart:Cart)->float:...# 工厂类、配置类、注册器……# ✅ 实际需要的（1 个函数）：defapply_discount(price:float,discount_pct:float)->float:returnprice*(1-discount_pct/100)

另一个示例——“保存用户偏好设置”：

❌ LLM 实现了： - 带失效时间的缓存层 - 输入验证（用户没要求） - 冲突合并逻辑（用户没遇到这个问题） - 变更通知系统（用户没提到） ✅ 实际需要的： - 把偏好写入数据库的一个函数

准则给出的判断标准：

“一个 senior 工程师看到这段代码，会说它过于复杂吗？”

如果 200 行代码可以写成 50 行，就重写成 50 行。

核心格言：

“Good code is code that solves today’s problem simply, not tomorrow’s problem prematurely.”

过早引入的复杂性不只是浪费，还会让代码更难理解、引入更多 bug，哪怕它遵循了正确的设计模式。

准则三：外科手术式修改（Surgical Changes）

针对的问题：LLM 做"顺路重构"——修复一个 bug 时，顺便改了引号风格、加了类型注释、重命名了变量、整理了导入顺序。

这个行为看起来是好意，但实际上有两个严重问题：

  1. 让 diff 变得难以审查：reviewer 无法区分哪些改动是 bug 修复、哪些是"顺便"
  2. 引入意外 regression：每一行未经要求的改动都是潜在的风险点

正确的做法：

# 原始代码（有 bug，同时有一些"不完美"之处）defcalculate_total(items):total=0foriteminitems:total+=item['price']# 单引号returntotal# 缺少类型注释# ❌ LLM 的"全面改善"：defcalculate_total(items:list[dict])->float:# 加了类型注释"""Calculate total price of items."""# 加了文档字符串total:float=0.0# 改了变量类型foriteminitems:total+=item["price"]# 改成双引号（"风格统一"）returntotal# ✅ 只修复 bug（假设 bug 是 items 为空时的问题）：defcalculate_total(items):ifnotitems:# 只加了这一行return0total=0foriteminitems:total+=item['price']# 保持原有风格不变returntotal

准则的具体要求：

  • 每一行改动都要能追溯到用户的请求
  • 匹配现有代码风格，即使你更喜欢另一种
  • 不要改进"路过"的代码，除非被明确要求
  • 只清理你的改动产生的无用导入/变量，不要动原有的

准则四：目标驱动执行（Goal-Driven Execution）

针对的问题：LLM 在接到模糊任务时，会给出看起来很全面但缺乏可验证性的计划。

模糊计划的示例：

任务: "重构 auth 模块" ❌ 模糊计划: 1. 审查现有代码 2. 识别问题 3. 改进结构 4. 运行测试 → 没有任何一步有明确的完成标准

准则要求把任务转化为可验证的目标：

任务: "修复登录 bug" ✅ 目标驱动计划: 步骤 1: 写一个复现 bug 的失败测试 验证点: 测试确实在当前代码上失败 步骤 2: 实现修复 验证点: 刚才写的测试现在通过 步骤 3: 运行完整测试套件 验证点: 没有新的回归 → 每步都有明确的"完成"定义

另一个示例：

任务: "重构 auth 模块" ✅ 具体化后: 1. 所有现有测试通过（记录基线） 2. 抽取 TokenService（验证：独立单元测试通过） 3. 重构 AuthController 使用 TokenService（验证：集成测试通过） 4. 所有原有测试仍然通过（无回归）

Karpathy 的核心洞察：

LLM 最擅长的事是"循环直到满足特定目标"——因此，提供成功标准比提供操作步骤更有效。

命令式指令（“先做 A，然后做 B，然后做 C”）在出错时会让 LLM 不知道该怎么处理。声明式目标（“这个测试要通过”、“这个接口要可调用”）让 LLM 可以自主决定路径，同时有清晰的完成标准。

为什么是一个文件，而不是一个工具？

这个项目的设计选择本身就值得深思。面对 LLM 编码的行为问题，可以有很多种解决方案：

  • 构建一个代理框架来约束行为
  • 开发后处理工具来检测和修正
  • 训练一个更好的模型

andrej-karpathy-skills 选择的是最简单的那个：一个文本文件，放进项目里，让 LLM 自己读自己执行。

这个选择本身就是对"简单优先"原则的最好示范——用最少的机制，解决今天的问题。而且，文本文件有一个工具无法比拟的优势：可以随时阅读、理解和修改，没有任何黑盒。

项目地址与资源

官方资源

  • 🌟GitHub: https://github.com/multica-ai/andrej-karpathy-skills
  • 📄原始 CLAUDE.md: 直接curl下载即可使用
  • 📖示例文档:EXAMPLES.md（四原则的对比示例，推荐阅读）

适用人群

  • Claude Code / Cursor 日常用户：希望减少 LLM 的过度工程化和不必要的代码改动
  • 团队工程效能负责人：在团队 CLAUDE.md 中集成这套行为规范，统一 AI 辅助编码的行为基准
  • 追求代码可审查性的开发者：厌倦了 LLM 生成的"超级 diff"，想要干净的、只包含请求变更的 PR

总结与展望

核心要点回顾

  1. 来源：直接提炼自 Karpathy 对 LLM 编码失效模式的一手观察，有真实使用基础
  2. 四条准则：
    • 编码前先思考：把隐性假设变成显性问题，而不是悄悄选一个
    • 简单优先：写解决今天问题的最少代码，不预建"灵活性"
    • 外科手术式修改：每行改动都能追溯到请求，不做顺路重构
    • 目标驱动执行：给成功标准，不给操作步骤
  3. 三种安装格式：CLAUDE.md（项目级）/ Claude Code 插件（全局）/ Cursor 规则
  4. 核心哲学：LLM 最擅长循环直到达成目标——给目标，不给步骤
  5. 自我示范：用最简单的方式（一个文件）解决问题，自身就是"简单优先"原则的体现

一句话评价

andrej-karpathy-skills 做了一件看似微小但影响深远的事：把"怎么用好 LLM 写代码"的工程智慧，压缩进一个任何人都能读懂、放进任何项目的文本文件——而这个文件本身，就是它所倡导的简单哲学的最好证明。

欢迎来我的个人主页找到更多有用的知识和有趣的产品

http://www.cnnetsun.cn/news/2517993.html

相关文章：

  • 免费图片去水印工具有哪些？2026 在线图片去水印软件推荐指南
  • 3步掌握Internet Archive Downloader：突破数字图书馆限制的终极浏览器扩展工具
  • 终极B站直播助手：3分钟搭建智能直播间，效率提升300%
  • CANN/pypto：MatmulAllReduce与RMSNorm融合算子
  • BuckyClient性能优化：sample与aggregationInterval参数调优实践
  • ElevenLabs支持广西话吗？2024最新实测结果曝光：仅2个API参数决定能否合成地道“梧州腔”
  • 英伟达VR200机柜PCB价值量同比+233%：AI硬件主线如何被引爆？
  • 从“水本原论”的时空错位看西方哲学叙事的建构与AI时代的数据霸权
  • SABIC工程塑料创新材料解决方案与发展前景分析
  • 2026年，揭秘浙江废铝回收界的明星企业！
  • Prompt Engineering、Context Engineering 与 Harness Engineering 的异同点
  • 8355 法还原魔方 – 解魔方不用死记公式
  • 为什么92%的中小企业DeepSeek私有化项目卡在推理延迟＞800ms？——基于TensorRT-LLM的4层加速调优公式（含吞吐量提升3.8倍实测数据）
  • TVA模型中的QKV投影层通道对齐缩放因子计算
  • “跳出机器人思维的局限”：如何防止人工智能退化你的大脑能力
  • NVIDIA-JetSonAGX-Thor系统安装-Ubuntu24.04（五）无人机导航开发环境配置
  • Sharp-dumpkey：三分钟获取微信数据库AES密钥的终极C解决方案
  • 效率飙升61%！南洋理工南科大新方法，让无人机边飞边“转头”，探索又快又准
  • Arm伪代码：硬件描述语言的核心特性与实践
  • DS4Windows终极指南：如何让PlayStation手柄在Windows上完美运行
  • Agentic Workflow实战：多智能体分治架构设计与落地
  • Midjourney V6 Vary(Region)：区域级潜变量编辑原理与精准控制实践
  • 为什么92%的CRM项目在6个月内失去用户喜爱？揭秘Lovable CRM的3层情感化设计模型
  • 2026年软考算法知识点—计算机等级考试—软件设计师考前备忘录—东方仙盟
  • 校招数据EDA与分类建模实战：从简历混沌中识别能力信号
  • OOMAO：MATLAB自适应光学仿真工具箱完全指南
  • ChatGPT写SEO文章到底行不行？实测127篇A/B文案后，我发现了3个99%人忽略的排名陷阱
  • 为什么92%的浙江话语音项目在ElevenLabs上失败？——资深方言NLP工程师20年踩坑复盘
  • 【204期】异地组网一键联机工具
  • Wot Design Uni 组件库异步上传终极指南：深度解析 wd-upload 的 Promise 支持机制