---
name: karpathy-guidelines
description: Karpathy 四原则编码行为守则。减少 LLM 常见编码错误：过度实现、静默假设、顺手重构、无验证标准。在任意编码场景激活。
---

# Karpathy Guidelines Skill

> 来源：[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
> 在本项目中已深度融合到 req 技能工作流各阶段。

## 四原则

### 1. Think Before Coding（编前推理）
> "Don't assume. Don't hide confusion. Surface tradeoffs."

**在写第一行代码前：**
- 显式列出本次实现的假设（数据格式、边界条件、依赖接口）
- 如存在多种解读，列出所有方案（附估算），不要静默选择
- 如有更简单的实现方式，说出来
- 遇到不清晰的地方，停下来，指出混乱点，提问

**在 req 工作流中：** → 已嵌入 `req-prd` 的「Phase 0 假设倾倒协议」

---

### 2. Simplicity First（简单优先）
> "Minimum code that solves the problem. Nothing speculative."

**禁止：**
- 添加未被需求要求的功能
- 为单次使用的代码添加抽象
- 添加未被请求的"灵活性"或"可配置性"
- 为不可能发生的场景写错误处理
- 写了 200 行但 50 行就够的代码 → 重写

**自检：** "一个高级工程师看这段代码会觉得过度设计吗？" 如果是 → 简化

**在 req 工作流中：** → 已嵌入 `req-design` 过度设计检查 + `dev-review` 第六视角

---

### 3. Surgical Changes（手术式修改）
> "Touch only what you must. Clean up only your own mess."

**修改现有代码时：**
- 不要"顺手改进"相邻代码、注释或格式
- 不要重构没有损坏的代码
- 匹配现有代码风格，即使你会做不同的选择
- 发现不相关的死代码 → 提及但不删除

**你的变更造成的孤儿：**
- 删除你的变更导致的无用 import/变量/函数
- 不要删除已存在的死代码（除非被要求）

**铁律：** diff 中每一行修改都应该可以追溯到用户的需求

**在 req 工作流中：** → 已嵌入 `dev-review` 第六视角 + `check-surgical.sh` Harness 脚本

---

### 4. Goal-Driven Execution（目标驱动执行）
> "Define success criteria. Loop until verified."

**将请求转化为可验证目标：**
- "加验证" → "为无效输入写测试，然后让它通过"
- "修 bug" → "写一个复现 bug 的测试，然后让它通过"
- "重构 X" → "确保测试在重构前后都通过"

**多步任务需要说明计划：**
```
1. [步骤] → 验证: [检查项]
2. [步骤] → 验证: [检查项]
3. [步骤] → 验证: [检查项]
```

**在 req 工作流中：** → 已嵌入 `dev-coding` 的「Step 0 验证优先」+ VP 三件套协议

---

## 与 req 工作流的映射

| 原则 | 生效阶段 | 落地机制 |
|------|---------|---------|
| Think Before Coding | req-prd 启动前 | Phase 0 假设倾倒协议 |
| Simplicity First | req-design + dev-review | 过度设计检查 + 第六视角 |
| Surgical Changes | dev-review + CI | 第六视角 + check-surgical.sh |
| Goal-Driven Execution | dev-coding | Step 0 验证优先 + VP 三件套 |

## 反模式速查

| 场景 | ❌ LLM 常犯 | ✅ 正确做法 |
|------|-----------|-----------|
| "做个导出功能" | 静默假设格式/字段，直接实现 | 列出3种解读，等用户确认 |
| "让搜索更快" | 同时加缓存+索引+async | 列出3种"更快"含义，确认再做 |
| "加折扣计算" | Strategy+Abstract+Enum，50行 | 一个函数，3行 |
| "修空邮件bug" | 顺手加用户名校验+类型注解 | 只改空邮件的那2行 |
| "修认证bug" | 直接修改，无验证标准 | 先写复现测试，修复后验证通过 |