AI AI 工具指南
常见问题解决库

Claude Code 不理解你的项目怎么办：让 agent 真正读懂代码的 7 个方法

Claude Code 改了一半文件、问的问题对不上、找不到关键函数？多半不是模型不行，而是它没拿到正确的项目上下文。本文给出 7 个方法让 agent 一次就读懂你的项目。

发布于: 作者: AI Productivity Guide Team 🌐 查看英文版本

Claude Code 表现拉跨的最常见原因，不是”模型不够聪明”，而是它根本没拿到你项目的关键上下文。这种情况下让它做任何事都会”看似在干活，实际全是猜”。本文给出 7 个让 agent 真正读懂项目的方法，按收益从高到低排列。

问题是什么

典型表现：

  • 改了文件但根本没看主要逻辑文件
  • 创建了已经存在的函数 / 组件（重复造轮子）
  • 问你”哪里定义了 X”，其实你已经在 README 写过了
  • 自动改了一堆”风格相关”的细节，破坏了原本的规范
  • 调试问题时一直在表面打补丁，不去看真正的源头

真正的原因

Claude Code 不会自动读完你整个仓库。它每次只看：

  1. 你 prompt 中明确提到的文件
  2. CLAUDE.md 里写明的项目说明
  3. 它在执行任务中主动用工具找的文件

如果这三处都缺，它就只能靠”猜常见结构”。Next.js 项目就猜 app/page.tsx，Astro 就猜 src/pages，结果你的项目其实是个 monorepo / 自定义结构，它就全部对不上。

7 个让 Claude Code 真正读懂项目的方法

按收益从高到低：

1. 写一份高质量 CLAUDE.md（最重要）

在项目根目录创建 CLAUDE.md。这是 Claude Code 每次对话自动读的”项目说明书”。

要包含：

  • 技术栈：框架、语言、版本、包管理器
  • 目录结构：每个一级目录是什么
  • 关键约定：文件命名、状态管理、路由模式、CSS 方案
  • 运行 / 构建 / 测试命令：npm run dev、npm test
  • 本地踩过的坑：哪些目录不该改、哪些文件不要碰
  • 如何添加新功能 / 新页面 / 新组件的实际流程

写法风格：用第二人称对 Claude 说话，像写给一个新同事的入职文档。

反例：一份 CLAUDE.md 写满了”项目愿景 / 设计理念”——Claude 不需要这个。它要的是”add a new page 要做的 4 步”。

2. 在 Prompt 里直接指路

不要写 “帮我修 login 的 bug”。写：

帮我修 src/auth/login.ts 的 bug，相关的逻辑还在 src/auth/session.ts 和 src/lib/cookies.ts。先读这三个文件，再告诉我修改方案。

直接指出 3-5 个文件，让 agent 跳过”找文件”阶段。

3. 让它先 ls / tree 一次

第一次进入项目时，让 agent 先做一次结构扫描：

先用 ls -la 看根目录，再 tree -L 3 -I 'node_modules|.next|dist' 看一下整体结构，告诉我这是什么类型的项目，然后再开始任务。

这相当于给它一次”开机扫描”。

4. 用 README + ARCHITECTURE 替模型省力

如果项目有 README 和 architecture 说明，把它们放在仓库根，并在 CLAUDE.md 末尾写一句：

Always read README.md and docs/ARCHITECTURE.md before suggesting code changes.

很多项目缺这两个文件，AI 就只能靠猜。

5. 限制 agent 不去碰的目录

用 .claudeignore 或在 CLAUDE.md 里明确写：

Do NOT edit anything inside:
- node_modules/
- .next/, dist/, build/
- generated/ (auto-generated)
- legacy/ (deprecated, do not touch)

这样它就不会去乱搜不该碰的目录，回答也更聚焦。

6. 给它”如何添加一个 X”的复制粘贴清单

例如在 CLAUDE.md 里写：

## How to add a new page

1. Create `src/content/articles/[lang]/[category]/[slug].mdx`
2. Use the schema in src/content/config.ts
3. Add the slug to internal links from the related category landing
4. Run `npm run audit:content` before commit

这种”清单式”指引能让 agent 直接照做，不会创新性地造一个新约定。

7. 给关键文件加”导览注释”

在你项目的关键文件顶部加 5-10 行注释：

// auth/session.ts
// Owns session lifecycle: create, refresh, destroy.
// Reads cookies via lib/cookies.ts. Writes audit logs via lib/log.ts.
// IMPORTANT: do not call this from middleware — use auth/edge-session.ts there.

这种”导览注释”是写给 AI 看的，但人类看也清楚，没有坏处。

最短修复路径

按落地难度从低到高：

  1. 加一份 CLAUDE.md（哪怕 30 行）
  2. 每次 prompt 直接列文件路径
  3. 限制 agent 不碰的目录
  4. 关键文件加导览注释
  5. 复杂项目再写 ARCHITECTURE.md

