Vibe Coding 的命门：上下文管理实战

你正在用 Cursor 或 Codex 写一个中型项目。前两小时一切顺利，AI 生成的接口、组件、样式都像模像样。第三小时开始，你发现它变了：总是重复定义已经存在的工具函数，明明在项目开头约定了用 pnpm，它却开始生成 npm 命令，最致命的是，对话框里突然冒出一行：

codex ran out of room in the model's context window. start a new thread or ...

这行报错翻译过来很简单：模型的上下文窗口已经被塞满了。模型看不到上下文之外的信息，不是因为它变笨了，而是因为窗口里装的东西太多、太乱、太旧。

我在讨论 Vibe Coding 的最近观察中，一个越来越清晰的判断是：Vibe Coding 的上限从来不取决于模型有多聪明，而取决于你喂给它的 Context 有多干净、多结构化。换句话说，当模型能力到达一定水位之后，上下文管理才是决定 AI 编程能否进入真实项目的关键。

这篇文章围绕 Context 上下文管理展开。你会理解 Context 到底是什么，为什么它是 Vibe Coding 的命门，哪些报错本质上是 Context 问题，以及怎样用一套可落地的工程方法让它变得可控。

1. 为什么 Vibe Coding 一夜流行，但很多人用不下去

Vibe Coding 这个词由 Andrej Karpathy 在 2025 年初提出，核心是：用自然语言描述需求，让 AI 生成代码，人的角色从“写代码的人”变成“评审需求的人”。你用感觉、氛围、节奏驱动，AI 负责把这种感觉翻译成可运行的实现。

这个概念之所以流行，是因为它让“不会写代码的人也能造软件”第一次变成现实。大量原型、小工具、自动化脚本在几天内被造出来，开发者体验确实爽。但问题也出现在这里：当项目复杂度上来之后，AI 开始频繁“失忆”。

典型场景有三种：

1. 你让 AI 重构一个模块，它却把之前约定好的目录结构打乱了。
2. 同一个函数，不同会话里被重复实现了好几次，每个版本还不一致。
3. 对话越长，AI 回答越偏，最后甚至开始“胡言乱语”。

大部分人会把这些现象归咎于“模型能力不行”，但更准确的判断是：你从来不知道模型当前看到了什么，也没管理过它看到的范围。模型不是人，它没有长期记忆，它只能在每次推理时查看上下文窗口里已有的内容。窗口里放什么、放多少、怎么组织，直接决定输出质量。

这篇文章的读者应该分两类。一类是已经在用 AI 编程工具、但对项目质量不满意的人，你需要一套系统性的上下文管理方法；另一类是想把 Vibe Coding 引入团队、却担心代码失控的技术负责人，你需要理解 Context 为什么是工程协作的瓶颈，以及如何制定规则。

接下来，先把 Context 的概念讲透。

2. Context 到底是什么：从 Vibe Coding 看上下文管理

2.1 Vibe Coding 的运作闭环

Vibe Coding 的典型闭环是四步：

1. 你描述需求（自然语言）。
2. 模型读取项目上下文（目录结构、文件内容、历史对话、约束条件）。
3. 模型生成代码或修改文件。
4. 你运行并反馈结果，回到第 1 步。

这个闭环是否稳定，取决于第 2 步。如果项目上下文完整、干净、结构化，模型的每一步都能站在正确基线上；如果上下文混乱、过时、超载，模型的输出就会开始漂移。

2.2 上下文窗口（Context Window）

上下文窗口是模型一次推理能够“看到”的 token 数量。Token 是文本的最小单位，一个汉字大约对应 1 到 2 个 token，一个英文单词大约 1 个 token。窗口内的内容会参与注意力计算，窗口外的内容对模型来说等于不存在。

目前常见模型上下文窗口从几万 token 到上百万 token 不等。1M token 听起来很大，但一个中型代码仓库的全部源码、README、设计文档、构建日志加起来很容易超过这个规模。如果你一次性把整个仓库都塞进去，仍然会撞到上限。

