Claude Code 行为指南

背景与问题

Andrej Karpathy（前 OpenAI 创始成员、前 Tesla AI 总监）在社交媒体上分享了他对 LLM 编码行为的观察：

“模型会替你做出错误的假设并直接执行，而不去验证。它们不管理自己的困惑，不寻求澄清，不暴露不一致性，不展示权衡取舍，在应该拒绝时也不拒绝。”

“它们非常喜欢过度复杂化代码和 API，膨胀抽象层，不清理死代码…实现一个膨胀的结构超过 1000 行，而实际上 100 行就够了。”

“它们有时仍然会更改/删除它们不够理解的注释和代码作为副作用，即使这些与任务无关。”

解决方案：四大原则

本项目通过四大核心原则来解决这些问题：

原则	解决的问题
先思考后编码	错误假设、隐藏困惑、缺失权衡
简约优先	过度复杂化、膨胀抽象
精准修改	无关编辑、触碰不该碰的代码
目标驱动执行	通过测试优先、可验证的成功标准

---

原则详解

1. 先思考后编码 (Think Before Coding)

核心理念：不要假设。不要隐藏困惑。展示权衡取舍。

LLM 经常默默地选择一种解释然后执行。这个原则强制显式推理：

• 明确陈述假设 — 如果不确定，先问而不是猜
• 呈现多种解释 — 当存在歧义时，不要默默选择
• 适时拒绝 — 如果存在更简单的方法，说出来
• 困惑时停止 — 指出不清楚的地方，请求澄清

示例对比：

# 用户请求："添加用户数据导出功能"

# ❌ LLM 常见做法（错误假设）
# - 假设导出所有用户（隐私问题？）
# - 假设文件位置
# - 假设包含哪些字段
# 直接开始写代码...

# ✅ 正确做法（展示假设）
在实现之前，我需要澄清：
1. 范围：导出所有用户还是筛选子集？（隐私影响）
2. 格式：您说的"导出"是指：
   - 浏览器下载文件？
   - 后台任务邮件通知？
   - API 端点返回数据？
3. 字段：包含哪些用户字段？（有些可能敏感）
4. 数据量：通常有多少用户？（影响实现方式）

最简单的方案：添加返回分页 JSON 的 API 端点。

2. 简约优先 (Simplicity First)

核心理念：解决问题的最少代码。不做任何推测性设计。

对抗过度工程化的倾向：

• 不添加超出需求的功能
• 不为单次使用的代码创建抽象
• 不添加未请求的"灵活性"或"可配置性"
• 不处理不可能发生的错误场景
• 如果 200 行代码可以写成 50 行，就重写它

测试标准： 高级工程师会认为这过度复杂吗？如果是，就简化。

示例对比：

# 用户请求："添加折扣计算函数"

# ❌ 过度工程化（约60行）
from abc import ABC, abstractmethod

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass

class PercentageDiscount(DiscountStrategy):
    # ... 更多代码
class FixedDiscount(DiscountStrategy):
    # ... 更多代码

class DiscountCalculator:
    # ... 更多代码

# ✅ 简约方案（5行）
def calculate_discount(amount: float, percent: float) -> float:
    """计算折扣金额。percent 应为 0-100。"""
    return amount * (percent / 100)

3. 精准修改 (Surgical Changes)

核心理念：只触碰必须触碰的。只清理自己制造的混乱。

修改现有代码时：

• 不要"改进"相邻的代码、注释或格式
• 不要重构没坏的东西
• 匹配现有风格，即使你会用不同的方式
• 如果发现无关的死代码，提一下 — 不要删除它

测试标准： 每一行改动都应该能直接追溯到用户的请求。

示例对比：

# 用户请求："修复空邮箱导致验证器崩溃的 bug"

