Claude Code上下文工程化：从CLAUDE.md到@引用，根治AI答非所问

用Claude Code最常遇到的尴尬，不是它不会写代码，而是你让它改登录接口，它反问你"登录接口在哪个文件里"。这不是模型笨，是它真的对你的项目一无所知。ClaudeCode实战系列走到第4篇，我越来越确认一件事：大部分问题不是靠更复杂的提示词解决，而是靠"添加上下文"这四个字——我自己的体感是，早期实战里至少六成翻车，把上下文补齐就能救回来。安装步骤官方文档写得很清楚，装好CLI、配上模型就能跑，难的是"项目认知"这一关。这期就把"添加上下文"从入门到工程化完整拆一遍：CLAUDE.md怎么建、@引用怎么用、如何让Claude自己搜代码找答案，以及踩坑之后怎么排查。如果你是刚装好Claude Code、正被它的答非所问逼到怀疑人生的开发者，这篇尤其对味。

1. 为什么上下文是Claude Code的第一生产力

1.1 不传上下文时，Claude到底有多"笨"？

先说个真实场景。有次我让它"帮我把交易列表加个筛选状态"，它直接按自己想象的字段返回了一段代码：组件里凭空冒出一个statusOption数组，接口字段对不上，代码风格也完全是另一套。

问题出在哪？我没告诉它两个关键背景：列表数据来自后端聚合接口，筛选要在前端做二次过滤；组件用的是团队封装的ProTable，传参方式和普通el-table完全不是一回事。这些信息一个字都没给，Claude当然只能按通用前端经验猜。

打个比方：你给五星级大厨一把菜刀，却不告诉他冰箱里有什么菜、今天几个人吃、有没有忌口，他再厉害也只能做一盘通用炒饭。Claude Code就是那把菜刀，上下文就是冰箱里的存货清单。工具本身的能力天花板很高，但输入信息的质量直接决定了输出能不能落地。很多人在这一步就放弃了，觉得"AI写代码不靠谱"，其实是投喂方式出了问题，不是工具出了问题。

1.2 上下文不是越多越好，而是越精准越好

很多人的第一反应是"那就把所有文件都喂给它"。错。

我见过最典型的翻车操作：把整个src目录拖进对话，让Claude"自己看着办"。结果它被几千行无关代码淹没，重点模块反而不突出，回答变得正确但无用。模型每次请求能承载的内容是有限的，垃圾信息会挤占注意力和token，真正需要参考的核心代码被稀释。

正确姿势是像给医生描述症状：说清部位、时长、诱因就够了，没必要把昨天吃了什么都背一遍。给Claude投喂上下文时，优先回答三个问题——改哪个文件、依赖什么数据、按什么规范写。这三个答案有了，绝大部分任务都能精准落地。反过来，如果这三个问题你自己都没想清楚，也别指望AI替你脑补完整。

1.3 一张表理清Claude Code的四个上下文来源

这张表后面每一节都会展开。记住一个原则：CLAUDE.md管"长期"，@引用管"本次"，检索管"未知"，三者配合，基本能覆盖90%的开发场景。剩下10%的高级场景，可以靠MCP这类外部数据源补齐，这个后面也会提到。

2. 第一优先级：CLAUDE.md——让Claude记住项目规矩

2.1 CLAUDE.md到底是什么

CLAUDE.md是放在项目根目录下的一个Markdown文件，Claude Code启动时会自动读取它，并把里面的内容当作整个对话的"项目宪法"。这是上下文体系里优先级最高的一层，相当于给Claude写了一份交接文档。

它解决的痛点很明确：你不想每次对话都把"这个项目是Vue3+TS、构建命令是pnpm build、别碰老代码里的日期函数"这些话重复一遍。只要写进CLAUDE.md，Claude就被要求默认遵守这些规则，你再省下一大段开场白。

