1. 项目概述：从“失忆”现象说起

最近在折腾 Claude Code 这个工具，发现一个挺有意思也挺让人头疼的问题：我明明在对话里给了它一个完整的项目结构，让它帮我写个函数，它写得挺好。但当我接着让它修改这个函数，或者基于这个函数再写点别的逻辑时，它有时候就像“失忆”了一样，要么重复问我之前已经交代过的细节，要么干脆基于一个错误的理解去写代码。这感觉就像你跟一个记忆力时好时坏的程序员搭档，你得不停地把说过的话再说一遍。这种现象，在 AI Agent 领域，尤其是在处理长对话或复杂任务时，其实非常普遍，核心原因就出在“上下文管理”上。

简单来说，Claude Code 这类基于大语言模型（LLM）的编程助手，本质上是一个 AI Agent。它通过一个叫“上下文窗口”的东西来“记住”我们和它的对话历史、代码文件内容等所有信息。这个窗口的大小是有限的，通常用“Token”这个单位来衡量。当我们的对话和涉及的内容（比如你打开的几个大文件）加起来，超过了这个窗口的容量，模型就不得不“遗忘”最早的一些信息，以保证能处理最新的输入。这就是 Agent “失忆”的根本原因。理解并管理好这个上下文，是让 Claude Code 这类工具从“时灵时不灵”变成“可靠搭档”的关键。无论你是刚接触的新手，还是已经用它写了不少代码的老手，搞懂上下文管理的门道，都能极大提升你的开发效率。

2. 核心原理：Token、上下文窗口与“遗忘”机制

要解决“失忆”问题，我们得先拆解它的工作原理。这就像医生看病，得先知道病因。

2.1 Token：LLM 的“单词”

首先得明白 Token 是什么。它不是我们通常理解的英文单词或汉字。对于 LLM 来说，一个 Token 可能是一个单词（如 “apple”），一个单词的一部分（如 “ing”），一个标点符号，或者一个汉字。例如，“Claude Code is helpful!” 这句话，可能会被拆分成["Claude", " Code", " is", " helpful", "!"]这样几个 Token。中文的“你好世界”可能被拆成["你", "好", "世", "界"]。模型处理和理解文本，就是基于这一串 Token 序列。

为什么这很重要？因为上下文窗口的大小限制，就是针对 Token 数量的。常见的模型，比如 Claude 3 系列，可能有 128K、200K 甚至更大的上下文窗口。这意味着，你一次能塞给模型的对话历史+当前问题+系统指令等的总 Token 数不能超过这个上限。Claude Code 在后台会把你当前活跃的对话、相关的代码文件内容、它的思考过程等全部转换成 Token，然后一并提交给模型处理。

2.2 上下文窗口：Agent 的“工作记忆”

你可以把上下文窗口想象成 Agent 的“短期工作记忆”或“桌面空间”。这个桌面只有固定大小。当你开始一个新对话（新任务），桌面上是空的。你每说一句话（输入），每打开一个文件（注入内容），就相当于往桌面上放一些东西。Agent 就看着桌面上的所有东西来回答你的问题。

问题在于，这个桌面空间是有限的（比如 128K Token）。当你和它的对话越来越长，或者你打开了几个几百行的代码文件，桌面很快就被堆满了。为了能继续处理你的新问题，Agent 必须把桌面上最早放上去的、当前看来可能“不那么重要”的东西清理掉，腾出空间。这个“清理”过程，就是模型的“遗忘”。被遗忘的信息，对于后续的对话来说，就像从未存在过一样。

2.3 “失忆”是如何发生的？一个典型场景

让我们还原一个经典“失忆”现场：

