Karpathy

Karpathy Guidelines 实测：207k Star 的四条铁律，终结 AI 编程四大顽疾

作者
Karpathy Guidelines 实测：207k Star 的四条铁律，终结 AI 编程四大顽疾

痛点切入

用 AI 写代码的人，大概率遇到过这四种场景：

  • 自作主张 — 你让它加个功能，它默默假设你想要全量导出、分页、异步处理，一口气实现完才发现方向错了
  • 过度工程 — 一个 calculate_discount 函数，它给你写 30 行 Strategy 模式的抽象层
  • 顺手重构 — 你让它修个 bug，diff 里混进一堆「改进」：改了注释、重命名变量、删了你以为没用的代码
  • 无法验证 — 完成标准是「让它能用」，结果循环了 5 轮还在改

    • Andrej Karpathy（前 OpenAI / Tesla AI 负责人）在 X 上发了一段观察，直接点名这四个问题。有人把他的观点整理成一个 CLAUDE.md 文件，上线 7 个月拿到 207,175 Star，成为 GitHub 历史上增长最快的 AI 工具类仓库之一。

    这个 skill 不是代码库、不是插件、不是框架 — 是一个 2,357 字节的 Markdown 文件，四条规则，没有依赖。

    —

    工作原理

    Karpathy Guidelines 的核心思路是：用声明式目标替代命令式指令，用强制约束替代隐性期望。

    四条原则 vs 四个问题

    原则 解决的问题 核心机制
    Think Before Coding 假设错误、隐藏困惑 强制显式列出假设，不确定就问
    Simplicity First 过度工程、抽象膨胀 「高级工程师会说这太复杂吗？」自检
    Surgical Changes 顺手重构、无关改动 每行改动必须追溯到用户请求
    Goal-Driven Execution 无法验证、循环失败 把任务转为可验证的成功标准

    为什么只有 4 条？

    Karpathy 的原话：

    “LLMs are exceptionally good at looping until they meet specific goals… Don’t tell it what to do, give it success criteria and watch it go.”

    关键洞察：LLM 擅长「执行到满足条件」，但前提是条件得明确。四条原则不是在教 AI 怎么写代码，而是在 重新定义 AI 和人类的协作契约 — 让 AI 停下来问、写简单点、别乱动、定义清楚什么叫「完成了」。

    与同类方案的差异

    方案 思路 复杂度 效果
    Karpathy Guidelines 4 条行为约束 极低 中等（依赖模型遵守）
    Andrej Karpathy Guidelines (fork) 添加更多规则 低 中等
    ECC Agent Harness 68 Agent + 286 Skill 高 高（系统级强制）
    Planning-with-Files 持久化规划文件 中 高（崩溃恢复）

    Karpathy Guidelines 的独特之处：零依赖、零配置、一个文件搞定。它不强制执行，而是「建议」— 效果取决于模型的指令遵循能力。

    —

    功能拆解

    模块 1：Think Before Coding（思考优先）

    一句话：在写任何代码之前，先列出你的假设，不确定就问。

    核心能力：

  • 强制 LLM 显式声明假设（而不是默默假设后直接实现）
  • 面对歧义时呈现多个选项，而不是自己选一个
  • 遇到更简单的方案时主动提出
  • 困惑时停下来，描述哪里不清楚

    • 适用场景：需求模糊的任务、涉及隐私/安全的功能、多技术方案可选的决策

    示例对比：

    ❌ LLM 常见行为：用户说「导出用户数据」，直接写一个导出全量 JSON 的函数

    ✅ 应有行为：先问清楚 — 导出全部还是筛选？JSON 还是 CSV？哪些字段？数据量多大？

    模块 2：Simplicity First（简单优先）

    一句话：写能解决问题的最简代码，不加推测性功能。

    核心能力：

  • 禁止添加用户没要求的功能
  • 禁止单次使用的代码做抽象
  • 禁止不需要的「灵活性」和「可配置性」
  • 禁止为不可能的场景写错误处理
  • 200 行能 50 行解决就重写

    • 自检标准：「一个高级工程师会说这太复杂吗？」如果是，简化。

    适用场景：所有编码任务，尤其是脚本、工具函数、快速原型

    模块 3：Surgical Changes（外科手术式修改）

    一句话：只改必须改的，只清理自己制造的垃圾。

    核心能力：

  • 不「改进」相邻代码、注释或格式
  • 不重构没坏的东西
  • 匹配现有代码风格，即使你有不同偏好
  • 发现无关死代码时提一下，但不删

    • 清理规则：只删除你的改动导致的孤立代码（未使用的 import/变量/函数），不删已有的死代码。

    验收标准：每一行改动都应该能追溯到用户的请求。

    适用场景：Bug 修复、功能增强、代码审查中的小改

    模块 4：Goal-Driven Execution（目标驱动执行）

    一句话：把任务转化为可验证的成功标准，循环直到达成。

    核心能力：

  • 把「加验证」转为「写测试用例让非法输入失败，然后让它们通过」
  • 把「修 bug」转为「写一个复现测试，然后让它通过」
  • 把「重构 X」转为「确保重构前后测试都通过」
  • 多步任务用 1. [步骤] → 验证: [检查] 格式列出计划

    • 关键洞察：强成功标准让 LLM 能独立循环，弱标准（「让它能用」）需要反复确认。

    适用场景：多步骤任务、测试驱动开发、需要验收标准的工程任务

    —

    实测数据

    星标与增长

    指标 数值
    Star 数 207,175
    Fork 数 21,141
    Watcher 1,202
    创建时间 2026-01-27
    最后更新 2026-04-20
    许可证 MIT

    7 个月 207k Star，平均每月增长约 30k。对比参考：ECC（242k★）用了 7 个月，Caveman（100k★）同期数据。

    Token 成本对比

    Karpathy Guidelines 本身不直接节省 token（不像 Caveman 那样压缩输出），但通过减少以下行为间接节省：

    场景 无 Guidelines 有 Guidelines 节省估算
    过度工程重写 1000+ 行 → 被拒绝 → 重写 50-200 行一次到位 60-80%
    顺手重构导致的额外 review diff 混入无关改动 → 逐行审查 干净 diff → 快速合并 50%+
    假设错误导致的返工 实现完发现方向错 → 全部重来 先确认再实现 80-100%

    真实场景对比（EXAMPLES.md 摘录）

    场景：添加折扣计算函数

    无 Guidelines（LLM 常见输出）：

    from abc import ABC, abstractmethod