我在实战里对它的定位是"活文档"——不是写完就不动了，而是随着项目演化持续更新。比如某个接口突然换协议了，组件库升级了，构建命令改了，都得同步反映到CLAUDE.md里。维护得越好，后面每个对话的起点就越高。反过来说，如果你写完就扔，过两个月再打开项目，Claude看到的还是过期信息，效果甚至会误导它。

2.2 用/init生成第一版底稿

手动从零写CLAUDE.md有点劝退，好在Claude Code内部集成了/init命令。在项目根目录运行claude进入交互模式，输入/init，它会扫描目录结构、读取package.json、tsconfig、README等配置文件，自动生成一版CLAUDE.md草案。

实测下来，/init生成的底稿覆盖了基础信息：项目简介、技术栈、几条关键命令。但离"好用"还差得远，它不可能知道你团队的命名习惯，不知道哪些历史包袱不能碰，也不会把你的代码风格偏好写进去。

所以我的标准流程是：/init生成底稿之后，立刻手动补三块——业务背景（这项目到底干嘛的）、技术约束（版本、框架、必须遵守的规矩）、坑位清单（踩过的雷和绕行方案）。这三块才是CLAUDE.md的真正价值所在。别嫌麻烦，这份文件写得好，后面省下来的时间远远超过投入。

2.3 手写CLAUDE.md的六个必备板块

分享一个我目前一直在用的CLAUDE.md结构，你直接照着搭骨架就行。

1. 项目简介与目标：用两到三句话写清业务，帮Claude建立底层认知。比如"这是一个面向跨境电商卖家的库存管理后台，核心是SKU维度的库存同步和异常预警"。
2. 技术栈与版本约定：框架、UI库、语言版本、构建工具全部写明。这能避免Claude用Vue2语法写Vue3代码的尴尬。
3. 目录结构说明：标注关键目录是干什么的。重点写"业务组件在src/components/业务类型/下"、"接口定义一律走src/api模块"这类规则。
4. 开发命令：启动、构建、测试、lint、类型检查的具体命令。我把它们按"开发时最常用"和"CI检查用"分开写，让Claude在合适场景调用合适的命令。
5. 代码规范：命名规则、组件写法、状态管理方式。比如"组件统一用setup语法糖"、"禁止在mutation里调用异步接口"，越具体越好。
6. 坑位记录：团队踩过的坑集中写在这里。比如"订单金额字段后端返回的是分，前端必须转元后再展示"——这种写进去之后，Claude大概率不会再犯同样的错误。

这六块不一定一次写全，但建议至少前四块是必备的。后面两块随着项目积累持续补充。我自己踩过不少"写CLAUDE.md时只图快，结果Claude天天踩同一个坑"的弯路，后来把坑位记录补上，这些低级错误基本绝迹了。

2.4 全局CLAUDE.md和项目CLAUDE.md怎么分工

除了项目根目录的CLAUDE.md，Claude Code还支持放在用户目录下的全局CLAUDE.md（~/.claude/CLAUDE.md）。它的特点是跨项目生效，适合写你个人的固定偏好。

我和团队的实际分工是这样的：全局文件里写"我个人习惯用组合式API、所有日期格式化统一走dayjs封装的formatDate函数、代码里不用分号"这类个人味道重的内容；项目文件里写团队约定和业务规则。两者加载时不冲突，Claude会按全局加项目叠加读取。

这条经验很关键：全局文件别写太多团队相关的东西，否则换个项目就会污染上下文。我见过有人把某个项目的技术栈写进全局CLAUDE.md，导致Claude在所有项目里都以为用的是那套框架，排查了半天才缓过来。全局文件只放"你自己走到哪儿都会坚持的写法"，项目文件放"这个团队必须统一的规则"，边界要清晰。

3. 对话中随手补充上下文的高级姿势

3.1 @-mention：精准引用文件和目录

CLAUDE.md解决的是长期记忆，但很多任务是临时的——我今天就要改这个组件，Claude只需要看这个组件和它相邻的依赖。

