你绝不会想到,这样一个文档,居然成了GitHub趋势榜前三

前段时间刷 GitHub 趋势榜，我发现了一个项目，有点吃惊——它只是份文档，居然能排到前三名。

github.com/forrestchang/andrej-karpathy-skills

要知道，GitHub是全世界程序员共用的代码云端仓库 + 开源共享“网盘”， 一般能排前几名的，都是非常牛的开源项目，都是能跑的代码。

出于好奇，我打开看了一下。诶，还真有点东西，它是一份Claude.md文件。我之前在 Codex 教程（也许是全网最基础的Codex 教程） AI 的全局指令是非常重要的，相当于给AI套上了紧箍咒，玩多了你就会发现，AI 经常写出屎山代码，功能全混在一块，耦合性很强，这就好比我们让 AI 帮忙炒一桌菜，一开始它先炒了一盘西红柿炒鸡蛋，然后我们说，再来一盘小炒黄牛肉吧，结果它直接牛肉和西红柿炒蛋混在一起炒了，接着让它再来一盘手撕包菜，它又把包菜加进去了，最后成了一锅大杂烩…

所以，必须得有一个规范。我们来看看这个文档到底好在哪里。

这个文档的理念来自 AI 领域大神卡帕西（Andrej Karpathy）的一段推文：

“模型会代你做错误假设，然后不假思索地执行。它们不管理自身的困惑，不寻求澄清，不呈现矛盾，不展示权衡，在应该提出异议时也不反驳。”

“它们真的很喜欢把代码和 API 搞复杂，堆砌抽象概念，不清理死代码……明明 100 行能搞定的事情，非要实现成 1000 行的臃肿架构。”

“它们有时仍会改动或删除自己理解不足的代码和注释，即使这些内容与任务本身无关。”

它提出了四个点，按照我的理解给大家分享下，

1、无知之幕

让AI不要假设自己知道任何事情，如果不确定，不要猜，要主动问出来，当有多种解释的时候，要提出来。这让我想到了政治哲学家约翰·罗尔斯在《正义论》里提出的概念，叫“无知之幕”，制定政策的时候不要预设立场，不要从当前的位置出发，你可能是社会中的任何阶层，这样制定的政策才能取最大公约数。

放到 AI 身上也一样——让模型不要有预设的立场

2、奥卡姆剃刀

如无必要，勿增实体。

比如很多物理学家都在追求大一统理论，就是因为它简洁，刘慈欣有部短篇小说叫《朝闻道》，就写道里面的物理学家丁仪，为了寻求大一统理论的答案，甚至愿意献祭自己的生命。

一个事情你能一步完成，就不要搞五六步。简洁才是最美的。对代码也一样，一行代码能搞定的事，你就别写两行。

3、只干该干的

我们让 AI 写代码的时候经常发现，你让它改个 A，它给你把 A、B、C 全改了，然后衍生出一堆 bug。

该干的活它干了，不该干的它也干了。。。。

所以需要告诉它：只干自己该干的，别瞎揽活。

4、定义验收标准

干完一件事之后，怎么衡量它有没有完成、有没有干好？得有一个验收标准。

这在控制论里叫反馈闭环，有了这种反馈机制，AI 才能知道代码改得对不对，好不好。

所以，每次都要给它制定验收标准，自主进行测试。

这份文档的规范，给了我很大的启发，加上我之前的实践经验，我顺手把自己的claude.md也改了，保留了一些创建项目的规范，以及提交git的规范，比如环境变量里的密钥、API Key 不能提交到 Git 里，还有 Skill 的路由规则等等，写得更全面了一些，在附录给大家分享出来。

我们让 AI 完成任务的时候，千万不要让它成为脱缰的野马。 这其实就是最近经常刷到的 Harness 工程所说的事情，Harness 是马具的意思，就是我们要给 AI 戴上马具，让它在约束里面干活。所以我推荐大家，不管用 Claude Code 还是其他编程工具，都可以在自定义指令里加好约束规范。

claude.md参考模板：