2.3 上下文内容的组成部分

在实际 Vibe Coding 工具中，注入到上下文窗口的信息通常包括：

注意一个事实：窗口里的信息并不是等价的。系统提示词和项目级指令决定了模型的行为基线，对话历史决定了模型对“最近发生了什么”的感知，文件内容和工具输出决定了模型当前操作的依据。如果这些信息互相矛盾，模型会倾向于选择信号更强的部分，这往往是规则丢失的原因。

2.4 为什么上下文会“越用越乱”

如果完全不管理，上下文会自然劣化。常见表现是：

• 对话到了第 50 轮，前 40 轮的信息还占着 token，但很多已经失效。
• 每个任务都让 AI 读取整个仓库，窗口很快被占满。
• 没有项目级说明，AI 每次都要从零猜测你的代码风格。
• 自动压缩（Auto-compaction）之后，信息被“温和地丢弃”，有时丢了关键约束。

这就是那句错误的由来：context is too large and auto-compaction could not recover this turn。自动压缩不是万能的，它可能裁掉关键信息，导致模型无法继续。把上下文管理寄托在自动压缩上，等于把系统稳定性寄托在“希望 GC 帮我把内存回收干净”，偶尔能行，但不可依赖。

3. 认识“上下文杀手”：典型错误与根因分析

在搜索 Vibe Coding 相关内容时，最常看到的报错大致有这几类。它们并不是同一类问题，需要分开对待。

3.1 一张表看懂常见 Context 报错

第一类错误说明请求时没有做 token 预算。你让模型读取了大量文件，实际 token 已超过限制。此时需要在发送前对文件名、文件大小做过滤，而不是让模型自己去“只读一部分”。

第二类错误是最典型的“会话失忆”问题。Codex、Cursor 这类 Agent 工具会在对话内部累积历史记录，对话越长，窗口被占用的比例越高。当窗口接近上限时，工具会尝试压缩历史，但压缩必然有损耗。

第三类要特别留意：自动压缩是兜底方案，不是管理方案。一旦压缩失败，整个会话就处于不可靠状态，最好的做法是立刻新开会话，用结构化总结恢复状态，而不是继续硬聊。

第四类从近期社区讨论和工程实践反馈看，大请求体在弱网环境下容易触发传输层错误。此时优先优化上下文体积，而不是反复重试。

额外提醒：有些context error其实是系统层面的，比如error response from daemon: get "https://registry-1.docker.io/v2/": context来自 Docker 拉取镜像时的请求上下文，和 Vibe Coding 里的 Context 不是一个概念。排错时先判断报错来自哪一层：是模型 API、是 Agent 工具，还是底层的操作系统/网络组件？不要把所有带有 context 字样的报错混为一谈。

3.2 大窗口并不能解决上下文问题

有人会说：既然 1M token 窗口那么大，干脆把所有项目文件都塞进去不就行了？这个思路有两个问题。

第一，成本与延迟。上下文越大，每次请求耗费的算力和时间越多，多轮交互的体验会迅速下降。大窗口不是免费的。

第二，注意力稀释。模型在窗口内不同位置的信息上投入的注意力并不均匀。大量无关文件混在一起，关键约束很可能淹没在噪声里。工程实践表明，窗口并不是越大越好，而是在需要的范围内越小越好。

所以，上下文管理的目标不是“装得下”，而是“放得准”。

4. 上下文管理的核心策略：先讲思路，再给方案

4.1 策略一：最小化原则

每次请求，只给模型当前任务真正需要的文件。不要默认“读整个仓库”。绝大多数 AI 编程工具支持在问题中指定文件路径，或在编辑器里选中相关代码。这个动作成本很低，但对窗口的节省非常明显。

举例来说，修复订单模块的一个 bug，需要的是order.ts、order.test.ts和错误日志，而不是user.ts、payment.ts、inventory.ts。你给出的相关文件越少，模型越容易聚焦。