from enum import Enum
from typing import Protocol, Union
from dataclasses import dataclass

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float:
        pass
# ... 30+ 行

    有 Guidelines：

    def calculate_discount(amount: float, percent: float) -> float:
    """Calculate discount amount. percent should be 0-100."""
    return amount * (percent / 100)

    代码量对比：30+ 行 vs 3 行。如果需求真的需要多策略，等需要时再重构。

    —

    安装 + 适用场景 + 结语

    安装

    方式 A：Claude Code Plugin（推荐）

    /plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

    方式 B：CLAUDE.md（逐项目）

    新项目：

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

    现有项目（追加）：

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

    方式 C：Cursor

    仓库自带 .cursor/rules/karpathy-guidelines.mdc，直接在 Cursor 项目中生效。

    最适合谁

    角色 价值 推荐度
    个人开发者 减少 AI 返工，代码质量提升 ⭐⭐⭐⭐⭐
    小团队 统一 AI 协作规范 ⭐⭐⭐⭐
    技术负责人 建立 AI 编码标准 ⭐⭐⭐⭐
    初学者 学习「好代码」的标准 ⭐⭐⭐⭐⭐

    不适合谁

  • 追求极致速度的人：这些规则偏向谨慎，会增加确认环节
  • 简单任务：改个 typo 不需要四条铁律
  • 已经用 ECC 等系统级方案的人：功能重叠

    • 相关文章

  • ECC 实测：242k Star 的 Agent 操作系统，68 个 Agent 286 个 Skill 终结 AI 编程散装
  • Caveman 实测：一个 Skill 砍掉 AI 编程 65% token 成本

    • 合规披露

  • 数据来源：GitHub 仓库 multica-ai/andrej-karpathy-skills，截至 2026-08-25
  • Star/Fork 数据为实时 API 查询结果
  • EXAMPLES.md 对比为仓库官方示例
  • 未进行独立的 token 计数 benchmark，节省估算基于代码量对比推算
  • Karpathy 原始推文链接：https://x.com/karpathy/status/2015883857489522876

    • —

    一句话总结：Karpathy Guidelines 不是框架，不是插件，是一个 2.3KB 的 Markdown 文件 — 但它可能是性价比最高的 AI 编程改进：四条规则，零成本，直接提升代码质量和协作效率。