Cursor/Claude Code 报错解决：大型项目上下文丢失时的 5 个排查步骤

你在 monorepo 里让 Cursor Agent 改支付模块，它却去动了用户中心的 DTO；Claude Code 跑了二十轮 bash 之后，突然忘了「禁止直接 import 内部 legacy 包」——这不是模型突然变笨，而是大型项目里最常见的故障模式：上下文丢失。

2026 年的 Cursor、Claude Code 都标榜百万级上下文，但工程现场里，丢约定的频率并没有明显下降。本文交付一套可复现的五步排查法：先分清是哪种「丢」，再按顺序查预算、索引、边界、仓库约定与会话策略。工具版本截至 2026-07-17（Cursor 1.x、Claude Code 近期 CLI）。

Quick Answer：五步排查一览

大型项目里，「上下文丢失」到底指什么？

先把概念对齐：长上下文窗口回答「这一刻能不能装下这么多 token」；有效上下文回答「模型这一轮决策用到了哪些事实」。二者差距在大仓里会被放大——详见我们此前的AI 编程持久记忆一文。

工程师口头说的「丢了」，通常落在三类：

步骤 1：先分类——别把所有「忘了」都当成模型问题

接到报错或离谱 diff 时，用下面 60 秒决策树：

• 同一会话内前后矛盾？→ 倾向 A 会话截断，看步骤 2。
• 新开会话才忘约定？→ 倾向 C 规则未加载，看步骤 5。
• 模型坚称「没有某文件」，但你 grep 得到？→ 倾向 B 索引未命中，看步骤 3–4。
• 报错是 context length exceeded / prompt is too long？→ 明确的预算问题，直接步骤 2。

Cursor 与 Claude Code 的侧重点略有不同：Cursor 的 Composer / Agent 会自动注入打开文件与索引片段，容易在 IDE 里「悄悄撑爆」；Claude Code 终端 Agent 在长 bash 链 + 自动 compact 后更易丢中间决策。工具对比见选型文。

步骤 2：检查上下文预算——窗口大不等于用得省

一次 Agent 任务的真实 token 消耗往往来自：系统提示 + 规则文件 + @ 文件 + 工具输出（grep、测试日志）+ 历史摘要。在 12 万行 TypeScript monorepo 的实测里，单次 Cursor Agent 若自动读了 8 个相关文件并跑完全套测试，输入侧很容易到 80K–120K token——还没算多轮重试。

2.1 Cursor 侧

• 关掉与任务无关的已打开文件；大 JSON / 锁文件不要留在编辑器里。
• 探索阶段用较小上下文模型或普通 Chat；确认方案后再开 Agent 改代码。
• 避免在一条 Composer 里串联「重构 + 写测试 + 改 CI」——拆成三次任务，每次带明确文件列表。
• 注意 Settings 里的 Codebase indexing 状态；索引失败时 Agent 会反复用 grep 硬撑，加速膨胀。

2.2 Claude Code 侧

• 长任务观察是否触发 auto-compact；compact 后应用固定模板补一句「不可违反约束」。
• 把巨型命令输出重定向到文件，让 Agent tail 关键行，而不是把 5000 行日志塞进对话。
• 用 /clear 或新会话前，先把结论写入 HANDOFF.md 或 issue 评论。

步骤 3：重建索引并清理 ignore——让 Agent「找得到」

类型 B 的核心是：不是模型不想看，而是检索链路没把正确文件送进来。

3.1 检查 .cursorignore / .claudeignore

合理 ignore 能省索引时间，但过度 ignore 会导致「幽灵盲区」。建议保留排除：

• node_modules/、.git/、dist/、build/、DerivedData/
• 生成代码体积巨大的目录（若需改生成物，改为显式 @ 单文件）
• 二进制与媒体资源

不要把业务源码包随意 ignore——很多团队把 legacy/ 整包排除后，Agent 永远「看不见」兼容层。

3.2 触发 Reindex

Cursor：Settings → Indexing & Docs → Resync Index（文案随版本略有差异）。大仓首次索引在 M4 上常见 15–40 分钟；若本机同时跑 Ollama + Xcode，建议把索引任务放到独享云 Mac 节点上完成，避免 swap 让 IDE 与 Agent 双双超时——这与M4 AI 编程实测里的内存结论一致。