最小化原则背后是一条工程常识：输入的大小决定了输出的质量上限。上下文越大，模型检索到正确答案的概率反而越低。

4.2 策略二：把约束放到项目级指令文件

与其每轮对话都重申“我们使用 pnpm、目录结构是 xxx、测试用 vitest”，不如把这些规则固化到项目根目录的CLAUDE.md或AGENTS.md。多数 Agent 工具会在会话初始化时自动读取这类文件，相当于给 AI 一份“入职手册”。

这里有一个容易被忽略的点：项目级指令不是 README。README 是给人看的，可以写得随意；AGENTS.md是给模型看的，它决定模型在生成代码时的默认行为。语法要明确，规则要可执行，避免模糊表述。

4.3 策略三：会话拆分与状态总结

长任务不要在一个会话里硬扛。拆成多个子任务，每个子任务独立会话。每完成一个阶段，把结果整理成“阶段总结”文档，写进项目docs目录。下一个会话开始时，让 AI 先读这份总结，而不是重读所有历史。

这个策略的收益是复利式的。最初你可能觉得写总结浪费时间，但当你需要从第 3 个小时的状态继续推进时，一份结构化的总结比 50 轮对话历史高效得多。

4.4 策略四：外部记忆与知识图谱

当项目信息量很大时，可以用外部记忆扩展窗口。MCP（Model Context Protocol）工具可以连接项目文档、Notion、数据库、知识图谱，按需查询。

最近在社区里可以看到graphify knowledge graph context这类方案，核心思路是：把项目中的实体、关系、文档索引成图，模型通过查询接口只取当前需要的子图，而不是把所有信息堆进窗口。换句话说，模型不再需要在窗口里“死记硬背”，而是可以“按需查资料”。

这带来的变化是结构性的：窗口内只放少量核心信息，海量可查询记忆放在窗口外。未来的 Agent 会越来越像“连了一个数据库的编译器”，而不是“一本不断翻页的百科全书”。

4.5 策略五：主动压缩与信息分层

在会话中，每隔一段时间主动让模型总结当前进度、已完成的文件、待办事项、关键决策。把这个总结放在会话靠前位置，覆盖掉那些已经过期的细碎对话。

技术上可以用“信息分层”的思路：最上层是任务目标，中间是约束和规则，最底层是当前要操作的代码细节。模型在每轮推理时，先看到目标，再看到规则，最后才看到代码。这样即使窗口内的代码细节过期了，目标和规则仍然在起作用。

4.6 策略选择对比

5. 环境准备与工具链选择

动手实践前，先理清环境。以下是通用组合，版本请以实际工具官方要求为准。

• 操作系统：Windows / macOS / Linux 均可。
• AI 编程工具：Claude Code、Codex CLI、Cursor 或同类支持 Agent 的工具。
• 运行环境：Node.js 18 或更高版本（多数 CLI 工具的宿主环境）。
• Python 3.10 或更高版本：用于编写自定义上下文管理脚本。
• 项目本身：一个 Git 仓库，大小不限，但建议先拿中小项目实验。

为什么要强调“先拿中小项目实验”？因为上下文管理的收益在复杂项目中才明显，但初学者如果直接在大项目里折腾，很容易在排错中迷失。先在小项目上建立“上下文预算”的直觉，再迁移到大项目。

Vercel 提供的 AI Vibe Coding 平台把项目上下文做成了可视化信息结构，你可以在界面中查看当前上下文占用、目标文件、相关文档。这类工具非常适合刚接触上下文管理的开发者，因为你能直观看到“窗口被什么占满了”。

另外，鸿蒙开发场景也在出现 AI 辅助开发的趋势。底层逻辑一致：先让模型理解项目结构，再生成代码。只是在落实到国产 IDE 和鸿蒙 SDK 时，要以对应工具的实际字段为准，不要照搬其它平台的配置。

6. 完整示例：从零配置一个可用的 Context 管理方案

这一节用一个示例项目，把前面讲的策略落成具体文件和命令。你不需要照抄全部内容，重点理解每一处配置在解决什么问题。

