---
name: karpathy-guidelines
description: Use when writing, reviewing, or refactoring code to reduce common LLM mistakes - enforces simplicity, surgical changes, and verifiable success criteria
---

# Karpathy Guidelines

减少 LLM 常见编码错误的行为准则，源自 [Andrej Karpathy 的观察](https://x.com/karpathy/status/2015883857489522876)。

**权衡：** 这些准则偏向谨慎而非速度。简单任务请自行判断。

## 1. 编码前思考

**不要假设。不要隐藏困惑。暴露权衡。**

实现之前：
- 明确陈述你的假设。不确定就问。
- 如果存在多种解释，全部列出——不要默默选一个。
- 如果有更简单的方案，说出来。必要时提出反对。
- 如果有不清楚的地方，停下来。指出困惑点，提问。

## 2. 简单优先

**解决问题的最小代码量。不做投机性设计。**

- 不做超出需求的功能。
- 不为只用一次的代码做抽象。
- 不加没被要求的"灵活性"或"可配置性"。
- 不为不可能的场景写错误处理。
- 如果 200 行能缩成 50 行，重写。

问自己："资深工程师会觉得这过度复杂吗？" 如果是，简化。

## 2.5 SOLID 与 DRY

**SOLID 原则——设计组件、类和函数时应用：**

- **S（单一职责）：** 每个组件、类或函数只负责一个关注点。
- **O（开闭原则）：** 扩展行为时不修改现有代码。
- **L（里氏替换）：** 子类型必须能完全替代基类型。
- **I（接口隔离）：** 优先使用小而专注的接口，而非"胖"接口。
- **D（依赖倒置）：** 依赖抽象而非具体实现。

**DRY（不要重复自己）：**

识别并消除重复逻辑。写新代码前，搜索是否已有类似实现——复用或扩展现有代码，而非创建重复。参见：第 3 节（精准修改）了解何时*不*该重构。

## 3. 精准修改

**只碰必须碰的。只清理自己制造的混乱。**

编辑现有代码时：
- 不要"改进"相邻代码、注释或格式。
- 不要重构没坏的东西。
- 匹配现有风格，即使你会做得不同。
- 如果发现无关的死代码，提一下——不要删它。

当你的修改产生孤立代码时：
- 删除*你的修改*导致未使用的导入/变量/函数。
- 不要删除已有的死代码（除非被要求）。

检验标准：每一行修改都应直接追溯到用户的需求。

## 3.5 强制规则转为可追踪待办

**当技能定义了强制规则时，立即将其转为待办项。**

开始任务前：
- 扫描当前技能的 ⛔ 强制规则部分。
- 将每个必需步骤添加为待办项——包括编码前检查和编码后交付物。
- 最后一个待办必须是："逐条核对强制规则并输出合规结果"。

不要在未验证每条强制规则的情况下标记所有待办完成。完成代码不等于完成任务——完成所有必需步骤才是完成任务。

## 4. 目标驱动执行

**定义成功标准。循环直到验证通过。**

**定义成功标准前，完成两个阶段：**

- **阶段 0 – 理解：** 彻底审查现有代码/材料。识别 KISS、YAGNI、DRY 和 SOLID 原则已应用或违反的地方。非简单任务不要跳过此阶段。
- **阶段 1 – 计划：** 定义任务范围和可衡量的结果。优先改进现有代码中的原则应用，而非盲目添加新功能。

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

多步任务请列出简要计划：
```
1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]
3. [步骤] → 验证：[检查项]
```

强成功标准让你能独立循环。弱标准（"让它工作"）需要不断澄清。

## 5. 报告协议

**只在明确要求时才生成总结报告。**

当要求报告时，包含：
- 本次迭代完成的核心任务及具体成果。
- 如何应用了 KISS、YAGNI、DRY、SOLID 以及获得的收益。
- 遇到的挑战及解决方式。
- 明确的下一步和建议。

未要求时：完全跳过总结。交付改动后停止。

**简洁 vs 必需交付物：**

简洁意味着消除填充，而非跳过必需交付物。如果技能明确要求输出（如合规报告），该输出是必需的，无论简洁准则如何。"无报告文件"意味着不要将文件写入磁盘——并不意味着抑制对话中的必需输出。