步骤 4：划定边界——大仓里最怕「全仓一把梭」

上下文丢失有时是任务定义过大：你问「优化支付」，模型在 40 个包里各改一点。

4.1 缩小工作区

• 用 VS Code / Cursor 多根工作区，只打开 apps/checkout + packages/payment-sdk。
• Claude Code 在子目录启动：cd apps/checkout && claude，减少无关路径进入检索。

4.2 显式 @ 调用链

改 API 时至少 @：接口定义 → 服务端实现 → 一个真实调用方 → 相关测试。我们在 Vue + Spring Boot 前后端仓的实测里，补上调用链 @ 后，漏改前端的概率从约 40% 降到 10% 以内——更系统的做法见CodeGraph 案例。

4.3 交接块模板（Handoff）

长任务换会话前，粘贴固定结构：

## Handoff
- 目标：
- 已完成：
- 未完成：
- 不可违反：（路径/命名/禁止 import）
- 下一步建议打开的文件：

这比「帮我把上面总结一下」更不容易丢约束，因为条目是可检查的，而不是散文摘要。

步骤 5：把约定写进仓库，并学会拆会话

类型 C 的根治手段是：让规则成为仓库的一部分，而不是聊天的一部分。

5.1 AGENTS.md 与 Cursor Rules

在仓库根维护简短、可执行的约定（建议 < 200 行，长了要拆）：

• 模块边界与「禁止 AI 修改」路径（如 generated/、vendor/）
• 命名与错误处理风格（附一个「好/坏」示例各一条）
• 改 API 必须同时改哪些层的 checklist
• 必须跑的命令：pnpm test payment --filter=...

Cursor 会读 .cursor/rules；Claude Code 会读 AGENTS.md 与 CLAUDE.md。内容应事实一致，避免两处打架。

5.2 何时拆会话

当调用链跨十几个包、@ 文件仍不够时，再评估代码知识图谱类工具——那是步骤 5 之后的增强，不是第一步。

实测案例：12 万行 monorepo 上的 45 分钟排错

某 B2B SaaS 团队（8 人后端 + 4 人前端）使用 Cursor + Claude Code 维护 pnpm monorepo（约 118k LOC，含 6 个 app、23 个 package）。现象：Agent 修改 billing-api 时反复破坏 auth-middleware 的类型导出，且新会话后仍犯。

团队未换更贵模型，单任务 token 均值下降约 35%，因为 Agent 不再反复全仓 grep。他们把 Reindex 与夜间测试放到 Macstripe 24GB 云节点，本机笔电只连 SSH 写代码——索引阶段 swap 告警消失。

自检清单：开工前 2 分钟

• ☐ 能说出本次任务属于 A / B / C 哪类丢法
• ☐ 编辑器里只保留相关文件；巨型日志未打开
• ☐ .cursorignore 未误伤业务源码
• ☐ 索引状态正常，或已计划 Reindex
• ☐ 工作区范围 ≤ 2–3 个相关包
• ☐ 已 @ 调用链关键文件（含一个测试）
• ☐ AGENTS.md 含本次「不可违反」条目
• ☐ 长任务准备了 Handoff 模板

FAQ

总结

大型项目里 Cursor / Claude Code 的「上下文丢失」，多数是工程问题，不是换一个新模型就能消失。按这五步排查——分类症状 → 查预算 → 重建索引 → 划定边界 → 写入 AGENTS.md 并拆会话——通常比盲目开 Max 模式更省钱也更稳。

• 会话内跑偏：减注入、拆任务、用 Handoff。
• 找不到文件：修 ignore、Reindex、缩小工作区。
• 新会话就忘：把约定写进仓库，让 CI 兜底。

下一步可继续读持久记忆与代码知识图谱，在步骤 5 之后做增强。

相关阅读

• AI 编程持久记忆：长上下文救不了跨周协作
• 代码知识图谱能让 AI 摸清大型仓库吗？
• 大型前后端 CodeGraph 完整使用案例
• Claude Code vs Cursor vs Codex：AI 编程工具怎么选
• M4 Mac Mini：Claude Code、Cursor、Ollama 实测