6.1 第一步：创建项目级指令文件

在项目根目录创建AGENTS.md：

# 项目开发约定 ## 技术栈 - 前端：React + TypeScript + Vite - 后端：Node.js + Express - 包管理：pnpm - 测试：Vitest ## 目录结构 - src/ : 前端源码 - server/ : 后端源码 - docs/ : 项目文档与阶段总结 ## 编码规范 - 组件使用函数组件 + Hooks - API 路径统一使用 /api 前缀 - 错误处理统一返回 { code, message } - 不要修改 database 目录下的迁移脚本 ## 当前任务（由 AI 维护） - 最近完成：用户登录接口 - 正在处理：订单列表页 - 下一步：接入支付回调

说明：这个文件的价值不是模板本身，而是把“团队里口头约定了很多次”的规则一次性固化下来。你会发现，之后每一轮对话，AI 都会默认遵守这些约束，不需要你重复。

注意：如果多人协作，这份文件相当于给 AI 的入职文档，也要像 README 一样评审和维护，避免写进过期规则。

6.2 第二步：写一个上下文预算检查脚本

上下文超限的报错，往往发生在请求已经发出之后。更好的做法是发送前自查：检查文件大小、预估 token，并给出警告。

#!/usr/bin/env python3 # 文件路径：scripts/check_context.py """ 简单的上下文预算检查脚本。 用法： python scripts/check_context.py --path src/server --max-tokens 120000 """ import argparse from pathlib import Path # 粗略估算：1 个中文字符约 1.5 token，1 个英文单词约 1.3 token def estimate_tokens(text: str) -> int: chinese_chars = sum(1 for ch in text if '\u4e00' <= ch <= '\u9fff') other_chars = len(text) - chinese_chars return int(chinese_chars * 1.5 + other_chars * 0.4) def main(): parser = argparse.ArgumentParser(description="Context 预算检查") parser.add_argument("--path", required=True, help="要扫描的文件或目录") parser.add_argument("--max-tokens", type=int, default=120000, help="窗口上限") args = parser.parse_args() path = Path(args.path) if path.is_file(): files = [path] else: files = [p for p in path.rglob("*") if p.is_file()] total_tokens = 0 for f in files: try: content = f.read_text(encoding="utf-8") except UnicodeDecodeError: continue tokens = estimate_tokens(content) total_tokens += tokens if tokens > 2000: print(f"[大文件] {f} : ~{tokens} tokens") print(f"\n预计总 token：{total_tokens}") if total_tokens > args.max_tokens: print(f"[警告] 已超过窗口上限 {args.max_tokens}，建议按目录拆分或删除无关文件。") raise SystemExit(1) print("[OK] 上下文预算在安全范围。") if __name__ == "__main__": main()

核心逻辑：把要发送给模型的路径内容先扫一遍，用估算值判断是否接近窗口上限。实际项目中，建议把扫描范围从“仓库根目录”改为“当前任务相关目录”，因为只有这部分才会被真正送入上下文。

Token 估算是启发式的，不要求精确。它的价值在于给开发者一个“这个目录到底多大”的直觉，而不是替代模型 API 的精确计数。

6.3 第三步：配置 MCP 外部记忆

MCP（Model Context Protocol）是连接模型与外部信息源的标准协议。通过 MCP，你可以在不把整个文档塞进窗口的情况下，按需查询外部信息。

下面是一个 MCP 配置示例，以 JSON 格式放在工具的 MCP 配置文件中：

{ "mcpServers": { "project-docs": { "command": "npx", "args": [ "-y", "mcp-docs-server", "--docs-dir", "./docs" ], "env": { "DOCS_INDEX": "graph.json" } }, "knowledge-graph": { "command": "npx", "args": [ "-y", "mcp-graph-server", "--source", "./graph.db" ] } } }