这时候最粗暴有效的方式是@引用。对话里输入@，Claude会弹出当前项目里的文件列表，支持路径补全。选中文件后，它会把文件内容当作本轮对话的上下文加载。改LoginForm就@src/components/LoginForm.vue，改接口就@src/api/auth.ts。

@引用目录也可以，但谨慎使用。小目录还好，目录一大文件一多，上下文窗口直接爆掉，反而拖累回答质量。我的经验是：默认@文件，只有在某个功能恰好集中在一个小目录里时才@目录。另外别忘了，@的文件路径尽量和项目实际目录结构一致，你手动编造的伪路径只会让Claude更迷糊。

3.2 报错日志、需求描述直接投喂

有些上下文不在代码文件里，而是散落在运行日志、报错信息里。这时候直接把内容粘进对话往往比让Claude去搜文件更高效。

我之前排一个构建报错，把pnpm build的完整stdout粘了进去，再补一句"这是构建接近尾声时的报错"，Claude立刻就定位到是SVG图标别名配置的问题。这个场景下，报错文本本身就是最关键的上下文，你不需要额外解释太多，模型能同时读取日志和你的补充说明。

需求描述也同理。写功能之前，把产品需求文档里的核心段落直接贴进去，别指望Claude脑补业务。它对业务的理解真的完全来自你喂的信息。有一次我贴了一段用户反馈截图转成的文字，Claude很快抓到了"用户觉得按钮位置不明显"这个真实诉求，比我手写十行描述有效得多。

3.3 让Claude自己翻书：代码库检索能力

不是每个改动你都说得清文件位置。这时候别硬撑，直接用自然语言告诉Claude"帮我查一下订单状态枚举定义在哪个文件"。

Claude Code内置代码库检索能力，能通过语义搜索定位到关键词所在位置。它不会只凭猜，而是先检索、再返回带路径的结论。你收到路径后再用@把对应文件引入对话，继续推进任务。

这里有个小提醒：检索结果不一定百分百准确，尤其当代码里存在大量相似命名时。所以别急着执行它给出的改法，先让它把文件路径摆出来，你扫一眼确认，再放它动手。"先证明确实找到了正确文件，再让它改代码"是我给自己定的铁律。省这一步，后面返工的代价往往比多花十秒钟确认更大。

3.4 把验收标准一并写进任务描述

上下文不只是输入给Claude的背景资料，还包括你对"做完"的定义。同样一句"优化一下列表加载"，加上验收标准后效果完全不同。

举个例子："这个列表要改成虚拟滚动，验收标准是：5000条数据时渲染时间不超过1秒；滚动过程不掉帧；保持现有API不变。"这段话喂进去，Claude就知道任务边界在哪，不会自作主张改接口、换依赖库。

我把这种写法叫作"把Definition of Done写成上下文"。它能帮你挡住AI最常见的两个毛病：交付半成品、顺手改你不想动的东西。你提前框定边界，它就不会用自由度来制造惊喜。

3.5 长对话的上下文膨胀与压缩

对话拉长了，Claude会逐渐"忘记"最早输入的信息，这是上下文窗口限制决定的，和模型能力没关系。

我实际操作中的处理方法：当Claude开始答非所问、反复引用同一个错误前提时，不再硬聊，直接用/compact压缩历史对话，把上下文整理成精简版本继续。如果对话实在太长、太乱，干脆/clear重新开一轮，最核心的信息用CLAUDE.md和@引用重新补齐。

在终端里还能用Shift+Tab循环切换上下文策略（auto、high、compact三种模式）。auto适合大多数场景，high适合重要长对话，compact适合预算敏感的批量任务。这个切换我每天都会用，它是上下文管理的主战场，别忽略。很多用户抱怨"Claude聊着聊着就变蠢了"，其实不是模型变蠢，是上下文窗口被垃圾塞满了，该做的压缩没做。

4. 工程化落地：把上下文管理变成团队习惯

4.1 控制Claude的视野边界

