删除你的 CLAUDE.md：为什么过度文档化正在损害你的 AI 编程体验

## 一、引言：那个被过度神化的文件 如果你用过 Claude Code、Cursor 或其他 AI 编程助手，你一定见过或创建过这样的文件： - `CLAUDE.md` - `AGENT.md` - `.cursorrules` - `AGENTS.md` 这些文件被奉为"让 AI 理解项目的圣经"。无数教程告诉你："一定要写好 CLAUDE.md，这样 AI 才能正确理解你的代码库。" 但最近一项研究和 Theo 的实测，却指向了一个反直觉的结论： **这些文件可能正在损害你的 AI 编程体验。** --- ## 二、研究发现了什么？ ### 论文核心结论 一项针对 AI Agent 指令文件的最新研究发现： | 场景 | 效果 | |------|------| | **开发者提供的指令文件** | 仅能微增性能（边际收益递减） | | **AI 生成的主动文件** | 增加 20%+ 成本和错误率 | | **无指令文件** | AI 自主探索，性能相当甚至更优 | **关键发现：** - 过度复杂的 agent.md 会导致模型产生**偏见** - 模型会尝试文件中提到的**过时技术栈** - 文件中的**虚假路径**会误导模型搜索 ### 文件审计的警示 Theo 审计了自己的项目库，发现典型的 agent.md 存在这些问题： ```markdown # 典型的问题 AGENT.md ## 技术栈 - 使用 React 18（实际已升级到 19） - 状态管理用 Redux（实际已迁移到 Zustand） - 测试用 Jest（实际已改用 Vitest） ## 目录结构 - src/components/（实际已重构到 app/） - src/utils/（实际已删除） ``` **结果：** AI 被这些过时信息带偏，反复尝试不存在的路径和废弃的技术。 --- ## 三、AI 上下文的真相 ### 三层提示词架构 要理解为什么指令文件可能有害，需要了解 AI 系统的上下文层级： ``` ┌─────────────────────────────────────────┐ │ 第一层：系统提示词 (System Prompt) │ │ - 由平台/工具提供 │ │ - 定义 AI 的基本行为和能力 │ │ - 用户无法直接修改 │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ 第二层：开发者消息 (Developer Message) │ │ - CLAUDE.md / AGENT.md 所在层级 │ │ - 项目级上下文 │ │ - 每次请求都会携带 │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ 第三层：用户指令 (User Instruction) │ │ - 当前对话的具体请求 │ │ - 优先级最高 │ │ - 动态变化 │ └─────────────────────────────────────────┘ ``` ### 关键问题：层级污染 **CLAUDE.md 的问题在于它处于"中间层"：** - 它比系统提示词更具体 - 但它比用户指令优先级低 - **它无法被动态更新** 这意味着： 1. 文件中的信息会**持续占用上下文空间** 2. 即使信息已过时，AI 仍会**参考它** 3. 用户指令需要**覆盖**文件中的偏见 --- ## 四、帮助模型，而非干扰 ### 过长上下文的代价 **成本角度：** - 每次请求都携带 CLAUDE.md 的全部内容 - 10K 字的文档 × 2000 次请求 = 2000 万字的 token 消耗 - 直接增加 API 费用 **注意力角度：** - 上下文越长，模型注意力越分散 - 关键信息被淹没在文档中 - 模型"忘记"了真正重要的东西 ### 什么时候需要 agent.md？ **原则：仅在模型反复犯错时才放入** | 场景 | 建议 | |------|------| | 模型总是用错某个 API | ✅ 加入简短的纠偏说明 | | 项目有特殊的命名约定 | ✅ 添加一行规则 | | 模型能自己探索出结构 | ❌ 不需要文档 | | 信息可能随时间变化 | ❌ 不要写死 | **好的 agent.md：** ```markdown # 项目规则 ## 必须遵守 - 所有 API 调用必须经过 src/lib/api.ts 的封装 - 不要直接使用 fetch ## 常见错误 - ❌ 不要在组件中直接调用数据库 - ✅ 使用 server actions ``` **坏的 agent.md：** ```markdown # 项目文档 ## 技术栈（可能过时） - React 18.2.0 - Next.js 14.1.0 - TypeScript 5.3.0 ## 目录结构（可能已重构） - src/components/ - 组件 - src/utils/ - 工具函数 - src/hooks/ - 自定义 hooks ## 开发流程（可能已变更） 1. 创建分支 2. 编写代码 3. 运行测试 4. 提交 PR ... ``` --- ## 五、实测：删除文件后的世界 ### 测试项目：Lawn Theo 在自己的真实项目 Lawn 中做了对比测试： **测试 A：启用 CLAUDE.md** - AI 反复引用文档中的过时路径 - 尝试访问不存在的文件 - 查询时间：较长（需要处理大量上下文） **测试 B：禁用 CLAUDE.md** - AI 自主探索代码库结构 - 快速找到正确的文件和依赖 - 查询时间：更快（上下文更精简） ### 观察：AI 的自研能力 **令人惊讶的发现：** AI 本身非常擅长： - 🔍 分析代码库结构 - 🔗 寻找依赖关系 - 📁 理解文件组织 - 🧩 推断架构模式 **AI 通过以下方式探索：** 1. 读取 `package.json` 了解依赖 2. 查看 `tsconfig.json` 理解路径映射 3. 浏览目录结构推断组织方式 4. 阅读关键文件（如 `app/layout.tsx`）理解框架 **结论：** 给 AI 一个干净的起点，它比你想的更聪明。 --- ## 六、进阶技巧：引导而非控制 ### 技巧 1：删除垃圾指令 **定期审计你的 agent.md，删除：** - 过时的技术栈描述 - 已变更的目录结构 - 不再适用的规则 - 冗余的示例代码 **原则：如果 AI 从来没犯过这个错，就不需要这条规则。** ### 技巧 2："欺骗" AI 简化任务 有时候，与其写复杂的指令，不如重构代码让 AI 更容易理解： ```typescript // 重构前：AI 容易困惑 export const handler = async (req, res) => { const data = await db.query(...) const transformed = data.map(...) const validated = schema.parse(transformed) return res.json(validated) } // 重构后：AI 一眼看懂 export const getUsersHandler = async (req, res) => { const users = await fetchUsersFromDatabase() const formattedUsers = formatUsersForApi(users) return res.json(formattedUsers) } ``` **核心洞察：让代码自解释，比写文档解释代码更有效。** ### 技巧 3：根据 AI 反馈重构 **不要：** 1. AI 犯错 → 添加规则到 agent.md 2. AI 再犯 → 添加更多规则 3. 文档越来越长 → AI 越来越困惑 **要：** 1. AI 犯错 → 分析为什么错 2. 重构代码/架构 → 让错误不可能发生 3. 删除对应的 agent.md 规则 **示例：** ```typescript // AI 总是忘记检查 null function getUserName(user) { return user.name // AI 经常漏掉 ?. } // 方案 A：添加规则（坏） // "总是检查 user 是否为 null" // 方案 B：重构代码（好） function getUserName(user: User | null) { return user?.name ?? 'Anonymous' } // TypeScript 强制处理，AI 不会犯错 ``` --- ## 七、新的最佳实践 ### 最小化原则 ``` AGENT.md 应该像急救包，而不是百科全书： - 只在必要时使用 - 内容精简到最少 - 定期清理过期内容 - 优先重构代码而非添加规则 ``` ### 动态化替代 **用动态上下文替代静态文档：** | 静态文档 | 动态替代 | |---------|---------| | 技术栈列表 | 让 AI 读取 package.json | | 目录结构 | 让 AI 运行 `tree` 或 `ls` | | API 文档 | 让 AI 阅读源码中的类型定义 | | 开发流程 | 让 AI 查看 scripts 和 CI 配置 | ### 验证清单 **在添加内容到 agent.md 前，问自己：** - [ ] 这个信息会变化吗？ - [ ] AI 能自己发现这个信息吗？ - [ ] 这条规则解决的是常见问题吗？ - [ ] 有没有办法通过重构代码来避免这个问题？ - [ ] 这条规则会不会限制 AI 的灵活性？ --- ## 八、结语：信任 AI，简化流程 Theo 的视频标题是《Delete your CLAUDE.md》，但真正的信息不是"不要写文档"，而是： **"不要过度工程化你的 AI 工作流。"** AI 比我们想象的更擅长探索和理解代码。我们的工作是： - 提供清晰的代码结构 - 编写自解释的代码 - 在必要时提供纠偏 - 定期清理过时的约束 **记住：** - 好的代码不需要解释 - 好的架构不需要文档 - 好的 AI 工作流不需要复杂的指令文件 下次你想往 CLAUDE.md 添加内容时，先问自己：**"我能不能通过重构代码，让这条规则变得不必要？"** --- ## 参考 - 原视频：[Delete your CLAUDE.md (and your AGENT.md too)](https://www.youtube.com/watch?v=GcNu6wrLTJc) - 作者：Theo - t3.gg - 相关研究：AI Agent 指令文件效能研究（2026） --- *你使用过 CLAUDE.md 或类似的指令文件吗？体验如何？欢迎在评论区分享。*