说明：不同 AI 编程工具，MCP 配置文件的路径和格式可能不同，通常可以在工具的设置面板中找到。上述示例演示的是一种通用倾向：用docs-dir指向文档目录，用graph.json指向知识图谱索引。模型需要了解某个接口细节时，会通过 MCP 查询，而不是提前把 docs 全部加载进窗口。

注意：不要照抄这里的命令名。mcp-docs-server、mcp-graph-server只是示例，真实项目需要去对应工具的官方仓库确认可用命令。

6.4 第四步：会话总结模板

当一个阶段结束时，用下面的提示词让 AI 输出结构化总结，写进docs/session-summary.md：

请总结本次会话，输出以下格式： - 会话目标： - 已完成的文件/功能： - 关键决策与原因： - 遇到的问题与解决方式： - 当前状态： - 下一步 TODO： - 对下一个会话的指令（供 AI 阅读，200 字内）：

这个模板最大的价值是“交接班笔记”。下一个会话开始时，让 AI 只读这份文件，就能恢复到接近本次结束时的状态，而不需要把几十轮对话都带过去。这段提示词本身很短，但它是整条上下文管理链条中最重要的文档。

7. 运行验证：如何判断 Context 管理是否生效

配置完成后，不能只凭“感觉 AI 变聪明了”来判断。下面是可验证的检查点。

7.1 验证项目级指令是否生效

在项目根目录执行一个简单任务，比如“告诉我这个项目用什么包管理器”。

预期：AI 直接回答pnpm，而不是反问“请提供更多上下文”。如果 AI 无法回答，先检查AGENTS.md是否被工具读取。有些工具需要重新启动会话后才能加载新的项目级指令。

7.2 验证上下文预算脚本

python scripts/check_context.py --path src --max-tokens 120000

预期输出类似：

[大文件] src/api/order.ts : ~12000 tokens [大文件] src/components/OrderTable.tsx : ~8000 tokens 预计总 token：45000 [OK] 上下文预算在安全范围。

如果输出[警告]，说明当前目录不适合整体送入，需要按文件或子目录拆分。

7.3 验证会话总结

开一个新会话，先让 AI 读取docs/session-summary.md，然后问：“根据总结，我们下一步要做什么？”

预期：AI 能准确说出“接入支付回调”及相关细节。如果 AI 回答不上来，说明总结文档太粗，丢失了关键上下文。需要把更细的约束写进总结。

7.4 观察窗口占用

大多数 Vibe Coding 工具都提供上下文占用查看能力，比如在界面显示类似Context 68% used的进度条。健康的状态是：单个会话的上下文占用长期维持在 60% 以下。超过这个值，就该考虑拆分下一步工作。

判断标准很简单：观察窗口占用曲线。如果它在每次会话中都快速冲到 80% 以上，说明你的输入习惯需要调整；如果长期保持在 50% 附近，说明你的上下文管理已经形成肌肉记忆。

8. 常见问题与排查思路

关于error running context: an error occurred during ssl communication这一类问题，社区里不少用户第一次遇到时会以为是工具坏了。更稳妥的判断是：当上下文体积特别大、网络链路又不稳定时，传输层就会成为瓶颈。如果你确认网络环境正常但该错误反复出现，优先优化将要发送的内容量，而不是依赖重试。

9. 最佳实践与工程建议

9.1 把上下文管理纳入代码评审

上下文管理不应该只是个人技巧。团队协作时，建议把AGENTS.md、docs/session-summary.md纳入 Git 评审流程。任何影响 AI 行为的重要规则变更，都要像 API 变更一样评审。

最简单的方式：在 Pull Request 模板里加一个 checkbox，要求任何 AGENTS.md 变更必须附带说明。这样做能避免团队里某个人悄悄改了规则，导致其他成员会话中的 AI 行为突然变化。

9.2 建立“最小上下文清单”

对每个常见任务类型，维护一个清单：

• 修改 bug：bug 描述 + 相关文件路径 + 最近一次错误日志
• 新增接口：接口定义 + 数据库表结构 + 依赖的其他模块
• 重构：目标 + 目录结构 + 影响范围 + 回归测试命令

