Andrej Karpathy Skills 深度实战：用 CLAUDE.md 让 AI 遵守工程纪律

截至 2026 年 6 月，andrej-karpathy-skills 在 GitHub 斩获 14.9 万 Stars。它不提供新功能，只通过一份 CLAUDE.md 文件，就让 Claude Code、Cursor 等 AI 编程助手的行为发生质的飞跃。

目录

1. 背景：AI 编程的"聪明反被聪明误"
2. Karpathy 四大原则详解
3. 生产级安装与配置
4. 代码实战：Before & After
5. 高级技巧
6. 总结

1. 背景：AI 编程的"聪明反被聪明误"

2024-2026 年，AI 辅助编程工具爆发。但深度使用者都会遇到令人沮丧的场景：

场景一：过度自信的幻觉

你：帮我实现一个用户认证模块
AI：（直接输出 200 行代码，包含 JWT、Redis、bcrypt）
    搞定！我加入了 JWT、Redis session、密码加密...
你：（发现引入了 5 个未使用的依赖）

场景二：过度复杂化

你：写个读取 CSV 的函数
AI：（输出 300 行，包含流式处理、并行读取、进度条）
    我考虑了大数据场景、编码问题、内存优化...
你：（你只有一个 10MB 文件）

场景三：乱改无关代码

你：修复登录页面的 CSS 对齐
AI：（修改了登录页、顺带"优化"了注册页、重构了按钮组件）
    我顺便优化了一下相关组件...
你：（CI 挂了，触发了 15 个测试失败）

Andrej Karpathy（前 Tesla AI 总监）在使用 Claude Code 过程中，系统性总结了这些 LLM 编程四大陷阱，并将应对策略浓缩为一份 CLAUDE.md 文件。

2. Karpathy 四大原则详解

2.1 Think Before Coding（编码前思考）

原理：LLM 训练目标是对提示词做出"有帮助的回复"。遇到模糊需求时，模型会自行"脑补"细节，而非主动寻求澄清。

实战效果：

Before（没有 CLAUDE.md）：

User: 帮我实现一个缓存装饰器
AI: （直接输出 50 行代码，包含 TTL、LRU、线程安全...）

After（有 CLAUDE.md）：

User: 帮我实现一个缓存装饰器
AI: 在开始之前，我需要确认：
1. 缓存粒度：按函数+参数组合？还是全局 key-value？
2. TTL 策略：绝对时间？还是滑动过期？
3. 存储后端：内存？还是 Redis？
4. 并发安全：需要加锁吗？
请告诉我你的使用场景。

正确实现（最小版本）：

import time
import functools
from typing import Any, Dict, Tuple

def cache(ttl: int = 300):
    """TTL 缓存装饰器（最小实现）"""
    def decorator(func):
        cache_store: Dict[Tuple, Dict[str, Any]] = {}
        
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            key = (args, tuple(sorted(kwargs.items())))
            
            # 检查缓存
            if key in cache_store:
                entry = cache_store[key]
                if time.time() - entry['timestamp'] < ttl:
                    return entry['value']
                else:
                    del cache_store[key]
            
            result = func(*args, **kwargs)
            cache_store[key] = {
                'value': result,
                'timestamp': time.time()
            }
            return result
        
        return wrapper
    return decorator


# 测试（先写测试！）
import unittest

class TestCacheDecorator(unittest.TestCase):
    def test_basic_caching(self):
        call_count = 0
        
        @cache(ttl=10)
        def add(a, b):
            nonlocal call_count
            call_count += 1
            return a + b
        
        self.assertEqual(add(1, 2), 3)
        self.assertEqual(call_count, 1)
        
        # 第二次调用应命中缓存
        self.assertEqual(add(1, 2), 3)
        self.assertEqual(call_count, 1)

if __name__ == '__main__':
    unittest.main()

2.2 Simplicity First（简洁优先）

原理：LLM 过度复杂化的根源是训练数据偏见——GitHub 上的明星项目往往是"功能完整"的框架，而非"最小可用实现"。

简洁性检验清单：

• 是否引入了当前需求不需要的依赖？
• 是否有 'future-proof' 的抽象层（但目前只用一种实现）？
• 是否有超过 3 层的方法调用栈？
• 单个函数是否超过 20 行？

实战对比：

过度复杂化版本（AI 默认输出）：

# 配置加载器 - 过度工程版本（200+ 行）
import json, yaml, toml
from abc import ABC, abstractmethod
from singleton import Singleton