Claude Code默认不会去读.gitignore里列出的目录和文件，这既是隐私保护，也是天然的上下文防火墙。node_modules、dist、.next、lock文件这些没人希望被读的东西，不主动加进对话就没事。

如果你想更精细地控制边界，可以在项目里配置自定义忽略规则，把生成目录、密钥文件、内部文档等都排除出去。这样Claude读项目时只会看到真正的源码和必要的配置文件，不会在一堆构建产物里迷路。

这个操作很容易被忽视，但它直接关系到token费用和回答质量。想象一下Claude在检索"订单"这个词时，同时扫到编译产物里无数条重复匹配，效率可想而知。我在项目里一旦发现Claude总是引用到dist目录下的旧代码，第一反应不是骂它，而是回去检查忽略规则是不是漏了。

4.2 一份可以直接套用的CLAUDE.md模板

给个非常实用的东西：我现在创建新项目时会从这份模板开始改。

# 项目名 ## 项目简介 - 一句话说清这个项目是什么、服务谁。 ## 技术栈 - 框架：Vue3 + TypeScript - 状态管理：Pinia - UI组件库：Element Plus - 构建：Vite - 测试：Vitest ## 常用命令 - 启动：pnpm dev - 构建：pnpm build - 跑单测：pnpm test - 代码检查：pnpm lint ## 目录结构 - src/pages：页面级组件 - src/components：通用业务组件 - src/api：接口定义 - src/utils：工具函数 ## 代码规范 - 组件统一使用 setup 语法糖 - props 需要写类型与默认值 - 禁止在 mutation 中调用异步接口 ## 踩坑记录 - 订单金额接口返回的是分，展示前必须转元 - node 必须 >=18，否则构建报错

这段模板不用迷信，重点是它把"项目是什么、怎么跑、怎么写、别踩什么坑"一次性给齐了。Claude每次对话开局先读这十几行，后面所有代码生成都会更贴你的项目。等到你真的用熟了，再按自己团队的风格去调整板块顺序和颗粒度。

4.3 把CLAUDE.md纳入版本控制

既然CLAUDE.md能沉淀团队知识，就应该把它提交进git仓库，跟代码一起管理。这样每个成员clone项目后，天然就带上了这套上下文底座，不需要各自口口相传。

我现在的习惯是：项目初始化时就建好CLAUDE.md，评审代码时顺带review它，每次迭代更新也同步更新。对新人来说，这份文件相当于浓缩版的团队wiki，甚至比读完整文档更快上手。而那些不适合进仓库的私人偏好，放进全局CLAUDE.md即可。

有一次我接手一个新项目，第一件事就是跑claude后直接问"这个项目怎么启动"。因为CLAUDE.md已经写好了，一分钟内我就搞清楚了技术栈、命令和结构，那种体验和以前对着wiki找半天完全是两个世界。如果你的团队还在靠口头传承技术背景，是时候把这份文档建起来了。

5. 常见问题与排查技巧实录

5.1 CLAUDE.md没生效？先查这四件事

项目CLAUDE.md没生效，按这个顺序排查：

• 文件位置是否正确。项目级必须放在项目根目录，子目录下的CLAUDE.md只在路径相关场景生效。
• 文件名是否准确。是CLAUDE.md，不是claude.md也不是CLAUDE.txt。
• 是否命中忽略规则。如果.gitignore或自定义忽略规则把CLAUDE.md排除了，Claude不会读它。
• 文件编码和格式。保持UTF-8纯文本，别存成带BOM或非UTF-8编码，否则中文内容可能变成乱码。

这四件事排查完，九成问题都能解决。剩下的一成，往往是你以为"放好了"但终端里的工作目录和项目根目录不是同一个。用pwd确认一下当前路径，再不行就用CLAUDE.md的绝对路径手动喂一遍，总能救回来。

5.2 Claude"失忆"了？先压缩再补上下文

