这是一个用于改进 Claude Code 行为的 CLAUDE.md 文件，源自 Andrej Karpathy 对 LLM 编码陷阱的观察。
一个CLAUDE.md文件让AI写代码从实习生秒变老油条工程师
一个CLAUDE.md文件通过四大原则约束AI编码行为，从源头减少错误假设、过度设计和无关修改，让模型稳定输出更像资深工程师的代码结果。
清晰规则约束直接改变AI行为输出质量。
你不用换模型，不用烧钱升级套餐，也不用折腾微调训练，你只要给AI一份写清楚规则的说明书，它立刻收敛，从“乱写代码的小聪明”变成“稳扎稳打的老工程师”。这个变化听起来像魔法，实际就是人类早就玩明白的套路：规则比天赋更重要。
再说直白一点，AI写代码翻车的根本原因是它太“自信”，脑补能力强到离谱，还不打招呼。你给它一个模糊需求，它直接拍脑袋开干，最后产出一坨逻辑复杂、结构膨胀、还顺手改了你隔壁文件的“艺术品”。这份CLAUDE.md干的事，就是把这种“自信型作死”掐死在摇篮里。
这个项目在GitHub上一周冲上趋势榜榜首，拿下了四万多颗星。一份不到70行的Markdown文件，没有一行正经代码，就靠写规则，干翻了无数花里胡哨的AI框架。这说明什么？说明被AI乱改代码折磨疯了的程序员，比我们想象的多得多。
问题从哪里冒出来
AI写代码翻车有一条非常稳定的因果链：模型误解需求直接导致错误实现不断放大。
它第一步就容易走偏。比如你说“加个校验”，它心里已经自动脑补出三种业务场景，然后选了一个你根本没想过的版本，还不问你。这个时候问题已经种下了，后面写再多代码都在错误轨道上狂飙。Karpathy自己就吐槽过，模型会代你做错误假设，然后不假思索地执行，不管理自己的困惑，不寻求澄清，不呈现矛盾，不展示权衡。
接着它会开始发挥“努力型选手”的本能。它会把简单问题复杂化，加一堆抽象层，设计一个未来十年都用不上的扩展结构。你本来要一个小工具，它给你搞出一个迷你框架，代码行数直接翻十倍。Karpathy的原话更狠：它们真的很喜欢把代码和API搞复杂，堆砌抽象概念，不清理死代码，明明100行能搞定的事情，非要实现成1000行的臃肿架构。
然后它还有一个经典操作：顺手优化你没让它动的地方。格式、注释、变量命名，全部动一遍。你打开diff一看，几十行改动里只有几行是你要的，剩下全是“顺便改改”。这就像你请人来修个水龙头，他顺手把你客厅的墙也刷了，还刷了个你不喜欢的颜色。
最后还有个隐藏杀手：它会删掉它看不懂的注释。它觉得“没用”，其实那是你项目里最关键的说明。这一刀下去，后面接手的人直接懵圈，得花半天时间重新理解这段代码到底是干什么的。
规则文件为什么能解决问题
规则明确直接约束决策路径就会改变结果。
这份CLAUDE.md干的事情非常朴素：它不让AI自由发挥，它让AI按流程办事。流程一旦固定，行为就稳定。这玩意儿的灵感来自Andrej Karpathy今年一月发的一条长推，阅读量接近800万，然后开发者Forrest Chang把大神的吐槽翻译成了AI能执行的规则。
你可以把它理解成一个“代码行为交通规则”。平时AI开车像个刚拿驾照的小伙子，看到空路就猛踩油门，看到岔路就随便选一条。这份文件直接给它装上红绿灯、限速牌、导航系统。
关键点在于，这些规则不是抽象口号，而是具体动作指令。翻译成大白话就是：先说你猜了啥，有歧义列出来，有更简单的方案要顶嘴。这就把AI从“闷头干活”变成“先沟通再动手”。错误自然大幅下降。
而且用起来贼简单。Claude Code用户两条命令装插件，Cursor用户把文件拷到项目根目录改个名就行。你不需要学新东西，不需要配服务器，甚至不需要重启IDE。装完之后你开一个新任务，立刻就能感觉到AI不对劲了——它开始问问题了，开始犹豫了，开始不敢乱动了。
思考优先如何卡住错误源头
先思考再动手直接减少错误假设。
Think Before Coding这个原则其实是整个系统的起点，它解决的是最早那一步“脑补失控”的问题。
AI以前的流程是：看需求 → 选一个理解 → 开写代码。
现在变成：看需求 → 写出所有可能理解 → 标注不确定点 → 再问你。
这个变化非常关键。因为一旦它把不确定点暴露出来，你就能在最便宜的阶段纠正它。这个阶段成本接近零。你说一句话，它回一段话，你纠正一下，它再去写代码。比起写完200行再删掉重来，这个成本可以忽略不计。
举个简单例子，你说“加登录限制”。它会列出：可能是限制登录次数，可能是限制IP，可能是限制设备，然后问你选哪个。这一步一旦做了，后面就不会写错方向。以前它是闷头选一个，写完了你发现错了，它再改，改的时候又顺手改了别的，恶性循环。
而且还有一个隐藏好处：它会开始“顶嘴”。如果它发现你要的方案很复杂，它会直接说“有更简单的”。这就是从执行工具变成合作伙伴的转变。你花钱请了个只会点头的实习生，和请了个会提建议的老员工，感觉完全不一样。
简单优先如何砍掉代码膨胀
限制复杂度直接压缩代码体积。
Simplicity First这个原则干的事情非常粗暴：一刀砍掉所有“未来可能用到”的设计。
AI有个坏习惯，特别爱加“灵活性”和“可扩展性”。听起来很高级，实际就是提前过度设计。就像你买个电饭煲，它给你附带火箭发射功能——听起来很酷，但你一辈子用不上，还占地方。
规则直接写死：不加未请求的功能，不做一次性用的抽象，如果200行能写成50行就重写。翻译一下就是：你只干现在这件事，多一行都不行。
这会带来一个非常明显的结果：代码短了，而且更容易读。资深工程师最喜欢这种风格，因为维护成本低。你想想，你接手一个项目，一个文件200行，另一个文件2000行但功能一样，你想看哪个？
而且这个规则还有一个“自检机制”：如果一个老工程师看了觉得复杂，那就重写。这一句话等于把经验写进规则里。你不用给AI培训三年，不用教它什么叫“代码坏味道”，一句话搞定。
外科手术式修改如何防止误伤
限制改动范围直接保护原有代码稳定。
Surgical Changes这个原则解决的是“顺手乱改”的问题。AI以前像个装修队，修一个水龙头，顺手把你客厅也刷一遍漆。你心里想的是“我就让你修个水龙头”，它心里想的是“我给你家免费升级一下”。
现在规则很明确：不动旁边的代码，不动没坏的东西，匹配现有的代码风格。意思很简单：你只动用户点名的地方，其它地方保持原样。
这里最狠的一条是：每一行改动都必须能追溯到需求。这句话相当于给每一行代码都贴了“理由标签”。没有理由的改动直接不允许存在。你想想Code Review的时候，你看到一行改动，问“这行为什么改”，AI能答上来，你就放心了。答不上来，这行就不能要。
还有一个细节很妙：它允许你“提醒问题”，但不允许你“动手修”。比如你看到别的地方有垃圾代码，你可以说一句“哥们这儿写得不太行”，但不能直接删。这就避免了范围失控。你知道了问题，但你选择不动，这就是纪律。
目标驱动执行如何让AI自我循环
明确目标直接驱动AI自动完成闭环。
Goal-Driven Execution是整个体系的发动机。它解决的是“什么时候算完成”这个问题。
AI以前的完成标准很模糊，它觉得“差不多了”就停了。这就像你跟一个小孩说“把房间收拾干净”，他收了两件玩具就说“好了”。你觉得不行，他觉得行，标准不一样。
现在规则要求必须有“可验证的成功标准”。比如“修Bug”这个任务，变成“先写一个能重现Bug的测试，再让测试通过”。这一下就变了。因为“测试通过”是一个非常明确的终点，AI可以自己循环直到达成。
这个机制利用了AI最擅长的能力：重复执行直到满足条件。你给它一个清晰终点，它会像打游戏刷任务一样一直干到完成。跑不过就改，改完再跑，跑过了就停。你不用在旁边催它。
还有一个好处是减少沟通成本。你不用一直盯着它改，它自己会检查、修正、再检查。你只需要在开始的时候说清楚“终点在哪”，然后去喝杯咖啡，回来它就搞定了。
为什么一份文件就够了
统一规则入口直接覆盖所有行为路径。
很多人第一反应是：这么多规则，得搞一套复杂系统吧。结果这个项目反其道而行之，只用一个CLAUDE.md文件。
原因很简单：Claude Code在执行前会读这个文件。这个文件相当于“全局行为说明书”。所有操作都会参考它。有研究分析了253个开源项目的CLAUDE.md文件，发现它们普遍采用浅层结构，用一个主标题搭配多个二级章节，内容集中在构建命令、实现细节和架构说明上。这说明大家达成的共识是一样的——一份说明书就够了，不用搞复杂。
你只需要把它丢进项目里，路径大概像这样：
/project-root |
然后AI每次动代码前都会先“看说明书”。这就像你给员工发了一本操作手册，他每次干活前都得翻一眼。你不用每次都喊一遍“记得先想再写”“记得别改旁边代码”，它自己会看。
更关键的是，这种方式成本极低。没有部署，没有配置，没有学习成本。团队成员也能共享同一套规则，行为一致性直接拉满。新人入职，把代码库clone下来，CLAUDE.md就在根目录里，AI助手的行为和团队里其他人完全一致，不需要额外培训。
为什么这个方案性价比离谱
低成本约束高价值输出直接放大效率。
你看那些订阅价格：Claude Pro每月20美元，更高级的套餐每月200美元，GitHub Copilot每月10美元。这些都是“换更强模型”的思路，属于堆硬件。你花更多钱，买更强的算力，希望它变聪明。
这个方案走的是另一条路：优化使用方式。成本是0，效果却能接近“换了一个更靠谱的工程师”。你不用多花一分钱，同一个模型，同一个账号，只是多了一个规则文件，输出质量就不一样了。
本质上这是在做一件事：把隐性经验显性化。资深工程师脑子里的那些判断标准——什么时候该问清楚、什么时候该简化、什么时候该停手——被写成了规则文件。AI照着执行，就能复现一部分经验。
这就像你给一个新员工一份详细的SOP，他表现会立刻提升一个档次。你不用等他干三年积累经验，你把经验写下来，他照着做就行了。AI也是一样，你把“老工程师的脑内规则”写下来，它就不犯那些低级错误了。
有个用户的反馈说得很到位：长任务成功率明显提升，AI不再想到哪写到哪，Code Review压力降了很多。唯一的副作用是琐碎任务会稍微变慢一点，因为AI会多问一句“你确定吗”。这个代价完全可以接受，毕竟慢两秒钟和改两百行代码，你选哪个？
最后
规则明确直接约束行为路径最终稳定输出质量。
整个事情串起来非常清晰：AI默认行为容易脑补 → 脑补导致错误 → 错误被复杂化放大 → 输出失控
加入CLAUDE.md后变成：规则限制脑补 → 提前暴露不确定 → 简单方案优先 → 修改范围受控 → 目标驱动验证
最后结果就是：代码更短、改动更少、错误更早被发现、沟通更顺畅。
这套东西看起来只是“写了一份说明书”，实际是在重写AI的行为逻辑。你没有改变模型，你改变了它做决定的方式。这就像你给一个人换了副眼镜，他没换脑子，但他看东西清楚了。
说得再直白一点，这玩意的本质就是一句话：你把AI当人管，它就开始像人一样靠谱。你给它定规矩、划边界、给流程，它就按流程走。你由着它瞎搞，它就给你搞出一堆烂摊子。AI不会变，变的是你管它的方式。
你花一分钟把这个文件丢进项目根目录，今天就能感受到差别。不用等，不用学，不用花钱。就这么简单。