class ConfigLoader(ABC):
    @abstractmethod
    def load(self, path): pass

class JsonLoader(ConfigLoader):
    def load(self, path):
        with open(path) as f:
            return json.load(f)

class ConfigManager(Singleton):
    def __init__(self):
        self._cache = {}
    
    def load_config(self, path, use_cache=True, env_override=True):
        # ... 100 行实现
        pass

简洁优先版本（CLAUDE.md 指导下）：

# 配置加载器 - 简洁版本（12 行）
import json
from pathlib import Path
from typing import Dict, Any

def load_config(path: str) -> Dict[str, Any]:
    """加载 JSON 配置文件"""
    with open(path, 'r', encoding='utf-8') as f:
        return json.load(f)

# 使用方式
config = load_config('config.json')

对比：

• 代码行数：200+ 行 → 12 行
• 依赖：json/yaml/toml/logging → 仅 json
• Bug 表面积：20 个失败点 → 1 个（文件读取）

2.3 Surgical Changes（精确修改）

原理：LLM 的"顺手优化"源于训练数据偏见——GitHub 上的 PR 往往包含"顺带重构"。

实战技巧：

# 在执行 AI 生成的修改后，立即运行：
git diff --stat

# 输出应该只包含你请求的文件中你请求修改的部分
# 如果出现以下情况，说明 AI "顺手优化"了：
# - 修改了未请求的文件
# - 在同一个文件中修改了无关的行

案例：修复 Bug（Off-by-one 错误）

任务：修复以下代码中的 Bug（第 12 行，user_id 应该从 1 开始）

# api/users.py (原始版本)
@users_bp.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    if user_id < 0 or user_id > len(USERS):
        return jsonify({'error': 'Not found'}), 404
    user = USERS[user_id]  # Bug: 应该是 USERS[user_id - 1]
    return jsonify(user)

AI 的"顺手优化"版本（没有 CLAUDE.md）：

# 引入了 3 个新依赖、重构了数据模型、加了日志...
# 改动行数：47 行（实际只需要改 2 行）

精确修改版本（CLAUDE.md 指导下）：

# api/users.py (精确修改版本)
@users_bp.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    # 修复：user_id 从 1 开始
    if user_id < 1 or user_id > len(USERS):
        return jsonify({'error': 'Not found'}), 404
    
    # 修复：将 1-based user_id 转换为 0-based 索引
    user = USERS[user_id - 1]
    return jsonify(user)

改动统计：

• 改动行数：3 行（2 行修改 + 1 行注释）
• 新增依赖：0
• 破坏兼容性：无

2.4 Goal-Driven Execution（目标驱动执行）

原理：LLM 在执行多步骤任务时，会"迷失方向"——中途忘记原始目标，或在已经"够好"的实现上继续"优化"。

解决方案：TDD + 显式成功标准

# 目标驱动执行的模板（每次任务开始前先填写）

"""
任务：<用一句话描述任务>

成功标准（必须满足，否则任务未完成）：
1. <可验证的标准 1>
2. <可验证的标准 2>

测试用例（在写实现代码之前先写）：
- test_case_1: <输入> → <期望输出>

实现步骤（按依赖顺序）：
1. <步骤 1>
2. <步骤 2>
"""

实战：实现 LRU Cache

步骤1：定义成功标准（先写测试）

# tests/test_lru_cache.py
import unittest
from lru_cache import LRUCache

class TestLRUCache(unittest.TestCase):
    def test_basic_get_set(self):
        cache = LRUCache(capacity=2)
        cache.put(1, 1)
        cache.put(2, 2)
        self.assertEqual(cache.get(1), 1)
    
    def test_capacity_eviction(self):
        cache = LRUCache(capacity=2)
        cache.put(1, 1)
        cache.put(2, 2)
        cache.put(3, 3)  # 应该淘汰 key=1
        self.assertEqual(cache.get(1), -1)  # 已被淘汰
    
    def test_lru_order_update(self):
        cache = LRUCache(capacity=2)
        cache.put(1, 1)
        cache.put(2, 2)
        cache.get(1)  # 访问 key=1，更新 LRU 顺序
        cache.put(3, 3)  # 应该淘汰 key=2（不是 key=1）
        self.assertEqual(cache.get(1), 1)  # 仍然存在
        self.assertEqual(cache.get(2), -1)  # 已被淘汰

if __name__ == '__main__':
    unittest.main()

步骤2：运行测试（应该失败）

