GitHub 1.5万星项目揭秘：让Claude写出可靠代码的四大黄金原则

GitHub 1.5万星项目揭秘：让Claude写出可靠代码的四大黄金原则

基于Andrej Karpathy的实战观察，一个配置文件拯救你的AI编程体验

你有没有遇到过这样的情况：

让Claude帮你改代码，结果它顺便"优化"了无关部分，导致其他功能崩溃；
让它重构一个模块，结果写出了1000行的"优雅"实现，而实际上50行就够了；
让它添加一个功能，它默默做了一堆你没要求的假设，最后完全不是你想要的。

这不是你一个人的困扰。就连AI界的大神Andrej Karpathy（前OpenAI AI负责人、特斯拉自动驾驶AI负责人）也在X上吐槽过：

"模型会替你做错误的假设，然后就那样执行下去，从不检查。它们不会管理困惑，不会寻求澄清，不会暴露权衡取舍，该反驳的时候也不会反驳。"

"它们真的喜欢把代码和API搞得过于复杂，膨胀抽象层，不清理死代码……明明50行能解决的问题，它能写1000行。"

"它们有时会删除或修改它们不理解也不应该碰的代码和注释，即使与任务完全无关。"

最近，一个叫forrestchang的开发者基于Karpathy的这些观察，整理出了一个单文件配置——CLAUDE.md，在GitHub上狂揽1.2万+ stars（今日新增1070），成为AI编程圈的现象级项目。

今天就来深度拆解这个项目，教你如何用四大黄金原则让Claude写出更可靠的代码。

---

🎯 四大原则，直击痛点

这个配置的核心是四个原则，每个都针对LLM编程的一个典型问题：

原则一：Think Before Coding（先思考，再编码）

问题：LLM会默默选择一种理解方式，然后就按这个理解跑下去，从不检查是否正确。

解决方案：

• ✅ 明确陈述假设——不确定就问，别猜
• ✅ 提供多种解读——有歧义时不要默默选一个
• ✅ 该反驳就反驳——如果有更简单的方案，说出来
• ✅ 困惑就停——明确说哪里不清楚，请求澄清

实战对比：

❌ 错误命令：

"添加用户验证功能"

✅ 正确命令：

"需要添加用户验证功能。我的理解是：
- 对所有API端点添加JWT验证
- 使用现有的auth中间件
- 公开端点（登录、注册）不需要验证

这个理解对吗？还是你想要其他范围？"

Claude会先确认理解，再动手，避免做了一堆无用功。

---

原则二：Simplicity First（简洁第一）

问题：LLM有过度工程化的倾向，喜欢搞抽象、加配置、处理"可能出现的场景"。

解决方案：

• 🚫 不做需求之外的功能
• 🚫 不为一次性代码搞抽象
• 🚫 不加没要求的"灵活性"
• 🚫 不处理不可能出现的错误
• ✅ 如果200行能简化成50行，就重写

判断标准：一位资深工程师看了会说"这也太复杂了"吗？如果是，简化它。

实战对比：

❌ Claude默认倾向（过度抽象）：

// 为了"未来可能复用"，搞了一堆工厂模式、策略模式
interface ValidatorFactory {
  createValidator(type: ValidationType): Validator;
  getValidatorConfig(type: ValidationType): Config;
  registerValidator(type: ValidationType, impl: ValidatorImpl): void;
}

// ... 500行代码，但你只需要验证邮箱格式

✅ 应用原则后（简洁直接）：

// 直接解决问题，3行代码搞定
function isValidEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

---

原则三：Surgical Changes（外科手术式修改）

问题：LLM会顺手"优化"相邻代码、修改格式、重构它认为"不够好"的部分，甚至删除它不理解的代码。

解决方案：

• 🚫 不要"改进"相邻代码、注释或格式
• 🚫 不要重构没坏的部分
• ✅ 保持现有风格，即使你不会这么写
• ✅ 如果看到无关的死代码，提一下——别删它
• ✅ 只清理你的改动造成的孤儿代码（无用的import、变量、函数）

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

