AI代码生成规范：Karpathy的55K星项目，用CLAUDE.md约束LLM写出简洁代码

你有没有遇到过这种情况？让AI修复一个bug，结果它不仅改了问题代码，还顺手调整了不相关的注释和格式，甚至“贴心”地给你添加了根本没要求的新功能。又或者，你只是想让它写个简单的折扣计算函数，它却给你生成了一整套抽象的策略模式架构。

前特斯拉AI总监、OpenAI联合创始人Andrej Karpathy在今年一月的一条推文中，精准地指出了大型语言模型（LLM）在编程时的普遍问题。而开发者Forrest Chang（张嘉元）在推文发布的第二天，就将Karpathy的观察落地，创建了一个可执行的开源项目——一个仅50行的行为规范文件。

这个名为 andrej-karpathy-skills 的项目，在 GitHub 上已获得约 55K Stars，峰值时每周增长超过6000星。它不是什么新框架，而是一套旨在让AI助手写出更干净、更精准代码的指导原则。

本文将为你详细拆解这个项目的核心思想、具体使用方法和实际应用价值。

01 Karpathy指出了什么？

Karpathy的推文点出了当前AI编程的三大顽疾：

“模型会替你做错误假设然后一路狂奔。它们不管理困惑、不寻求澄清、不暴露矛盾、不展示权衡、该反驳时不反驳。”

“它们特别喜欢把代码和API搞复杂，膨胀抽象层，不清理死代码……100行能搞定的事，给你写1000行。”

“它们有时会删除或修改自己没充分理解的注释和代码，即使跟任务完全无关。”

这三句话，几乎每个深度使用过AI编程工具（如Claude Code、Cursor、GitHub Copilot）的开发者都深有体会。问题很明确，但如何解决呢？

Forrest Chang的答案简洁有力：用一个文件，四条核心原则，直接约束AI的行为模式。

02 四条核心行为原则

原则一：先思考，再编码

核心准则：不要假设。不要隐藏困惑。主动暴露权衡。

AI最常见的毛病就是“自己默默选了一个理解，然后一路写到底”。这条原则强制AI在动手写代码之前，必须先进行思考并和你沟通：

• 对于不确定的需求，要明确列出假设，而不是去猜测。
• 当存在多种实现可能时，要把所有选项摆出来让你选择。
• 如果存在更简单的方案，需要主动提出。
• 如果对需求或上下文感到困惑，必须停下来提问，而不是硬着头皮去写。

实际场景
当你提出“给系统加一个用户导出功能”时，AI不应该立刻开始写导出逻辑。它应该先反问：是导出所有用户，还是筛选后的结果？导出为CSV/Excel文件，还是通过API返回JSON？需要包含用户的哪些字段？预估的数据量有多大？

原则二：简单优先

核心准则：只写解决问题的最少代码。不做任何推测性功能。

这是对抗AI“过度工程化”倾向的核心武器。我们来看一个真实的代码对比：

❌ LLM常见的过度设计（30+行）：

from abc import ABC, abstractmethod
from dataclasses import dataclass

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

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: float):
        self.percentage = percentage
    def calculate(self, amount: float) -> float:
        return amount * (self.percentage / 100)

class FixedDiscount(DiscountStrategy):
    def __init__(self, fixed_amount: float):
        self.fixed_amount = fixed_amount
    def calculate(self, amount: float) -> float:
        return min(self.fixed_amount, amount)

@dataclass
class DiscountConfig:
    strategy: DiscountStrategy
    min_purchase: float = 0.0
    max_discount: float = float('inf')

class DiscountCalculator:
    def __init__(self, config: DiscountConfig):
        self.config = config
    def apply_discount(self, amount: float) -> float:
        if amount < self.config.min_purchase:
            return 0
        discount = self.config.strategy.calculate(amount)
        return min(discount, self.config.max_discount)

✅ 实际需要的（2行）：

def calculate_discount(amount: float, percent: float) -> float:
    return amount * (percent / 100)

左边的代码使用了策略模式、抽象基类、数据类，看起来非常“专业”和“可扩展”，但用户实际可能只需要一个简单的百分比计算。好的代码是解决今天问题的最简方案，而不是提前为明天可能永远不存在的问题做复杂的架构。

原则三：精准改动

核心准则：只改你必须改的。只清理你自己制造的混乱。

假设用户提出的需求是“修复空邮箱导致校验崩溃的bug”。一个没有约束的AI可能会做出以下“多余”操作：

