用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长期记忆启动对话时自动加载沉淀项目规范、技术栈、命令、坑位用户级CLAUDE.md跨项目的个人偏好记忆记录你惯用的代码风格、禁用项-mention引用文件/目录临时精准投喂修改某个模块前把相关文件带进对话代码库检索让Claude自己去搜答案说不清文件位置时用自然语言命令它找这张表后面每一节都会展开。记住一个原则CLAUDE.md管长期引用管本次检索管未知三者配合基本能覆盖90%的开发场景。剩下10%的高级场景可以靠MCP这类外部数据源补齐这个后面也会提到。2. 第一优先级CLAUDE.md——让Claude记住项目规矩2.1 CLAUDE.md到底是什么CLAUDE.md是放在项目根目录下的一个Markdown文件Claude Code启动时会自动读取它并把里面的内容当作整个对话的项目宪法。这是上下文体系里优先级最高的一层相当于给Claude写了一份交接文档。它解决的痛点很明确你不想每次对话都把这个项目是Vue3TS、构建命令是pnpm build、别碰老代码里的日期函数这些话重复一遍。只要写进CLAUDE.mdClaude就被要求默认遵守这些规则你再省下一大段开场白。我在实战里对它的定位是活文档——不是写完就不动了而是随着项目演化持续更新。比如某个接口突然换协议了组件库升级了构建命令改了都得同步反映到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结构你直接照着搭骨架就行。项目简介与目标用两到三句话写清业务帮Claude建立底层认知。比如这是一个面向跨境电商卖家的库存管理后台核心是SKU维度的库存同步和异常预警。技术栈与版本约定框架、UI库、语言版本、构建工具全部写明。这能避免Claude用Vue2语法写Vue3代码的尴尬。目录结构说明标注关键目录是干什么的。重点写业务组件在src/components/业务类型/下、接口定义一律走src/api模块这类规则。开发命令启动、构建、测试、lint、类型检查的具体命令。我把它们按开发时最常用和CI检查用分开写让Claude在合适场景调用合适的命令。代码规范命名规则、组件写法、状态管理方式。比如组件统一用setup语法糖、禁止在mutation里调用异步接口越具体越好。坑位记录团队踩过的坑集中写在这里。比如订单金额字段后端返回的是分前端必须转元后再展示——这种写进去之后Claude大概率不会再犯同样的错误。这六块不一定一次写全但建议至少前四块是必备的。后面两块随着项目积累持续补充。我自己踩过不少写CLAUDE.md时只图快结果Claude天天踩同一个坑的弯路后来把坑位记录补上这些低级错误基本绝迹了。2.4 全局CLAUDE.md和项目CLAUDE.md怎么分工除了项目根目录的CLAUDE.mdClaude 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和引用重新补齐。在终端里还能用ShiftTab循环切换上下文策略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重建、ShiftTab切换策略。补充一条实际操作心得如果你发现某个关键背景反复丢失别指望靠对话拉扯解决把这段背景写进CLAUDE.md才是釜底抽薪。长期记忆归长期记忆临时对话归临时对话混着用必踩坑。比如不要修改公共工具函数这种规则每次对话都靠口头强调根本不现实写进CLAUDE.md一次见效。5.3 回答不符合项目技术栈回去检查CLAUDE.mdClaude给出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把外部数据变成上下文如果项目已经离不开上下文工程化MCPModel Context Protocol值得纳入视野。通过MCPClaude Code可以挂载外部工具和数据源比如查数据库Schema、拉取需求详情、读内部设计文档API把这些信息实时变成上下文的一部分。这一层比CLAUDE.md更动态适合中大型团队把AI底座接入已有工具链。但它的学习曲线也陡配置复杂我建议先把CLAUDE.md和引用玩明白再考虑MCP否则容易陷入配置地狱。从实用角度看先把基础上下文管理做扎实收益已经非常可观MCP属于锦上添花。从我个人经验来说上下文管理不是一个一劳永逸的动作它是伴随项目生命周期持续迭代的过程。每完成一个重要需求如果我发现Claude理解项目时费了很大劲第一反应不是下次多写两句话而是回去把CLAUDE.md补一节——让下次对话的起点更高。最后分享一个小技巧每次更新完CLAUDE.md我习惯开个新会话随手问三个问题——这个项目怎么启动接口定义在哪有哪些不能踩的坑如果Claude能秒答就说明上下文底座是健康的。如果它还要反问你那就继续修。上下文理顺了Claude Code才真正从玩具变成生产力。