$ python -m pytest tests/test_lru_cache.py
FAILED (failures=3)

步骤3：实现最小可用版本

# lru_cache.py
from collections import OrderedDict

class LRUCache:
    """LRU Cache 实现（使用 OrderedDict）"""
    def __init__(self, capacity: int):
        self.capacity = capacity
        self.cache = OrderedDict()
    
    def get(self, key: int) -> int:
        """获取缓存值，不存在则返回 -1"""
        if key not in self.cache:
            return -1
        self.cache.move_to_end(key)
        return self.cache[key]
    
    def put(self, key: int, value: int) -> None:
        """写入缓存，超出容量时淘汰最久未使用的项"""
        if key in self.cache:
            self.cache.move_to_end(key)
        else:
            if len(self.cache) >= self.capacity:
                self.cache.popitem(last=False)
        self.cache[key] = value

步骤4：运行测试（应该全部通过）

$ python -m pytest tests/test_lru_cache.py -v
PASSED (successes=3)

3. 生产级安装与配置

3.1 方式一：直接克隆仓库（推荐）

# 进入你的项目根目录
cd /path/to/your/project

# 克隆仓库
git clone https://github.com/multica-ai/andrej-karpathy-skills.git /tmp/karpathy-skills

# 复制 CLAUDE.md 到项目根目录
cp /tmp/karpathy-skills/CLAUDE.md ./

# 如果使用 Cursor，复制 .cursorrules
cp /tmp/karpathy-skills/.cursorrules ./

# 清理
rm -rf /tmp/karpathy-skills

# 验证安装
cat CLAUDE.md | head -20

验证步骤：

# 启动 Claude Code
claude

# 输入：帮我写一个快速排序函数

# 观察输出：AI 应该会先问你：
# - 输入格式是什么？（列表？还是数组？）
# - 需要原地排序还是返回新数组？

# 如果 AI 直接输出代码而没有询问，说明 CLAUDE.md 没有被正确加载

3.2 方式二：手动创建自定义 CLAUDE.md

如果你的项目有特殊的编码规范，可以基于 Karpathy 的原则创建自定义版本：

# CLAUDE.md (自定义版本)

## 项目特定规则

- 使用 Python 3.11+ 语法（类型注解、match-case）
- 遵循 PEP 8（行长度 100 字符）
- 使用 pytest 作为测试框架
- 所有公共 API 必须有 Google 风格 docstring

## 集成 Karpathy 四大原则

（将 andrej-karpathy-skills 的 CLAUDE.md 内容复制到这里）

## 项目特定约束

- 数据库连接使用 SQLAlchemy 2.0
- 异步代码使用 asyncio + aiohttp
- 配置管理使用 pydantic-settings

4. 代码实战：Before & After

4.1 案例一：REST API 重构

任务：为现有 Flask 应用添加用户认证接口

Before（没有 CLAUDE.md）：

User: 添加用户登录接口
AI: （直接输出 70 行代码，包含 JWT、Redis、refresh token、注册接口...）

问题：

• 引入了 3 个新依赖
• 顺手加了注册接口和 refresh token 接口
• 没有测试

After（有 CLAUDE.md）：

User: 添加用户登录接口
AI: 在开始之前，我需要确认：
1. 认证方式：JWT token？还是 session？
2. 存储后端：已有用户模型吗？
3. 密码策略：需要 bcrypt 哈希吗？
4. Token 过期：1 小时？还是永久？

User: JWT，已有 User 模型，bcrypt 哈希，1 小时过期
AI: 明白了。这是最小实现：（输出 50 行完整可运行的代码 + 测试）

After 版本代码：

# api/auth.py
from flask import Blueprint, request, jsonify
from flask_jwt_extended import JWTManager, create_access_token, jwt_required
from werkzeug.security import check_password_hash
from models import User
from datetime import timedelta

auth_bp = Blueprint('auth', __name__, url_prefix='/api/auth')

def init_jwt(app):
    """初始化 JWT（在 app 工厂中调用）"""
    app.config['JWT_SECRET_KEY'] = app.config['SECRET_KEY']
    app.config['JWT_ACCESS_TOKEN_EXPIRES'] = timedelta(hours=1)
    JWTManager(app)

@auth_bp.route('/login', methods=['POST'])
def login():
    """用户登录接口"""
    data = request.get_json()
    
    # 输入校验
    if not data or 'username' not in data or 'password' not in data:
        return jsonify({'error': 'Missing username or password'}), 400
    
    user = User.query.filter_by(username=data['username']).first()
    
    if not user or not check_password_hash(user.password_hash, data['password']):
        return jsonify({'error': 'Invalid credentials'}), 401
    
    access_token = create_access_token(identity=user.id)
    return jsonify(access_token=access_token), 200