实战对比：

❌ Claude默认倾向（顺手重构）：

- // 用户要求：修复bug
+ // 修复bug
  const result = calculateResult();
  
- // Claude顺手改的：格式化
+ const formattedResult = formatResult(result);
  
- // Claude顺手改的：添加"可能的"错误处理
+ if (!formattedResult) {
+   throw new Error("Result is empty");
+ }
  
- // Claude顺手改的：重构函数名
- function calculateResult() {
+ function computeResult() {
    return data.reduce((acc, item) => acc + item.value, 0);
  }

✅ 应用原则后（精准修改）：

- // 用户要求：修复bug
  function calculateResult() {
    if (!data || data.length === 0) return 0;
    return data.reduce((acc, item) => acc + item.value, 0);
  }

只修复bug，不改其他任何东西。

---

原则四：Goal-Driven Execution（目标驱动执行）

问题：模糊的指令（"让它工作"、"修复bug"）导致LLM需要反复澄清，效率低下。

解决方案：将命令式任务转换为可验证的声明式目标。

命令转换对照表：

不要这样说 ❌	要这样说 ✅
"添加验证"	"为无效输入编写测试，然后让它们通过"
"修复bug"	"编写一个重现bug的测试，然后让它通过"
"重构X"	"确保前后测试都通过"

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

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

实战对比：

❌ 模糊命令：

"让用户注册功能工作"

Claude可能会：

• 改数据库schema
• 改API接口
• 改前端表单
• 改验证逻辑
• ...而且每个都问你"对吗？"

✅ 目标驱动命令：

"用户注册功能问题排查：
1. 编写测试：POST /api/register 成功返回token
2. 编写测试：重复邮箱返回400错误
3. 修复代码让这些测试通过
"

Claude会自主循环执行，直到目标达成。

---

🚀 如何安装使用

方式一：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

---

📊 如何判断生效

应用这些指南后，你应该能看到：

✅ diff中的不必要改动更少了——只出现请求的改动
✅ 因过度复杂化导致的重写减少了——代码第一次就写对了
✅ 澄清问题在实现之前就来了——而不是在错误之后
✅ 干净、最小化的PR——没有drive-by重构或"改进"

---

💡 实战建议

1. 与项目特定规则结合

这些指南可以和项目特定规则合并。例如：

## Project-Specific Guidelines

- 使用TypeScript严格模式
- 所有API端点必须有测试
- 遵循 `src/utils/errors.ts` 中的错误处理模式

2. 简单任务可灵活调整

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

目标是在非平凡工作上减少昂贵错误，而不是拖慢简单任务。

3. 循序渐进

不需要一次性应用所有原则。可以从"Goal-Driven Execution"开始，因为它最容易上手，然后逐步加入其他原则。

---

🎓 Karpathy的终极建议

最后，再引用一次Karpathy的话：

"LLM在循环执行直到达成特定目标方面非常出色……不要告诉它做什么，给它成功标准，看着它完成。"

"Goal-Driven Execution"原则正是抓住了这一点：将命令式指令转换为带验证循环的声明式目标。

---

📝 总结

这个12k stars的项目本质上做了一件事：把AI编程的最佳实践固化成一个配置文件。

它的核心思想很简单：

• 🤔 别让AI猜
• ✨ 别让AI过度设计
• 🎯 别让AI顺手改无关代码
• 🔄 给AI明确的目标和验证标准

但正是这些简单原则，能显著提升AI编程的可靠性和效率。

现在就试试吧：

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

你的下一次AI编码体验，可能会完全不同。

---

项目地址：**github.com/forrestchan…
Karpathy原文：**x.com/karpathy/st…

---

👋 觉得有帮助吗？点赞、在看、转发，让更多人写出更好的AI代码！

---