• 修改了不相关注释的措辞。
• 添加了用户名长度的校验（没人要求）。
• 添加了用户名合法字符的校验（没人要求）。
• 统一了代码中的引号风格（单引号改双引号）。
• 为函数添加了文档字符串。

正确的做法应该只修改与bug直接相关的代码行：

• 只修改两处：1) 处理 email 为空字符串的情况；2) 用更安全的方式获取 email 值。
• 其余所有代码，一字不动。

判断标准
每一行代码的改动，都应该能够追溯到用户的原始请求。如果某行修改找不到对应的请求依据，那么这行就不应该被改动。

原则四：目标驱动执行

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

这是Karpathy洞察中最核心的一点：

“LLM在‘循环直到达成具体目标’这件事上异常出色……别告诉它做什么，给它成功标准，然后看它执行。”

我们需要把模糊的、主观的指令，转化为清晰、可验证的目标：

• 模糊指令（弱）：“给这个函数加上输入验证。”
• ✨ 可验证目标（强）：“为这个函数的无效输入编写测试用例，然后修改函数让这些测试全部通过。”
• 模糊指令（弱）：“修复这个登录的bug。”
• ✨ 可验证目标（强）：“写一个能够复现这个登录bug的单元测试，然后修改代码让这个测试通过。”

对于多步骤的复杂任务，可以采用“验证链”的方式：

1. 编写测试：用户修改密码后，其所有旧会话应立即失效。
   验证：新写的测试失败（成功复现了bug）。

2. 实现功能：在密码修改逻辑中，添加清除用户所有活跃Session的代码。
   验证：上一步的测试通过。

3. 检查边界情况：多个活跃Session、并发修改密码等场景。
   验证：为边界情况编写的额外测试也全部通过。

4. 回归检查：确保现有的所有认证相关测试仍能通过。
   验证：完整的测试套件运行结果为绿色（全部通过）。

03 如何安装与使用？

项目支持三种主流开发工具链，其核心只是一个名为 CLAUDE.md 的50行文本文件。

方式一：Claude Code 插件（推荐 ⭐️）

在Claude Code中执行以下两条命令即可：

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

安装后，这些行为规范将作为插件自动加载，并在你所有的Claude Code项目中生效。

方式二：下载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

方式三：Cursor IDE

将项目中提供的 .cursor/rules/karpathy-guidelines.mdc 文件，复制到你自己的项目目录下的 .cursor/rules/ 文件夹中。Cursor IDE会自动识别并应用该规则文件。

04 适合谁用？有什么局限性？

✅ 适合人群

• 日常使用 Claude Code 或 Cursor 进行开发的工程师，受够了AI的“自作主张”和过度设计。
• 在团队协作中，需要AI生成的代码改动具备高可审计性和可追溯性。
• 希望将AI助手从一个“想法很多但总跑偏的实习生”，转变为一个“精准高效的高级工程师”。

⚠️ 存在的局限性

• 偏向谨慎：对于极其简单的任务（如修复拼写错误），这套规范可能显得约束过度，需要开发者根据情况自行判断。
• 非代码生成工具：它本身不会帮你写代码，只是一套约束AI如何写代码的“行为守则”。
• 工具亦有误：项目README中曾出现过安装URL拼写错误的bug。这提醒我们，对于任何开源项目的安装指南，亲自验证一步总是好的。

🎯 如何判断它生效了？

• 代码的Diff（差异对比）中，只包含你明确要求修改的部分，看不到任何“顺手”的格式调整或无关优化。
• AI第一次生成的代码就足够简洁、直接，不需要你反复要求它“精简一点”。
• 在开始编写代码之前，AI会主动向你提问，澄清模糊的需求，而不是写完一版后再让你指出问题。

总结

andrej-karpathy-skills 并非又一个AI代码生成工具，而是一套关于 “如何与AI高效协作” 的行为规范。它巧妙地将Karpathy对LLM编程的深刻洞察，转化为了四条清晰、可执行的原则。其核心思想可以归结为一句话：不要只告诉AI要做什么，更要清晰地告诉它，什么样的结果才算成功。

一个仅50行的文件，能收获超过5.5万颗星，这充分说明了“AI代码臃肿和不可控”是一个普遍且强烈的痛点，而Forrest Chang提供的这个答案，以其极致的简洁性击中了要害。如果你也在寻求让AI编程变得更可控、更高效的方法，不妨试试这个项目。欢迎在云栈社区分享你的使用体验和心得。

项目地址：
https://github.com/forrestchang/andrej-karpathy-skills

许可证： MIT