# Karpathy Skills

> Karpathy LLM 编程避坑指南

- Skill: `gaoqiongxie/karpathy-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gaoqiongxie/karpathy-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaoqiongxie/karpathy-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gaoqiongxie (https://skillmd.com/u/gaoqiongxie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gaoqiongxie/karpathy-skills

---

# Karpathy LLM 编程避坑指南

> 灵感来源：Andrej Karpathy 的 LLM 编程最佳实践
> GitHub: https://github.com/forrestchang/andrej-karpathy-skills ⭐71.8K（本周新增+44K，登上 Trending #1）
> 触发关键词：LLM编程规范、代码避坑、AI编程技巧、写代码规范

---

## 🎯 核心理念

LLM 写代码有其独特优势，也有独特陷阱。这份 Skill 帮你规避常见错误，写出更可靠的 AI 辅助代码。

---

## ⚠️ LLM 编程十大戒律

### 1. 不要过度抽象
```
❌ 不要：
// LLM 容易过度设计
abstract class BaseService<T extends Entity, DTO extends BaseDTO> {
    abstract protected Mapper<T, DTO> getMapper();
    // ... 200行框架代码
}

✅ 应该：
直接写你要的功能
public class UserService {
    public User getById(Long id) {
        return userMapper.selectById(id);
    }
}
```

### 2. 先跑通，再优化
```
❌ 不要：
一上来就设计完美的微服务架构

✅ 应该：
先写一个能跑的 monolith
等真正遇到问题再拆分
```

### 3. 写测试是必须的，不是可选的
```
❌ 不要：
"测试以后再补"

✅ 应该：
// 测试先行
@Test
public void testUserLogin() {
    // given
    String phone = "13800138000";
    String code = "123456";
    
    // when
    User user = userService.login(phone, code);
    
    // then
    assertNotNull(user);
    assertEquals("13800138000", user.getPhone());
}
```

### 4. 读报错信息比问 AI 更快
```
❌ 不要：
看到报错就去问 AI 或重新生成

✅ 应该：
1. 先仔细读报错信息
2. 看第几行、什么类型的错误
3. 大多数报错 AI 已经告诉你怎么修了
```

### 5. 先自己体验 AI 代码助手
```
❌ 不要：
让 AI 写完代码直接复制粘贴

✅ 应该：
1. 让 AI 写一小段
2. 自己跑一下、测一下
3. 有问题先自己想想
4. 真的不懂再追问 AI
```

### 6. 避免"超级代理"陷阱
```
❌ 不要：
让 AI 一次性写整个系统

✅ 应该：
分步骤、小模块交付
"先写 User 实体和 Mapper"
"跑通后再写 Service 层"
"最后写 Controller"
```

### 7. 上下文要具体，不要模糊
```
❌ 不要：
"帮我优化这个查询，很慢"

✅ 应该：
"这个查询在用户量10万时需要3秒
 WHERE create_time > '2024-01-01'
 请帮我加索引或优化 SQL"
```

### 8. 警惕 AI 的"幻觉"引用
```
❌ 不要：
"帮我引用 Spring Boot 最新文档的 xxx"

✅ 应该：
AI 可能会编造文档链接
自己核实重要信息
```

### 9. 代码 review 不能省
```
❌ 不要：
相信 AI 写的代码一定对

✅ 应该：
1. 通读 AI 生成的代码
2. 检查边界条件
3. 确认业务逻辑正确
4. 测试覆盖是否足够
```

### 10. 保持人工判断力
```
❌ 不要：
AI 说什么就做什么

✅ 应该：
AI 是工具，你是决策者
对于关键代码：
- 理解它为什么这么写
- 判断是否符合你的需求
- 必要时要求重新生成
```

---

## 🛠️ AI 辅助调试流程

```
┌─────────────────────────────────────────────────────────┐
│                    调试问题正确姿势                        │
├─────────────────────────────────────────────────────────┤
│ 1️⃣ 读报错  →  先看错误信息，搞清楚什么错                  │
│     ↓                                                    │
│ 2️⃣ 定位    →  哪一行、什么类型错误                       │
│     ↓                                                    │
│ 3️⃣ 思考    →  可能的原因是什么                          │
│     ↓                                                    │
│ 4️⃣ 提问    →  描述清楚：预期 vs 实际                     │
│     ↓                                                    │
│ 5️⃣ 验证    →  AI 给出方案后，自己先测                    │
│     ↓                                                    │
│ 6️⃣ 理解    →  确保理解原因，不只是修复表面               │
└─────────────────────────────────────────────────────────┘
```

---

## 📝 提问模板

### Bug 报告
```
【Bug描述】
预期行为：
实际行为：

【错误信息】
[粘贴完整报错]

【相关代码】
[粘贴相关代码片段]

【已尝试】
1. xxx - 结果
2. xxx - 结果
```

### 代码审查请求
```
【审查范围】
[描述要审查的代码/模块]

【关注点】
1. xxx 方面
2. xxx 方面

【特殊要求】
[任何特殊要求或约束]
```

### 重构请求
```
【目标】
[描述要达到的效果]

【现状】
[描述当前代码的问题]

【约束】
[性能要求/兼容性/时间限制]
```

---

## ✅ AI 友好代码 Checklist

| 检查项 | ✅ | ❌ |
|--------|:--:|:--:|
| 代码行数 < 100行/文件 | ☑️ | |
| 单一职责，一个方法做一件事 | ☑️ | |
| 有基本的单元测试 | ☑️ | |
| 变量命名见名知意 | ☑️ | |
| 没有多层嵌套 (>3层) | ☑️ | |
| 异常有处理，不是裸抛 | ☑️ | |
| SQL 有参数化查询 | ☑️ | |

---

## 🎓 学习资源

- [Andrej Karpathy 原始博客](https://karpathy.github.io/)
- [LLM 编程最佳实践讨论](https://github.com/forrestchang/andrej-karpathy-skills)
- [Vibe Coding 概念](https://www.youtube.com/watch?v=defY喀)

---

## 💬 使用方式

```
用户：AI 写代码有什么坑要注意
助手：【展示十大戒律】

用户：帮我 review 这段代码
助手：【使用提问模板收集信息，然后给出审查意见】

用户：调试了半天报错，怎么问 AI 效率更高
助手：【展示调试流程 + 提问模板】
```