1. 开始阶段：你打开了一个 500 行的main.py文件，并向 Claude Code 提问：“请帮我解释一下这个文件里的DataProcessor类是如何工作的。” Claude Code 将整个文件内容（假设 1500 Tokens）和你的问题一起放入上下文窗口，成功分析并给出了详细解释。此时上下文占用还很低。
2. 深入讨论：你接着问：“那么，我想在process方法里加一个缓存功能，避免重复计算，该怎么改？” Claude Code 基于对DataProcessor类的完整记忆，给出了一个不错的修改方案。你让它直接应用修改。
3. 引入新文件：为了完善功能，你打开了另一个相关的 800 行配置文件config.yaml，并问：“根据这个配置，缓存的有效期应该怎么设置？” Claude Code 现在需要把config.yaml的内容也读进来。此时，上下文里已经有了最初的对话、main.py的全部内容、第一次修改的讨论和结果。总 Token 数可能已经接近窗口上限。
4. “失忆”触发：当你继续追问：“好，那请把刚才提到的缓存有效期逻辑，集成到DataProcessor的process方法里，记得要和之前的缓存键生成逻辑保持一致。”问题来了：为了把config.yaml的内容和当前问题塞进窗口，模型可能被迫丢弃了最早的一部分信息——很可能就是main.py中关于DataProcessor类process方法原始实现的详细内容，或者第一次修改的具体细节。
5. 错误表现：于是，Claude Code 可能会出现以下反应之一：
   • 表现A（部分遗忘）：它还记得要加缓存，但忘记了缓存键具体是怎么生成的，于是可能会问你：“您之前提到的缓存键生成规则是什么？”或者它自己编造一个规则。
   • 表现B（严重遗忘）：它可能完全忘记了DataProcessor类的存在，或者混淆了方法，给出的代码逻辑混乱，甚至试图在一个不存在的类里添加方法。
   • 表现C（冲突与混淆）：它可能记住了多个版本的信息片段，导致生成的代码逻辑前后矛盾。

注意：这种“遗忘”并非完全随机，通常遵循“先进先出”（FIFO）的原则，即最早进入上下文的信息最先被丢弃。但一些更先进的模型或系统可能会尝试根据“重要性”进行选择性保留，不过这并不完全可靠。

3. Claude Code 的上下文管理机制剖析

Claude Code 作为 VS Code 插件，并不是简单地把所有打开的文件都一股脑儿塞给模型。它有一套自己的策略来管理上下文，以优化 Token 使用，延缓“失忆”的发生。理解这套策略，你才能更好地与之配合。

3.1 自动上下文注入：什么被“看见”了？

Claude Code 会根据你的操作，动态决定将哪些内容放入上下文。主要包括：

1. 当前活跃的对话历史：你与 Claude Code 在当前会话中的所有问答记录。这是最基本的上下文。
2. 当前焦点文件：你在 VS Code 中正在编辑或光标所在的文件。当你提问时，这个文件的全部或部分内容（取决于设置）有很大概率被包含进去。
3. 打开的相关文件：Claude Code 会通过文件引用（如import语句）、你对话中提及的文件名，或者它自己推测的相关性，尝试将其他已打开的文件内容也纳入上下文。但它会优先保证焦点文件。
4. 项目结构信息：当你要求它理解项目时，它可能会读取package.json、requirements.txt、目录结构等元信息文件。
5. 系统指令与角色设定：插件预设的“你是一个有帮助的编程助手”这类指令，也占用一部分 Token。

实操心得：我发现，当你选中一段代码再提问时，Claude Code 会优先将选中的代码块作为最相关的上下文，这比单纯把光标放在文件里更精准。例如，选中一个函数体，然后问“这个函数如何优化”，效果通常比不选中直接问要好，因为它减少了模型需要关注的无关代码量。

3.2 Token 预算的分配与争夺

假设 Claude Code 使用的模型上下文窗口是 128K Tokens。这个预算需要分配给以下几部分：

• 模型输出预留：模型生成回答也需要 Token，这部分需要预留出来。通常回答越长，预留越多。
• 系统指令与对话历史：固定占用一部分。
• 文件内容：这是最大的变量，也是“失忆”的主要诱因。

当多个大文件被同时纳入考虑时，就会发生激烈的 Token 预算争夺。Claude Code 的内部逻辑（我们无法完全知晓）会决定哪些文件内容被完整保留，哪些被截断（只取开头或结尾部分），哪些被完全丢弃。这种截断和丢弃，就是导致上下文不完整、进而引发“失忆”的直接操作。

一个常见的陷阱：你以为打开了 A、B、C 三个文件，Claude Code 就能同时“看到”它们三个的全部。但实际上，当三个文件都很大时，它可能只完整保留了 A 文件，B 文件被截取了一半，C 文件只被读入了前 50 行。如果你接下来的问题恰好依赖于 C 文件后半部分的关键类定义，那么“失忆”就不可避免。

3.3 与纯聊天界面的关键差异

在 Claude 的网页聊天界面中，上下文管理相对“单纯”，就是线性的对话历史。但在 Claude Code 中，上下文是“多维”的：

