引言让ClaudeCode真正“听懂”你的项目用了ClaudeCode一段时间的人基本都会遇到同一个坎刚装好、能跑通基础流程的时候特别兴奋感觉像是请了一个随叫随到的程序员但真正丢给它一个有点规模的项目它就开始“一本正经地胡说八道”——改错了文件、猜错了目录结构、甚至把A项目的代码逻辑搬运到B项目里。问题几乎都出在同一个地方上下文没给够。ClaudeCode不是一个“贴一段代码进去它给你改完吐出来的”工具它是一个常驻在终端里的结对编程搭档。你使用终端、编辑器、Git提交信息、构建日志它都在旁边看着但它们能当你的“记忆”并不代表它们能理解你的“意图”。在项目里跑起来的ClaudeCode本质上是一个手里拿着工具但没看过项目文档的新员工——它能写代码但不知道你项目的规矩、约定、背景和边界。所以第四篇实战我们专门聊“添加上下文”。这一篇是整套实战系列里我认为最值得细读的一篇因为它的适用范围不限于ClaudeCode本身你理解了怎么给AI项目注入上下文你就能理解怎么让任何AI编程工具真正变得好用。适合正在从“学会安装”走向“真正用起来”的开发者也适合刚被AI写代码坑过一次、想搞清楚问题出在哪的人。1. 上下文到底是什么先搞懂ClaudeCode在“看”什么1.1 一句话讲清楚上下文机制ClaudeCode在每一次运行任务时并不是把你的整个项目都读进内存里。它会基于当前所处的目录、你敲的指令、你引用的文件有选择地把代码片段、目录结构、关键说明喂给模型。这个“喂进去的信息集合”就是上下文。你可以把它想象成你在给一个远程助手安排工作。你说“把XX模块的接口改一下”对方如果不知道你项目里api层、service层、controller层的划分习惯不知道你用的是fetch还是axios不知道你的错误处理规范他只能靠猜。猜对了是运气猜错了是常态。ClaudeCode的设计者显然很明白这一点所以它提供了多层机制来让你主动注入上下文。不理解这些机制的区别你就会陷入“每次都手动贴一堆代码进去”的原始状态——虽然能用但效率很低而且每次对话一多就开始丢信息。1.2 ClaudeCode记忆的信息源根据我的实际使用ClaudeCode的上下文大体来自四个地方系统提示词工具自带的基础设定告诉你“我是谁、我能干什么”。这一部分你基本改不了也不需要改。CLAUDE.md 文件项目的“说明书”也是本篇文章的重头戏。你可以在这里写下项目结构、代码规范、命令用法、禁忌事项ClaudeCode在每次运行时都会主动读取它。对话历史你在这个会话里和它交流过的内容包括你给的指令、它读过的文件、它写过的代码。对话越长这部分占的上下文越多。工具返回结果执行命令的stdout、搜索文件的结果、MCP工具返回的数据。这些也会被拼进上下文里。明白这四部分之后你就知道“添加上下文”主要能做的操作就是把能离线准备的信息写进CLAUDE.md把动态获取的信息通过指令和工具交互拉给模型。接下来我们挨个展开。2. CLAUDE.md项目级“代码记忆”的正确写作姿势2.1 三个层级的CLAUDE.md你要分清ClaudeCode支持三种层级的CLAUDE.md文件它们的加载顺序和作用范围不一样别混着用用户级~/.claude/CLAUDE.md加载于所有项目之前适合放你个人的全局偏好比如“我习惯用pnpm而不是npm”“提交信息用中文写”“不要用any类型”。这相当于你作为开发者的“性格设定”会应用于你机器上的所有ClaudeCode会话。项目级项目根目录的CLAUDE.md这是你平时最需要维护的文件。ClaudeCode进入项目目录后会主动读取它作为该项目所有上下文的基础。它负责回答“这个项目是什么、怎么跑、有什么规矩”三个问题。会话级通过/memory指令写在会话内只对当前会话生效适合存放临时约定比如“本次任务只改src/modules/user这个目录”“数据库连接串在.env.local里”。会话结束即失效不影响其他项目。我第一次用的时候只知道项目根目录能放CLAUDE.md结果把很多个人偏好也写进去了换了台电脑就失效。后来我把“我习惯用pnpm”“提交信息写中文”这类内容挪到用户级项目级文件才真正瘦身成功。2.2 一份够用的CLAUDE.md应该写什么CLAUDE.md不用写得像技术文档那么正式但一定要围绕“让AI少犯错”来组织。我实践下来最有效的结构是下面这几块项目简介3~5句话这个项目是干什么的、服务哪些用户、核心业务是什么。目的是让AI在做大范围改动时不会偏离业务方向。技术栈与关键依赖前端框架、后端框架、ORM、构建工具、包管理器、Node版本等。注意不用全部罗列只写会影响程序写法的事项即可。目录结构与归属说明不需要把整个目录树贴进去那是浪费上下文。只需写清楚核心目录的职责和约定。比如“src/pages放页面级组件src/components放通用组件”“services层统一封装HTTP请求”。常用命令与运行方式安装依赖、启动开发服务、运行测试、构建产物、代码格式化的准确命令。这能避免AI执行了一堆安装和构建命令却全错。编码规范与风格约定命名规范组件/变量/接口、要不要类型声明、错误处理的方式、是否允许使用任何类型等。注意事项与“禁区”比如“不要修改public目录下的静态资源”“不要动数据库迁移文件”“线上环境的.env文件绝不读取”。我的一个建议是早期不用追求一次写全可以在每次ClaudeCode犯错的时候顺手补一条。比如它在修改模块时把另一个无关模块改坏了你就把“涉及src/modules下的改动必须先向我确认影响范围”写进CLAUDE.md。写几周之后这份文件就是一个非常贴合你项目实际的记忆库。2.3 一个真实可用的CLAUDE.md模板以下是我给一个典型的前端项目写的CLAUDE.md结构可以直接抄# 项目某某后台管理系统 ## 项目简介 面向内部运营人员的管理后台核心业务包括用户管理、订单管理、权限配置、数据看板。 UI基于Ant Design服务端接口走RESTful风格。 ## 技术栈 - React 18 TypeScript - Vite 构建pnpm 包管理 - 状态管理Zustand - 路由React Router v6 - 请求axios统一封装在 src/services ## 目录约定 - src/pages页面级组件一个路由对应一个目录 - src/components通用组件按组件名建目录 - src/services接口请求封装每个业务域一个文件 - src/store全局状态按业务域拆分store - src/utils纯函数工具库禁止放业务逻辑 ## 常用命令 - 安装依赖pnpm install - 启动开发服务pnpm dev - 运行测试pnpm test - 构建pnpm build ## 编码规范 - 组件使用函数组件 hooks禁止class组件 - 接口请求必须走 src/services禁止在组件内直接调fetch - 类型声明优先用interface不用type定义对象结构 - 所有props超过3个时必须定义一个Interface ## 特别注意 - src/pages下的任何改动需要同步检查路由配置 - 不要修改src/components下的通用组件除非任务明确说明 - 新增加载状态必须处理不能只写“请求成功”的逻辑这份文件看起来不长但信息密度很高ClaudeCode每次运行都读一遍配合对话上下文基本不会跑偏。建议所有团队都把类似的文件入库新人用AI干活的时候也能直接享受前人积累的“项目记忆”。3. 动态注入ADD、文件引用与MCP工具的实用组合拳3.1 /add与文件引用临时指定关注范围CLAUDE.md解决的是“稳定信息”但很多场景下需要临时告诉ClaudeCode“这次的重点是这些文件”。最常见的做法是两种。第一种是直接在对话里打src/xxx.tsxClaudeCode会把该文件的完整内容放进上下文。这个操作适合文件数量少、内容可控的情况。我在修改一个表单组件的时候会把组件文件、对应的service文件、接口类型定义文件一起引进来效率非常高。第二种是使用/add指令作用类似但它更像一个“会话级的关注清单”。你可以通过/add src/modules/user把整个目录添加进上下文ClaudeCode会扫描这个目录并理解里面的内容关系。这个指令很适合任务范围比较明确、但跨多个文件的情况。需要注意/add和引用会占用上下文窗口别把整个node_modules引进来那不是帮手是炸弹。3.2 上下文窗口占用什么时候该“开新会话”ClaudeCode默认的上下文长度比较可观具体数值取决于使用的模型和配置但这不意味着可以无限塞。每读一个文件、每执行一条命令都会消耗上下文空间。当上下文接近上限时它的表现会明显变差开始遗忘早期的约定、忽略CLAUDE.md里的规定、甚至把之前的对话内容重复输出。我的经验法则是一个任务如果在同一会话里聊了超过一小时或者ClaudeCode开始反复问你“之前提到的XXX是什么”就果断开新会话。新会话会把CLAUDE.md重新加载然后你可以通过/add或写一段“任务导入”来重建需要的信息。这比在一个快撑爆的会话里硬撑着继续高效得多。另外还有一个习惯我把它叫“会话开场白”每次新会话进入后第一句话不要直接丢需求而是先把背景写清楚。比如“本次任务是修复订单导出功能相关代码在src/services/order.ts和src/pages/order/export环境变量使用.env.test的配置”。这短短一句话就能避免AI开局就瞎猜。3.3 MCP工具上下文不只能“喂”还能“查”CLAUDE.md和文件引用都是“把已知信息塞给模型”的静态做法。但真实项目里有些信息是运行时才知道的比如数据库结构、构建产物、服务日志。这些信息更适合通过MCP工具以查询的方式动态拉取。ClaudeCode支持MCPModel Context Protocol工具接入你可以配置一个数据库MCP让它能执行只读SQL查询来了解表结构可以配置一个Git MCP让它自动分析提交历史和分支信息。这么做的本质是把“上下文”这个概念从“读静态文件”扩展成“按需查询”。举个例子有一次我要改一个接口的返回结构传统做法是把后端接口文档复制粘贴进来。配置了数据库MCP之后ClaudeCode直接执行了一条只读SQL查了表结构自己就判断出哪些字段需要改、哪些字段会影响前端展示。整个过程我只需要在旁边确认【是否允许执行该操作】省去了大量查文档、贴文档的时间。配置MCP的时候要注意权限控制尤其是数据库MCP好的实现会默认只开放SELECT语句写操作必须经用户手动确认。别为了图方便把写权限放开AI有时候过于“自作主张”安全底裤要自己穿好。4. 组织上下文的进阶心法像管理工程一样管理上下文4.1 优先级思维什么值得进CLAUDE.md什么只配进会话很多人的CLAUDE.md文件越写越长从项目简介写到埋点规范再写到代码风格最后变成了一个小型Wiki。但ClaudeCode每次都读全量CLAUDE.md文件越长真正关键的信息被稀释得越厉害。记住一个分类方法规则进CLAUDE.md事实进会话数据进MCP。“接口命名必须用动词开头”“提交前必须跑单测”属于规则值得写进CLAUDE.md因为它能长期约束行为。“本次要改的接口在src/api/user.ts它调用的后端服务是user-service”属于事实写进当前会话的开场白即可不需要长期占用CLAUDE.md。“数据库user表的status字段有哪些枚举值”属于数据应该通过MCP工具查询写进任何文档都是静态过时的。遵循这个原则你的CLAUDE.md能长期保持精简ClaudeCode每次启动都轻装上阵判断准确率反而更高。4.2 上下文可视化像检查日志一样检查AI的“视野”很多人不知道ClaudeCode有一个能直接查看当前上下文的界面。你在会话里按快捷键具体按键会根据使用的版本和客户端略有不同就能打开一个上下文面板里面会显示当前已加载的CLAUDE.md、已引用的文件、已执行的工具调用以及估算的上下文占用比例。我强烈建议你养成一个习惯接到一个复杂任务时先打开这个面板看一眼确认CLAUDE.md已被加载、你/add的文件列表确实覆盖了关键代码再开始让AI干活。这就像写代码前先看一眼IDE打开的标签页够不够一样是最廉价但最有效的防偏路手段。有一次我觉得ClaudeCode表现得特别“笨”改了三次都没改对打开面板一看它压根没读到我刚更新过的CLAUDE.md因为我在会话开始后修改过那个文件它只在会话启动时加载过旧版本。手动在对话里再引入一次CLAUDE.md内容之后问题立刻消失。从那以后我遇到任何“AI变蠢”的情况第一反应都是先查上下文面板。4.3 为团队沉淀把CLAUDE.md从个人笔记变成项目资产如果你在一个团队里用ClaudeCode强烈建议把项目级的CLAUDE.md提交到Git仓库。它是项目的“AI使用说明书”而不是某个工程师的个人偏好。新人入职时读一遍CLAUDE.md再让AI辅助干活上手的效率能快很多。团队维护CLAUDE.md有一个坑需要避开不同成员的编码风格可能完全不同每个人都会往CLAUDE.md里塞自己的偏好文件很快会膨胀成一锅大杂烩。我的做法是在CLAUDE.md开头加一节“本文件维护规则”明确说明“此文件只记录项目级约定个人偏好请写入~/.claude/CLAUDE.md”从源头避免文件劣化。5. 实战案例从一个前端需求走通“添加上下文”全流程5.1 场景设定我们假设有一个后台管理系统需求是“在用户列表页新增一个导出按钮支持导出当前筛选条件下的用户数据为Excel”。这个任务看起来简单但它涉及页面组件、接口服务、后端接口、权限控制等多个环节非常适合演示上下文注入的完整流程。5.2 实操流程记录第一步开场白。我新开一个会话先输入项目背景把本次任务的目标、涉及文件、约束条件一次交代清楚本次任务在用户列表页新增导出按钮支持导出当前筛选条件下的用户数据为Excel。 涉及文件src/pages/user/List.tsx页面主组件、src/services/user.ts接口封装、src/types/user.d.ts类型定义。 约束导出接口使用POST方法参数与当前列表查询参数一致权限标识为user:export需要调用前端权限判断工具。 项目使用Ant Design按钮风格请保持与其他页面一致。第二步引入关键文件。我使用src/pages/user/List.tsx、src/services/user.ts、src/types/user.d.ts把三个核心文件内容递进去。如果文件比较长我只会选择性地引用List.tsx可能有一千行但前两百行里已经包含了列表查询的参数对象、筛选表单、表格列定义那就够用了。第三步让它先提出方案。我不直接说“你开始写”而是让它先描述一下“导出功能的实现思路”。这样做的原因是ClaudeCode对项目的理解可能和实际有偏差通过它“说方案”来验证偏差比等它写完代码再发现错误成本低得多。它通常会回复类似“在列表组件上加一个导出按钮调用services/user.ts里已有的fetchUserList函数但它返回的是分页JSON需要新增一个导出专用函数”的方案。第四步修正方向。它的方案里有一句话踩在我们的“禁区”上——它会说“为了拿到全部数据建议直接把分页参数改为0或传一个很大的pageSize”。这句话在多数项目里会被打回因为用户量稍微大一点这种写法就是性能灾难。我在对话里指出“导出接口由后端统一处理导出逻辑前端只负责传当前筛选条件不要自己拉全量数据”然后重新让它给方案。这里就体现出CLAUDE.md“特别注意”那节的功能了——如果你已经写明“禁止前端一次拉全量数据”AI大概率一开始就不会往这个方向想。第五步让AI动手并自查。方案确认后让它写代码。写完让它自己执行一次TypeScript类型检查项目里已经有pnpm run typecheck命令再拿当前页面跑一下截图对比。所有操作在终端里以工具调用的形式回显每一步我都看一眼日志再放行。整个流程走下来大约十分钟产出是一个符合团队规范的导出按钮功能。对比之前不做上下文管理直接丢需求给AI的结果——那一次它改了List.tsx、新增了一个废弃接口、还顺手改了一个无关组件的样式——这次的体验堪称丝滑。5.3 过程中能额外注意的点这个案例里最有价值的经验是“让它先说方案再让它动手”。我见过太多人把需求丢给AI之后等它写完代码再review那等于把一个超大代码块交给人来检查效率极低。让AI先说方案本质是让它把思考过程暴露出来你只要花十秒钟看方案就能提前过滤掉至少80%的大方向错误。另一点是文件引用要克制。很多人觉得多引几个文件AI会更聪明但上下文窗口是有限资源。一次引用超过六七个大文件不仅浪费窗口还会让AI把注意力放在无关细节上。明确“本次任务真正需要的文件是哪些”比“把所有相关文件都塞进去”重要得多。6. 常见问题与排查技巧实录6.1 为什么我改了CLAUDE.mdAI还是按旧规则干活这是最多踩的坑。ClaudeCode的CLAUDE.md加载时机是会话启动时如果你在会话开始之后修改了CLAUDE.md当前会话里AI看到的仍是旧版本。解决方法是要么开新会话让它重新加载要么在对话中明确说一句“我刚刚更新了项目根目录的CLAUDE.md请重新读取一遍”。我自己实测下来重新读取指令能生效但开新会话更干净利落。6.2 上下文太长了AI开始答非所问怎么办答非所问通常是两个原因一是上下文窗口确实快满了二是CLAUDE.md被写得太长挤占了任务相关信息。后者的解法是砍CLAUDE.md把非项目级的内容挪走。前者的解法是开新会话然后用一段精炼的开场白把关键信息重新交代。这两招配合使用绝大多数“AI忽然变傻”的问题都能秒恢复。6.3 引入文件之后AI还是漏看了关键代码和/add引入的文件AI一般都能读到但如果文件里相关代码在很远的位置比如两千行文件里只有一个小函数需要改它的注意力也可能被分散。解决办法是不要只引文件还要在对话里用一句话点出关键位置“注意看这个文件里xxx函数的实现它是本次改动的核心”。这本质上是给AI画了一个“重点高亮”很有用。6.4 团队新成员不知道CLAUDE.md这回事第一次把CLAUDE.md提交到仓库后团队同事可能会问“这个文件是干嘛的”。最简单的做法是写一条README片段或者直接在周会分享时提一句“这个文件是给ClaudeCode看的项目说明书大家日常遇到AI不懂约定时随手加一条描述”。等文件里积累的规则超过十条之后团队基本就形成习惯了。7. 写在最后的一点个人体会上下文管理这件事说到底是“教AI做人”的功夫。我踩过很多坑比如一开始什么规则都不写、开场白一句话就丢需求、把CLAUDE.md写得又长又杂乱。这些问题现在回头想想都很好笑因为本质上是我自己没想清楚“AI需要什么才能干活”而不是AI不够聪明。后来我养成了一个简单的习惯每次给ClaudeCode派活之前先花三十秒问自己三个问题——它知道这个项目的目标吗它知道这次改动涉及哪些文件吗它知道有哪些雷区不能碰吗如果三个问题的答案都是肯定的这次任务的效率一定不会差。这三个问题对应的恰好就是CLAUDE.md、/add文件引用和“注意事项”板块。如果你刚开始用ClaudeCode建议这周就做一件事花半小时写一份属于你的项目CLAUDE.md然后跑一个平常需要手动完成的小需求对比一下前后的差别。等你真的感受过“AI在几句话之内理解了你的项目”是什么体验你大概就再也回不到一段代码一段代码喂它的原始时代了。