对话变长后Claude忘记早期指令，这是最常见的体验。处理方法上文提过：/compact压缩、/clear重建、Shift+Tab切换策略。

补充一条实际操作心得：如果你发现某个关键背景反复丢失，别指望靠对话拉扯解决，把这段背景写进CLAUDE.md才是釜底抽薪。长期记忆归长期记忆，临时对话归临时对话，混着用必踩坑。比如"不要修改公共工具函数"这种规则，每次对话都靠口头强调根本不现实，写进CLAUDE.md一次见效。

5.3 回答不符合项目技术栈？回去检查CLAUDE.md

Claude给出Vue2风格代码而你项目是Vue3，大概率是CLAUDE.md没写清楚技术栈版本。别先骂AI，先问自己"这笔上下文到底喂没喂到位"。

有一个自测方法很有效：新打开一轮对话，直接问Claude"这个项目的技术栈是什么？构建命令是什么？代码规范有哪些？"如果它答得和你预期不一致，那就是上下文没管理好，去修补CLAUDE.md，而不是在对话里反复纠正。喂一次上下文就希望能纠正十次，那是偷懒，不是高效。

5.4 IDE集成和第三方模型接入时的上下文差异

现在很多人不只纯终端用Claude Code，还会在VSCode、Cursor甚至PyCharm里配合使用。以VSCode为例，集成方式有多种，有的是官方扩展，有的是第三方封装，操作入口不同，但上下文机制是同一套。在PyCharm里没有官方插件，直接用内嵌终端跑claude命令就是最可靠的方案，不影响CLAUDE.md和@引用功能。

另外，圈子里的朋友经常讨论把Claude Code接到第三方模型API上（比如DeepSeek、智谱这类兼容服务的配置方案）。这种玩法下，不同模型的上下文窗口大小差异很大，更要把CLAUDE.md维护好，因为它在每次请求里消耗的token不多，收益却是整个对话的质量上限。

5.5 Codex还是Claude Code？从上下文视角看

很多人纠结OpenAI Codex和Claude Code选哪个。简单说说我的感受：Codex更擅长高度自主的agent循环，适合"给定一个目标，它自己来回运行代码直到完成"的场景；Claude Code则更强调你作为开发者主动管理上下文和任务边界。

如果你喜欢"把项目规则写清楚，然后让AI在规则内自由发挥"，Claude Code的CLAUDE.md机制用起来很顺手；如果你更想要"开个空会话，让它自己折腾半天"，就试试Codex。这里没有绝对标准，工具选型最终取决于你的使用习惯。但不管选哪个，上下文管理的思想都一样适用，CLAUDE.md这套思路放在任何AI编程工具上都成立。

5.6 MCP：把外部数据变成上下文

如果项目已经离不开上下文工程化，MCP（Model Context Protocol）值得纳入视野。通过MCP，Claude Code可以挂载外部工具和数据源，比如查数据库Schema、拉取需求详情、读内部设计文档API，把这些信息实时变成上下文的一部分。

这一层比CLAUDE.md更动态，适合中大型团队把AI底座接入已有工具链。但它的学习曲线也陡，配置复杂，我建议先把CLAUDE.md和@引用玩明白，再考虑MCP，否则容易陷入配置地狱。从实用角度看，先把基础上下文管理做扎实，收益已经非常可观，MCP属于锦上添花。

从我个人经验来说，上下文管理不是一个一劳永逸的动作，它是伴随项目生命周期持续迭代的过程。每完成一个重要需求，如果我发现Claude理解项目时费了很大劲，第一反应不是下次多写两句话，而是回去把CLAUDE.md补一节——让下次对话的起点更高。

最后分享一个小技巧：每次更新完CLAUDE.md，我习惯开个新会话随手问三个问题——"这个项目怎么启动？""接口定义在哪？""有哪些不能踩的坑？"如果Claude能秒答，就说明上下文底座是健康的。如果它还要反问你，那就继续修。上下文理顺了，Claude Code才真正从"玩具"变成"生产力"。