1. 时间维度：对话历史。
2. 空间维度：多个打开的文件、项目结构。
3. 操作维度：你的选中操作、编辑动作。

这种多维性使得上下文管理复杂了一个数量级。网页聊天中，你可以通过“总结之前对话”来压缩历史；但在 Claude Code 中，你很难手动总结几个正在编辑的复杂代码文件之间的关系。因此，Claude Code 的“失忆”问题往往更隐蔽、更棘手，因为它可能“记得”你们刚才的对话，却“忘记”了十分钟前你打开的那个关键工具类文件的内容。

4. 实战：诊断与应对“失忆”的策略

知道了原理，我们就可以主动出击，诊断问题并采取策略。下面是一些我实践中总结出来的方法。

4.1 如何判断 Agent 是否“失忆”？

“失忆”并非总是表现为直接回答“我不知道”。更多时候是表现为以下几种“症状”，你需要像调试程序一样保持警惕：

• 重复提问：询问之前已经明确提供过或讨论过的信息。例如，你刚解释了业务规则，它转头又问“这个规则的具体要求是什么？”
• 前后矛盾：在同一段对话中，对同一个概念、变量或函数的描述出现不一致。比如，前面说函数返回字符串，后面生成的代码却让它返回整数。
• 引用错误：提及一个不存在的文件名、类名或函数名，或者把A文件的功能张冠李戴到B文件。
• 逻辑断层：生成的代码缺少必要的导入、依赖，或者基于一个未被提及的假设。例如，突然使用一个从未定义过的全局常量。
• 性能下降：回答变得笼统、模糊，缺乏之前对话中体现出的对项目细节的把握。

当你观察到这些症状时，首先就应该怀疑：是不是上下文满了，关键信息被挤出去了？

4.2 主动管理：给 Agent 一个清晰的“工作区”

我们不能完全依赖工具的自动管理，必须主动干预。核心思想是：像给同事布置任务一样，为 Claude Code 准备清晰、简洁、必要的上下文。

策略一：对话分拆，任务闭环不要试图在一个超长的对话中解决所有问题。将大任务拆解成多个独立的、上下文自包含的小任务，并开启新的对话。

• 反面例子：在一个对话里，先后要求：1) 解释项目结构，2) 重构A模块，3) 为B模块写测试，4) 修复C模块的bug。
• 正确做法：
  • 对话1：专门讨论A模块的重构。只打开A模块相关的文件，任务完成后，如果满意，可以礼貌地结束对话（或者说“谢谢，这个任务完成了”）。
  • 对话2：新建一个对话，专门为B模块写测试。重新提供必要的背景（可以简要说明B模块的功能，引用A模块的重构结果），并打开B模块及其依赖的文件。
  • 好处：每个对话都从一个相对“干净”的上下文开始，避免了历史积累导致的污染和遗忘。虽然需要你重新提供一点背景，但比起在混乱中调试“失忆”的代码，成本更低。

策略二：精准提供上下文，而非全部打开不要无脑地打开项目里所有文件。在提问前，有意识地思考：回答这个问题，最少需要哪些信息？

• 操作技巧：
  1. 使用选中功能：永远优先选中你希望 Claude Code 关注的特定代码段（一个函数、一个类、几行逻辑），再提问。这为它提供了最精确的“注意力焦点”。
  2. 手动提供引用：在问题中，明确提及相关的文件名和关键部分。例如：“请看utils/helpers.py文件中的format_data函数，我想在service/processor.py的run方法里调用它，但需要注意数据格式，请帮我写这个调用逻辑。” 这样即使utils/helpers.py没有被自动纳入，你的提示也能引导它。
  3. 创建临时摘要文件：对于复杂的背景信息（如一系列配置项、业务规则），可以创建一个临时的context.md或notes.txt文件，将关键信息用清晰的格式写进去。在需要时，打开这个文件并让 Claude Code 参考它。这个文件通常很小，但信息密度高，比让模型去理解散落在各处的代码和注释更高效。

策略三：定期进行“上下文刷新”在长对话中，当你感觉模型开始出现“症状”时，可以主动进行刷新。

• 方法：用你自己的话，总结一下当前任务的核心状态、已做出的关键决策、以及接下来要做的步骤，然后将这个总结作为一条新的消息发送给 Claude Code。
  • 例如：“我们来回顾一下：目前我们在重构UserAuth类，目标是将密码验证和令牌生成分离。我们已经创建了PasswordService类来处理加密和验证，UserAuth类现在只负责调用。接下来的步骤是，调整login方法，让它使用新的PasswordService，并确保错误处理一致。这是当前的UserAuth类和PasswordService类的代码（附上代码）。请基于这个状态继续。”