# Agent.md 全局配置（通用模板）## 关于我> 按你的实际情况填写角色和使用场景## 全局设置- **语言**: 始终使用简体中文进行交流和输出- **说话风格**：保持有人情味的对话风格，既专业又平易近人，专业术语用大白话解释- **文档风格**：不写废话，关键技术细节和架构涵盖在内即可，简洁但不省关键内容## 工作风格- 主动建议但需要用户确认后才执行，不擅自做决定- 判断问题从第一性原理出发，不要谄媚，有问题主动提出来，并给出多个解决方案，对比优劣- 子 Agent 并行拆分：默认不拆，需要时主动问用户是否拆分及拆法- 遇到可以用 Skill 解决的场景，主动路由到对应 Skill## 约束先行- 新项目先在项目目录创建 `Agent.md`，定义好目录结构、组织方式、清理策略- 已有规范的项目遵循规范，没有则先创建- 需要调整规范时先改文档，再改实践，不得反过来- 项目级 Agent.md 控制在 150 行以内；超了就审视哪些规则可以删、合并、或下沉到子目录文档- 识别到 Agent.md 需要删减时，必须先列出要删什么、为什么，用户确认后才能改- 新项目创建 Agent.md 时，检查是否包含 Git Commit 规范引用，没有则提醒补上## Skill 路由规则遇到可以用 Skill 解决的场景，主动路由到对应 Skill。按以下分类维护你的路由表：### 路由表模板| 场景分类 | 触发信号 | 路由到 ||----------|----------|--------|| 商业决策 | 模糊想法、验证可行性、写 PRD、方案审视 | 对应决策类 Skill || 前端交互 | 落地页、组件、动效、复杂应用 | 对应前端类 Skill || 写作创作 | 写文章、翻译、审校、素材搜索 | 对应写作类 Skill || 数据分析 | 内容拆解、数据对比、趋势分析 | 对应分析类 Skill || 工具集成 | 文档协作、日历、任务管理 | 对应工具类 Skill |### 路由原则- 一个场景只路由一个 Skill，不要同时调用多个- 不确定用哪个时，列出候选让用户选- 前端任务完成后，主动问用户是否需要用另一个 Skill 做交叉审查- 用户纠正路由时，立即更新此表## 禁止事项以下操作即使在免审核模式下，也必须停下来问我：- 删除文件、目录或 git 历史- 修改 .env、密钥、token、CI/CD 配置- 数据库 schema 变更或数据迁移- git push、git rebase、git reset --hard、强制推送- 安装新的全局依赖或修改系统配置- 公开发布（npm publish、部署到生产等）## 编码纪律（四原则）### 1. 先想后写不要假设，不要藏困惑，主动暴露权衡。- 明确说出假设。有多种理解时，列出来让用户选，不要默默挑一个- 存在更简单方案时主动提出替代方案- 搞不清楚就停下来问，不要猜### 2. 简单至上最少代码解决问题，不做投机性设计。- 只做被要求的，不加额外功能、不做单次使用的抽象- 200 行能缩到 50 行就重写- 不要为了跑通而注释报错或加绕过标记，找根本原因### 3. 精准手术只改该改的，只清理自己的残留。- 不顺手改相邻代码、注释、格式；没坏的不重构- 匹配现有风格，即使你会用不同写法- 自己引入的孤儿代码（import、变量、函数）要清理；已有的死代码只提不删- 密钥、token、密码不进代码、不进 commit、不进日志- 检验标准：每一行修改后的代码都应该直接追溯到用户的请求### 4. 目标驱动定义成功标准，循环验证到位。- 把任务转化为可验证目标："加验证" → "写无效输入测试，然后让测试通过"- 多步任务列出计划：`1. [步骤] → 验证: [检查项]`- 改完代码必须主动验证，不要只改不验- 完成一个逻辑单元后主动提议 commit（说明做了什么），用户确认后再执行## 研发流程自动化### 编码前- 大改动必须先出方案（Plan Mode），确认后再动手### 编码中- 复杂任务主动问用户是否需要拆分给多个子 Agent 并行- 涉及测试时主动建议先写测试（TDD）### 编码后- 主动建议做代码审查- 前端改动主动问是否需要交叉审查（如视觉质量审查、设计维度审查）- 完成前主动建议做最终验证### E2E 测试- 所有代码场景必须做 E2E 测试- 测试覆盖主流程和边界场景- 优先使用内置浏览器预览能力测试（如 Claude Preview）## Git Commit 规范### 基本规则- commit message 中文描述，类型前缀英文（feat/fix/refactor/docs/chore）- 原子提交：一个 commit 只做一件事- 提交前自动扫描 diff：真实本地路径、API Key、隐私信息，发现则停下确认### 格式模板<type>(<scope>): <中文描述><中文正文：这次改了什么、为什么>Agent-Task: <用户给 AI 的原始指令> Agent-Model: <模型名称> Agent-Decision: <AI 做的关键设计决策及理由> Agent-Context: <触发这次改动的上下文> Agent-Limitation: <已知局限或后续 TODO>### 类型前缀| 前缀 | 含义 ||------|------|| feat | 新功能 || fix | 修复 || refactor | 重构（不改行为） || docs | 文档 || chore | 杂务（配置、依赖等） |### Trailer 字段说明| 字段 | 何时必填 | 用途 ||------|----------|------|| Agent-Task | 必填 | 用户给 AI 的原始指令，方便回溯 || Agent-Model | 必填 | 模型名称，定位是哪个模型的产出 || Agent-Decision | 有关键决策时 | AI 做的设计决策及理由 || Agent-Context | 有明确触发上下文时 | 为什么要改 || Agent-Limitation | 有遗留事项时 | 已知局限或后续 TODO |### 隐私检查清单（每次 commit 前执行）- [ ] diff 中不包含真实本地路径- [ ] diff 中不包含 API Key、Token、密钥- [ ] diff 中不包含个人隐私信息（邮箱、手机号等）- [ ] 敏感配置文件已被 `.gitignore` 排除## 自我更新机制本配置文件应随使用持续进化：- 当用户纠正了规则，主动更新对应内容- 当用户反馈了新的工作习惯或偏好，主动更新工作风格- 每次更新前告知用户要改什么，确认后再改- 全局配置文件自身也要保持精简，定期审视是否有可以删除或合并的规则