A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
💡 Use Cases
最适合需要AI辅助但又要严格控制代码质量、避免过度设计的编程场景。
修复遗留代码bug
Problem: 让AI修复一个复杂函数中的bug时,它经常擅自重构周边代码,引入新的问题。
Solution: 使用CLAUDE.md的"精准修改"原则,强制AI只修改与bug直接相关的代码行,不改变无关的注释、格式或相邻函数。
Example: 修复一个数据库查询函数中的SQL注入漏洞时,AI不会重写整个函数的错误处理逻辑,只专注于添加参数化查询部分。
实现简单功能需求
Problem: AI经常过度设计,把简单的数据验证功能实现成复杂的验证框架。
Solution: 应用"简单性优先"原则,要求AI只实现明确请求的功能,禁止添加未要求的抽象层或配置选项。
Example: 要求实现邮箱格式验证时,AI会提供一个简单的正则表达式函数,而不是创建包含多种验证器的Validator类。
重构大型代码库
Problem: AI在重构时经常做出错误假设,不确认代码意图就进行修改,导致功能损坏。
Solution: 启用"先思考后编码"原则,强制AI先明确陈述对代码的理解和假设,发现歧义时主动询问澄清。
Example: 重构一个复杂的支付处理模块前,AI会先列出它理解的各个组件职责,并询问不确定的业务逻辑细节。
添加测试覆盖
Problem: AI编写的测试经常遗漏边界情况,或者测试本身过于复杂难以维护。
Solution: 采用"目标驱动执行"策略,要求AI先编写测试用例定义成功标准,然后实现代码让测试通过。
Example: 添加用户注册验证时,AI会先编写测试用例覆盖所有无效输入场景,然后实现刚好能让这些测试通过的最小代码。
📊 Project Info
- Stars
- ⭐ 49,683
- Forks
- 4,095
- Today
- +7,959
- Ranking
- #1
- Collection
- Overall
- Trending Date
- April 16, 2026
- Last Push
- 4/15/2026
🏷️ Topics
5分钟快速开始:使用CLAUDE.md优化Claude代码生成
通过一个配置文件,快速提升Claude等AI助手在编程任务中的输出质量,减少错误假设和过度设计。
🖥️ OS
⚙️ Runtime
🔧 Tools
📝 Steps
安装Claude Code插件(推荐)
在Claude Code中添加市场并安装插件,使指南在所有项目中生效。
添加插件市场
$ claude code marketplace add https://github.com/forrestchang/andrej-karpathy-skills安装CLAUDE.md指南插件
$ claude code plugin install claude-md-guidelines或创建项目级CLAUDE.md文件
如果不想全局安装,可在项目中添加CLAUDE.md文件,仅影响当前项目。
下载CLAUDE.md文件到当前目录
$ curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md测试指南效果
在Claude Code中请求一个编程任务,观察输出是否符合指南原则。
模拟一个简单任务
$ 在Claude Code中输入:'请帮我写一个Python函数,计算两个数的和,并添加错误处理。'✅ 验证成功
确认CLAUDE.md指南正在生效,优化AI助手的代码生成行为。
- ✓Claude在编码前主动询问澄清问题
- ✓生成的代码简洁,无未请求的功能
- ✓修改仅针对任务,不波及无关代码
⚡ Quick Tips
🔍 Troubleshooting
❓ Claude Code未识别CLAUDE.md文件
→ 确保文件位于项目根目录,并重启Claude Code。
❓ 插件安装失败
→ 检查网络连接,或手动下载文件并放置到正确位置。
🎯 Next Steps
阅读CLAUDE.md文件内容
深入了解四大原则,以便更好地指导AI助手。
尝试复杂任务
用指南测试重构或调试任务,观察改进效果。
Difficulty
入门
Est. Time
1-2小时
Target Audience
任何希望更高效、更可靠地使用Claude等AI助手进行编程的开发者,尤其是对AI生成代码质量不满意或感到困惑的初学者。
🎯 What You'll Learn
学会如何配置和使用CLAUDE.md文件来引导AI助手生成更简洁、精准、符合意图的代码,减少AI在编程任务中常见的过度设计、错误假设等问题。
📋 Prerequisites
需要能够使用终端或命令行创建文件、编辑文件内容。
能够使用任何文本编辑器(如VS Code, Notepad++, Vim等)打开和编辑纯文本文件。
最好有过使用Claude、GitHub Copilot等AI工具进行代码生成或问答的初步体验,以便理解本指南要解决的问题。
📚 Resources
项目GitHub仓库README
最核心的学习资料,包含了所有设计思想、原则详解、安装方法和使用提示。
Andrej Karpathy的原帖(如果可找到)
理解项目灵感的源头,能更深刻地体会作者试图解决的大模型编码痛点。
Claude Code官方使用指南
如果你选择插件安装方式,熟悉Claude Code的基本操作将有助于你更好地利用这个技能。
🗺️ Learning Phases
理解与准备
阅读项目README,理解核心问题
仔细阅读GitHub仓库的README文件,重点理解Andrej Karpathy指出的三大问题(错误假设、过度复杂化、无关修改)以及对应的四大解决原则(先思考后编码、简单性优先、精准修改、目标驱动执行)。
选择安装方式
根据你的使用场景,决定采用哪种方式应用这些指南: 1. **Claude Code插件(推荐)**:如果你主要使用Claude Code,这将使指南在所有项目中生效。 2. **项目级CLAUDE.md文件**:如果你希望规则仅应用于特定项目,或者使用的AI工具支持读取此类配置文件。
安装与配置
方式A:安装Claude Code插件(如选择)
1. 在Claude Code界面中,首先添加市场:`claude code:marketplace add https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/marketplace.json` 2. 然后安装技能:`claude code:skill install forrestchang/andrej-karpathy-skills`
方式B:创建项目级CLAUDE.md文件(如选择)
1. 打开你的项目根目录。 2. 创建一个名为`CLAUDE.md`的新文件。 3. 将项目README中“The Four Principles in Detail”部分之后、直到“Customization”之前的所有内容(即四大原则的详细描述)复制粘贴到该文件中。
初次使用与验证
发起一个简单的编程任务
在你的项目中,向AI助手(已配置CLAUDE.md)提出一个清晰但非琐碎的编程请求。例如:“为这个用户模型添加一个‘年龄’字段的验证,确保年龄在0到150之间。”
观察AI的响应行为
仔细阅读AI生成的代码和解释,对照四大原则检查: 1. **先思考后编码**:AI是否在开始编码前陈述了它的假设或提出了澄清性问题? 2. **简单性优先**:生成的代码是否直接解决了问题,没有添加额外的抽象或“未来可能有用”的功能? 3. **精准修改**:AI是否只修改了与“年龄验证”相关的代码,没有改动其他无关的格式、注释或函数? 4. **目标驱动执行**:AI是否建议或直接编写了测试来验证其修改的正确性?
检查“如何知道它起作用了”
回顾项目README中“How to Know It's Working”部分。评估你的体验: - 生成的代码差异(diff)是否干净,只包含必要的更改? - 代码是否第一次就相对简洁,不需要你要求重写? - AI是否在犯错前就先寻求了澄清?
进阶与定制
理解权衡与适用场景
阅读“Tradeoff Note”。明白这些指南偏向“谨慎而非速度”。对于修复一个明显的拼写错误,可能不需要完整的流程。学会判断何时需要严格遵循指南(非琐碎工作),何时可以放松。
尝试定制CLAUDE.md
如果你有项目特定的编码规范或要求,可以将其添加到`CLAUDE.md`文件中。例如,在文件末尾添加:“## 项目特定规则\n- 本项目使用4个空格缩进。\n- 所有函数必须包含JSDoc注释。”
⚠️ Common Mistakes
❌ 期望CLAUDE.md能“魔法般”解决所有AI编码问题
✅ CLAUDE.md是一套“指导原则”,而非绝对命令。AI的理解和遵守程度可能有波动。它旨在显著改善输出质量,但不能保证100%完美。保持审阅AI生成代码的习惯仍然重要。
❌ 在过于模糊或庞大的任务上测试,导致效果不明显
✅ 初次使用时,从定义清晰、范围有限的中小型任务开始(如添加一个函数、修复一个已知Bug)。这样更容易观察指南是否引导AI做出了更聚焦、更简单的修改。
❌ 创建了CLAUDE.md文件,但AI助手似乎没有读取或遵循
✅ 1. 确认文件名为`CLAUDE.md`(全大写),且位于项目根目录。2. 确认你使用的AI工具(如特定IDE插件、特定聊天界面)支持读取项目根目录下的配置文件。并非所有AI工具都支持此功能。3. 如果使用Claude Code插件方式,请确认技能已成功安装并启用。
❌ 将指南用于所有任务,包括极其简单的修改,感觉流程繁琐
✅ 回顾“权衡说明”。对于“把console.log改成console.error”这类一目了然的任务,可以直接给出指令,无需等待AI进行“先思考”等完整流程。灵活运用,让工具为人服务。
🚀 Next Steps
学完基础后可以继续探索的方向