• 原理：这条总结消息包含了高度浓缩的上下文信息，并且因为它是最新输入，所以被遗忘的可能性最低。这相当于你手动为 Agent 做了一次关键的“记忆强化”。

4.3 工具设置与优化建议

Claude Code 本身也提供了一些设置，可以帮助我们更好地管理上下文（具体位置在 VS Code 设置中搜索Claude）：

• 关注文件范围：有些插件允许你设置“包括当前项目中的所有文件”或“仅包括打开的文件”。对于大型项目，建议选择“仅包括打开的文件”或手动配置包含的目录，避免插件盲目读取大量无关文件，徒然消耗 Token。
• 理解“自动触发”规则：观察并熟悉 Claude Code 在什么情况下会自动读取文件内容（如文件被激活、光标移动、提及文件名）。这有助于你预测它的“所见”范围。
• 代码库索引（如果支持）：一些高级功能或企业版可能支持为整个代码库建立索引。这相当于为模型提供了一个外部知识库，在需要时可以快速检索相关信息，而不必把所有代码都塞进上下文窗口。如果你的项目非常庞大，可以关注此类功能。

常见问题与排查技巧实录

下面是一个我遇到过的典型问题及其排查思路的速查表：

5. 进阶思考：超越基础管理的模式

对于更复杂的项目协作，我们可能需要一些模式化的方法来系统化地管理上下文。

5.1 “会话快照”模式

对于重要的、阶段性的设计讨论或方案评审，我习惯创建一个“会话快照”。具体做法是，在对话取得关键结论后，我将整个对话记录（包括我的提示和 Claude Code 的回复，特别是包含代码块和决策逻辑的部分）复制出来，粘贴到一个项目内的文档中（如docs/claude_discussion_20240520_design.md）。这个文档就成了项目知识库的一部分。

好处：

• 永久记录：避免了上下文丢失导致设计决策丢失。
• 新人 onboarding：新队友可以通过阅读这些文档快速了解某个模块为什么这样设计。
• 后续参考：未来需要修改时，可以重新打开这个文档，将其中的关键信息作为新对话的起点，实现“记忆”的传承。

5.2 “分层上下文”意识

我们可以有意识地将上下文分为几个层次：

1. 战略层：项目目标、整体架构、核心规范。这部分信息通常很稳定，但很重要。可以通过一个固定的ARCHITECTURE.md或CONTEXT_GUIDE.md文件来承载，在开始重要新对话时，先打开这个文件。
2. 战术层：当前正在开发的模块/功能的设计思路、接口约定、待办事项。这部分可以通过任务管理工具（如 Issue 描述）或当前对话的“上下文刷新”总结来维护。
3. 执行层：当前正在编辑的具体文件、函数、代码块。这是最动态的一层，通过 VS Code 的焦点和选中操作来管理。

养成这种分层意识，能帮助你在与 Claude Code 协作时，更清晰地为它“加载”所需的信息层级，减少跨层信息干扰导致的混乱。

5.3 将 Agent 视为“需要清晰简报的队友”

归根结底，最有效的策略是改变心态：不要把它当作一个全知全能的“魔法黑箱”，而是把它看作一个能力极强但短期记忆有限、需要你清晰指挥的新人队友。

• 给你的“队友”清晰的任务简报（Prompt）：任务背景是什么？目标是什么？有哪些约束条件（代码风格、性能要求）？可以参考哪些现有资料（文件）？
• 给“队友”明确的交付物要求：你希望它输出代码、解释、还是方案比较？代码需要包含测试吗？
• 检查“队友”的工作：它给出的代码，你真的理解吗？直接运行吗？还是需要先 review？它给出的解释，逻辑自洽吗？
• 在“队友”困惑时提供帮助：当它出现“失忆”症状时，不要抱怨，而是像带新人一样，耐心地重新提供它缺失的信息。

这种心态的转变，能让你从被动地应对“失忆”故障，转变为主动地设计协作流程，从而最大化 AI 编程助手的价值。上下文管理，本质上就是你和这个特殊“队友”之间的沟通艺术。管理得好，它就是你得力的倍增器；管理不好，它就会成为那个总在关键时刻掉链子的“失忆”搭档。