只做前两步，效果就能立竿见影。

什么时候不是模型的问题

  • 你的项目结构本身很乱，新人也读不懂 → 优先重构而不是修 Claude
  • 同一个 prompt 在小项目里完全没问题，在你的大 monorepo 才出错 → 是上下文量超了
  • agent 在反复重试同一个文件 → 它没拿到那个文件的真正路径

容易误判的情况

  • 以为 Claude “笨了”，其实是项目变大了 —— Claude Code 不能一次读 100 万行
  • 以为它无视你的 CLAUDE.md —— 检查文件名大小写、路径在仓库根
  • 以为它编造代码 —— 多半是它没看到原代码，被迫”补一个看起来对的”
  • 以为它不会用工具 —— 你的 prompt 没让它用 tree / grep 就只能靠猜

预防建议

  • 每个项目第一天就建 CLAUDE.md
  • 添加新模块时同步更新 CLAUDE.md
  • 大型 monorepo 在每个子包都放一份 CLAUDE.md
  • 把”重构 / 命名约定 / 不要做”的红线写明
  • 让 agent 在每次大任务前先输出”理解到的项目结构”再开始

常见问题（FAQ）

Q：CLAUDE.md 写多长合适？ A：50-200 行最实用。太短没信息，太长 agent 反而抓不到重点。优先级是：技术栈 → 目录 → 关键命令 → 不要做的事 → 怎么加新东西。

Q：CLAUDE.md 和 README 冲突怎么办？ A：CLAUDE.md 给 agent 用，README 给人用。但内容可以重叠，只是 CLAUDE.md 更强调”agent 应该怎么操作”。

Q：Cursor / Codex / Claude Code 的 ignore 文件互通吗？ A：不完全互通。.cursorignore、.claudeignore、.gitignore 是不同文件。每个工具都建议有自己的 ignore。

Q：让 Claude Code 一次读完整个项目可行吗？ A：除非项目很小。中大型项目应该让它”按需读”，不要塞太多无关文件进上下文。

Q：如何判断它现在拿到了正确上下文？ A：让它在开始前”用 1-2 句话总结你理解的项目结构”。结构不对就停下来纠正。

相关问题

决策前的检查清单

  • 如果错误是在某次改动后立刻出现，先回滚或隔离那次改动，不要同时试一堆无关修复。
  • 如果只在生产环境出现，对比环境变量、build 产物、缓存、权限和平台设置。
  • 如果只影响某个账号或浏览器，优先查权限、cookie、插件、额度和地区可用性。
  • 如果有两个修复方向，先选最容易验证、最容易撤销的那个。

什么时候可以先停下来

当你无法复现、日志和 UI 互相矛盾、涉及账单或账号安全、或者每个修复都需要你没有的生产权限时，就该停止盲试并升级处理。向平台支持或同事求助前，把完整错误、时间点、项目 ID、复现步骤、截图和最近改动整理好。清楚的升级说明，通常比再猜一小时更快解决问题。

诊断流程

  1. 先复现一次问题，并写下准确路径。复现不了时，先收集证据，不要急着改设置。
  2. 判断影响范围：一个用户还是所有用户，一个浏览器还是全部浏览器，只在本地还是只在线上，新内容还是旧内容也受影响。
  3. 优先查最近一次改动。大多数排查不是寻找神秘根因，而是找出哪次改动制造了不一致。
  4. 把系统切成两半测：输入 vs 输出、本地 vs 线上、账号 vs 项目、源文件 vs 生成文件、prompt vs 模型。确认哪一半还在失败。
  5. 先做最小且可撤销的修复。不要同时改 DNS、权限、账单、部署和代码。
  6. 用原复现路径和一个相邻路径验证，再记录最终是哪一步修好的。

最小复现模板

问题：
- [完整错误或异常表现]

发生位置：
- URL / 工具 / 项目：
- 账号：
- 环境：local / preview / production
- 浏览器 / 设备：

复现步骤：
1.
2.
3.

预期结果：
- 

实际结果：
- 

最近改动：
- 代码：
- 配置：
- DNS / 权限 / 账单：
- Prompt / 模型 / 上传文件：

证据：
- 截图：
- Console error：
- 服务端或平台日志：

这些”假修复”别做

  • 只清缓存，却不确认底层文件、权限、路由或设置是否正确。
  • 明明是环境变量、凭证、额度或平台配置问题，却反复重装依赖。
  • 一次改好几个无关设置，最后不知道到底是哪一步起作用。
  • 从另一个框架或平台复制修复方法，却不确认路由、build 输出或鉴权模型是否相同。
  • 没看 status page 和近期反馈，就把平台临时故障当成自己的 bug。
  • AI 提交前审查工作流
  • Claude Code SEO 审计教程
  • AI 依赖升级工作流

标签: #Claude #Claude Code #AI 编程 #排查

相关文章