# ❌ 做得太多（添加了未请求的用户名验证）
def validate_user(user_data):
    """验证用户数据。"""  # 添加了未请求的 docstring
    email = user_data.get('email', '').strip()

    # 验证邮箱
    if not email:
        raise ValueError("Email required")
    if '@' not in email or '.' not in email.split('@')[1]:  # 增强了验证
        raise ValueError("Invalid email")

    # 验证用户名  ← 这是未请求的功能！
    username = user_data.get('username', '').strip()
    if not username:
        raise ValueError("Username required")
    if len(username) < 3:
        raise ValueError("Username too short")

    return True

# ✅ 精准修改（只修复空邮箱问题）
def validate_user(user_data):
    # 检查邮箱格式
    email = user_data.get('email', '')  # 只改了这里
    if not email or not email.strip():  # 处理空字符串
        raise ValueError("Email required")

    if '@' not in email:  # 保持原有验证逻辑
        raise ValueError("Invalid email")

    # 检查用户名（保持原样）
    if not user_data.get('username'):
        raise ValueError("Username required")

    return True

4. 目标驱动执行 (Goal-Driven Execution)

核心理念：定义成功标准。循环直到验证通过。

将命令式任务转化为可验证的目标：

不要说…	转化为…
“添加验证”	“为无效输入写测试，然后让测试通过”
“修复 bug”	“写一个能复现它的测试，然后让测试通过”
“重构 X”	“确保前后测试都通过”

对于多步骤任务，陈述简要计划：

1. [步骤] → 验证: [检查项]
2. [步骤] → 验证: [检查项]
3. [步骤] → 验证: [检查项]

示例对比：

# 用户请求："给 API 添加速率限制"

# ❌ 一次性完成（300行代码，无验证步骤）
# 实现完整的 Redis 速率限制、多种策略、配置系统...

# ✅ 增量验证
API 速率限制实现计划：

1. 添加基本的内存速率限制（单个端点）
   验证：
   - 测试：100次请求 → 前10次成功，其余返回429
   - 手动：curl端点11次，看到速率限制错误

2. 提取为中间件（应用到所有端点）
   验证：
   - 测试：速率限制应用到 /users 和 /posts
   - 现有端点测试仍然通过

3. 添加 Redis 后端（支持多服务器）
   验证：
   - 测试：应用重启后速率限制持久化
   - 测试：两个应用实例共享速率限制计数器

4. 添加配置（每个端点的速率）
   验证：
   - 测试：/search 允许 10/分钟，/users 允许 100/分钟

每个步骤独立可验证、可部署。
从步骤1开始？

---

安装方式

方式 A：Claude Code 插件（推荐）

在 Claude Code 中执行：

# 首先添加市场
/plugin marketplace add forrestchang/andrej-karpathy-skills

# 然后安装插件
/plugin install andrej-karpathy-skills@karpathy-skills

这会将指南作为 Claude Code 插件安装，在所有项目中都可用。

方式 B：CLAUDE.md（每个项目）

新项目：

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

现有项目（追加）：

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

---

如何知道它在生效

如果这些指南在起作用，你会看到：

• diff 中不必要的改动减少 — 只出现请求的改动
• 过度复杂化导致的重写减少 — 代码第一次就很简单
• 澄清问题在实现之前出现 — 而不是在犯错之后
• 干净、最小的 PR — 没有顺便重构或"改进"

---

权衡说明

这些指南偏向谨慎而非速度。对于琐碎任务（简单的拼写修复、明显的单行修改），请使用判断力 — 不是每个改动都需要完整的严谨流程。

目标是减少非琐碎工作中的代价高昂的错误，而不是减慢简单任务。

---

核心洞见

来自 Andrej：

“LLM 非常擅长循环直到满足特定目标…不要告诉它做什么，给它成功标准然后看着它执行。”

"目标驱动执行"原则捕捉了这一点：将命令式指令转化为带有验证循环的声明式目标。

好的代码是简单解决今天问题的代码，而不是过早解决明天问题的代码。

---