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

一、引言：那个被过度神化的文件

如果你用过 Claude Code、Cursor 或其他 AI 编程助手，你一定见过或创建过这样的文件：

• CLAUDE.md
• AGENT.md
• .cursorrules
• AGENTS.md

这些文件被奉为"让 AI 理解项目的圣经"。无数教程告诉你："一定要写好 CLAUDE.md，这样 AI 才能正确理解你的代码库。"

但最近一项研究和 Theo 的实测，却指向了一个反直觉的结论：

这些文件可能正在损害你的 AI 编程体验。

---

二、研究发现了什么？

论文核心结论

一项针对 AI Agent 指令文件的最新研究发现：

关键发现：

• 过度复杂的 agent.md 会导致模型产生偏见
• 模型会尝试文件中提到的过时技术栈
• 文件中的虚假路径会误导模型搜索

文件审计的警示

Theo 审计了自己的项目库，发现典型的 agent.md 存在这些问题：

# 典型的问题 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？

原则：仅在模型反复犯错时才放入

好的 agent.md：

# 项目规则

## 必须遵守
- 所有 API 调用必须经过 src/lib/api.ts 的封装
- 不要直接使用 fetch

## 常见错误
- ❌ 不要在组件中直接调用数据库
- ✅ 使用 server actions

坏的 agent.md：

# 项目文档

## 技术栈（可能过时）
- 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 更容易理解：

// 重构前：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 规则

示例：

// 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 应该像急救包，而不是百科全书：
- 只在必要时使用
- 内容精简到最少
- 定期清理过期内容
- 优先重构代码而非添加规则

动态化替代

用动态上下文替代静态文档：

验证清单

在添加内容到 agent.md 前，问自己：

• 这个信息会变化吗？
• AI 能自己发现这个信息吗？
• 这条规则解决的是常见问题吗？
• 有没有办法通过重构代码来避免这个问题？
• 这条规则会不会限制 AI 的灵活性？

---

八、结语：信任 AI，简化流程

Theo 的视频标题是《Delete your CLAUDE.md》，但真正的信息不是"不要写文档"，而是：

"不要过度工程化你的 AI 工作流。"

AI 比我们想象的更擅长探索和理解代码。我们的工作是：

• 提供清晰的代码结构
• 编写自解释的代码
• 在必要时提供纠偏
• 定期清理过时的约束

记住：

• 好的代码不需要解释
• 好的架构不需要文档
• 好的 AI 工作流不需要复杂的指令文件

下次你想往 CLAUDE.md 添加内容时，先问自己："我能不能通过重构代码，让这条规则变得不必要？"

---

参考

• 原视频：Delete your CLAUDE.md (and your AGENT.md too)
• 作者：Theo - t3.gg
• 相关研究：AI Agent 指令文件效能研究（2026）

---

你使用过 CLAUDE.md 或类似的指令文件吗？体验如何？欢迎在评论区分享。