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 摸清大型倉庫吗？
• Cursor 改 API 總漏前端？CodeGraph 實測解決方案（Vue + Spring Boot）
• Claude Code vs Cursor vs Codex 選型
• Mac mini M4 適合 AI 程式設計嗎？Claude Code、Cursor、Ollama 實測