这个清单本身就是上下文管理的执行标准。你可以在 AGENTS.md 中声明这些模板，让 AI 在开始任务前主动向你“反问缺失项”。

9.3 定期清理过期上下文

在工具界面上，把那些已经完成、被新会话取代的对话归档或删除。不要让工具替你积累无限的历史。每个会话只保留当前任务的信息，这是最容易被忽略也最有效的优化。

清理动作要形成习惯。建议每次完成一个可交付的阶段性成果后，做三件事：生成总结、关闭旧会话、开一个新会话。三步加起来不超过五分钟，收益却能持续到项目结束。

9.4 用知识图谱做“查得到但不占窗口”的长期记忆

如果项目文档非常多，可以考虑引入知识图谱类方案。基本思路是：把文档、接口、概念拆成节点和关系，索引到图数据库或向量库。模型通过工具调用只获取与当前问题相关的子图。

这相当于把“死记硬背”变成“按需查资料”，窗口利用率会高很多。从社区近期讨论看，graphify knowledge graph context这类方向正在把知识图谱与 Agent 的工具调用能力结合起来，未来 Context 管理的大趋势是“窗口内放少量核心信息 + 窗口外挂海量可查询记忆”。

9.5 安全与权限提醒

接入 MCP 或外部知识库时，注意最小权限原则：

• 只给模型读必要目录的权限，不要让它搜索整个磁盘。
• 对包含密钥、密码的文件，不要放进可被模型读取的路径。
• 知识图谱或文档服务如果包含内部敏感信息，要设置访问控制。
• 任何外部服务的凭证都要通过环境变量注入，不要硬编码进配置。

调试阶段，先把权限限定在测试目录。确认模型只读取了应该读取的内容后，再逐步放开范围。

9.6 针对鸿蒙等新平台的落地建议

如果是在鸿蒙开发工具链中做 Vibe Coding，通用策略可以套用，但要注意几点：

• 项目级指令文件是否被对应 IDE 插件读取，需查看插件文档。
• 鸿蒙 SDK 的 .ets 文件、资源目录结构，在上下文中要显式描述清楚。
• 多模式开发工具的能力边界可能与主流工具不同，先跑通最小用例再扩展。

核心判断不变：任何平台的 Vibe Coding，质量瓶颈都是 Context。谁把上下文管理做好，谁就能在 AI 编程上获得稳定生产力，而不是“偶尔灵光一现、常常稀里糊涂”。

10. 总结与下一步

本文围绕 Vibe Coding 中的一个核心问题——Context 上下文管理进行了展开。

你已经看到：Context 不是玄学，而是模型中参与计算的 token 集合，是可以被工程化管理的资源；Vibe Coding 项目的质量下滑，多数不是因为模型不够强，而是上下文没有管好；常见报错如maximum context length、context is too large、codex ran out of room都可以通过预算检查、会话拆分、项目级指令、外部记忆等策略规避。

我也从最小化原则、项目级指令、会话总结、MCP 外部记忆四个角度，给出了一套可以落地的配置方案，并且提供了验证方法：不是“感觉变好了”，而是通过预算脚本、指令读取测试、总结恢复测试来定量确认。

如果你正在使用 Cursor、Codex、Claude Code 或国产 IDE 做 AI 编程，建议按这个顺序实践：

1. 先建立项目根目录的AGENTS.md，把技术栈、目录结构、编码规范写清楚。
2. 在发送给模型的每次请求中，明确指定相关文件路径，而不是让 AI 自己去扫描整个仓库。
3. 在会话进行中每完成一个阶段就生成结构化总结文档。
4. 当窗口占用超过 60% 时，主动新开会话并用总结恢复状态。
5. 项目文档庞大时，再引入 MCP 或知识图谱扩展长期记忆。

下一步可以深入的方向是 Context Engineering 的高级玩法，比如meta context engineering via agentic skill evolution——让 Agent 在执行任务过程中，不断生成和进化自己的上下文工具