# tests/test_auth.py
import unittest
from app import create_app
from models import User, db

class TestAuth(unittest.TestCase):
    def setUp(self):
        self.app = create_app('testing')
        self.client = self.app.test_client()
        with self.app.app_context():
            db.create_all()
            user = User(username='test', password_hash='...')
            db.session.add(user)
            db.session.commit()
    
    def test_login_success(self):
        response = self.client.post('/api/auth/login', json={
            'username': 'test',
            'password': 'password123'
        })
        self.assertEqual(response.status_code, 200)
        self.assertIn('access_token', response.get_json())
    
    def test_login_invalid_credentials(self):
        response = self.client.post('/api/auth/login', json={
            'username': 'test',
            'password': 'wrong_password'
        })
        self.assertEqual(response.status_code, 401)

if __name__ == '__main__':
    unittest.main()

5. 高级技巧

5.1 为不同类型任务定制 CLAUDE.md

不要在所有项目中都用同一份 CLAUDE.md。根据项目类型调整：

# CLAUDE.md (Web 前端项目版本)

## 技术栈特定规则

- 使用 TypeScript（严格模式）
- 遵循 Airbnb JavaScript 风格指南
- 使用 React 18+（函数组件 + Hooks）
- 状态管理用 Zustand（不用 Redux）
- 样式用 Tailwind CSS

## Karpathy 原则的适配

### Think Before Coding
- 在开始之前，问：这个组件需要状态吗？能用 CSS 实现吗？

### Simplicity First
- 优先用 HTML/CSS 实现，其次用组件，最后用第三方库
- 拒绝"用一个 UI 框架"

### Surgical Changes
- 修改组件时，不要顺手"优化"无关组件

### Goal-Driven Execution
- 每个组件先写 Storybook 故事（作为规范）
- 然后用 TDD 实现

5.2 用"示例驱动"让 AI 理解你的风格

在 CLAUDE.md 中加入"好代码/坏代码"的对比示例：

## 代码风格示例

### ✅ 好的实现（简洁、可读、可测试）

```python
def calculate_discount(price: float, coupon: Coupon) -> float:
    """计算折扣后价格"""
    if not coupon.is_valid():
        return price
    return max(0, price - coupon.discount_amount)

❌ 坏的实现（过度复杂、不可读、不可测试）

def calculate_discount(price: float, coupon: Coupon, 
                      user: User = None, 
                      context: Dict[str, Any] = None) -> Union[float, Tuple[float, Dict]]:
    """
    计算折扣（支持多种折扣类型、用户等级、促销规则...）
    """
    # 200 行实现...

当你给出"好/坏"示例后，AI 会学习你的审美，生成符合你风格的代码。

### 5.3 用"反向提示词"防止常见错误

在 `CLAUDE.md` 中加入"禁止清单"：

```markdown
## 禁止事项（绝对不允许）

- ❌ 不要使用 `import *`（总是显式导入）
- ❌ 不要使用 `except Exception:`（总是捕获具体异常）
- ❌ 不要直接拼接 SQL（总是用参数化查询）
- ❌ 不要提交硬编码的密钥（总是用环境变量）
- ❌ 不要"优化"我没让你优化的代码
- ❌ 不要在没有测试的情况下重构

6. 总结

核心收获

1. Why：理解 LLM 为什么会"过度复杂化"、"顺手优化"——理解了根源，才能从根本上解决问题
2. What：andrej-karpathy-skills 的四大原则——不是"提示词技巧"，而是"软件工程纪律"
3. How：如何安装、配置、定制 CLAUDE.md
4. Practice：真实案例的 Before & After 对比

效果评估（社区数据）

行动呼吁

如果你还没用过 andrej-karpathy-skills，现在就试试：

# 1 分钟安装
cd /path/to/your/project
curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

# 然后重启 Claude Code / Cursor
# 感受 AI 行为的质的飞跃

参考资源：

• 项目地址：github.com/multica-ai/andrej-karpathy-skills
• Karpathy 原推文：twitter.com/karpathy（搜索 "vibe coding"）
• Claude Code 文档：docs.anthropic.com/claude-code

最后更新时间：2026 年 6 月 28 日

字数统计：约 6,000 字

阅读时间：约 15 分钟