Claude Code 代理筆記檔大小警告：96 次提交中兩次誤觸的偵錯經驗

這是我每天在 Windows 電腦上執行的自主 Claude Code 代理的一個現場筆記。這些數據來自它自己的日誌，而非記憶。我的代理會維護一個「交接筆記」，這是一個 Markdown 檔案，供下一個會話優先讀取，以便了解目前執行的內容、變更了什麼以及哪些部分不能中斷。當這個檔案超過 400 行時，一個掛鉤（hook）會發出警告。

在 10 月 8 日，該筆記檔案有 615 行，大約 201 KB。代理首次讀取時被拒絕了，因為它有 56,521 個 token，超過了單次讀取 25,000 個 token 的限制。這導致原本應該優先讀取的檔案無法一次性讀取。

這個警告機制確實存在。該掛鉤會在每個 shell 指令執行後運行。如果指令是一個成功的 git commit，並且交接筆記超過 400 行，它就會在每個會話中列印一次警告，但不會阻擋任何操作，因為提交已經完成。

Git 歷史記錄顯示，該筆記檔案在 8 月 19 日、8 月 28 日和 9 月 21 日超過了 400 行，並在 8 月 20 日和 9 月 20 日回到了限制以下。從 9 月 21 日的提交使其超過 400 行開始，直到 10 月 8 日上午，共有 84 次提交修改了該筆記，且每次提交後檔案都超過 400 行。

然而，在此期間，掛鉤的日誌中只記錄了兩次警告，分別在 10 月 1 日和 10 月 4 日。

10 月 8 日，代理將舊的部分移到一個歸檔檔案中，使得該次提交後筆記檔案剩下 368 行。同時，它也增加了一個測試，當檔案超過 400 行或 80,000 位元組時會失敗。設定位元組限制是因為即使行數不多，少數長行也可能佔用大量空間，例如當天前 41 行就達 27 KB。

這項操作解決了檔案過大的問題，但並未解釋為何之前只發出兩次警告。

為什麼只有兩次警告？Claude Code 會將 shell 指令的結果，包括標準輸出（stdout）、標準錯誤（stderr）和一些旗標，傳遞給掛鉤，但沒有結束代碼（exit code）。因此，掛鉤必須從文字內容中猜測指令是否成功。

它會尋找「files changed」、「file changed」或一個閉合方括號，這些通常來自 git 在提交後列印的摘要行，例如 [master 1a2b3c4] message。然而，我的代理使用 git commit -q 進行提交，而靜默模式（quiet mode）不會列印這個摘要行。

10 月 9 日，我檢查了該專案的代理會話日誌。在 84 次提交的起始與結束之間，共有 96 次 shell 呼叫執行了 git commit 指令，且所有 96 次都使用了 -q 參數。舊的檢查機制只接受了其中兩次，時間與掛鉤日誌中的兩次警告完全吻合。

這兩次警告都是意外觸發的：10 月 1 日，相同的指令在提交前執行了 git diff --cached --stat，其統計行顯示「6 files changed」。10 月 4 日，指令在提交後執行了 git log --oneline -1，其列印的主題包含「KR_HOLIDAYS[2026]」。

值得注意的是，警告觸發並不總是會立即導致修正。在 9 月 21 日之前，該專案的日誌中還有四個大小警告。9 月 5 日和 10 日的警告之後，筆記檔案一直保持在 400 行以上，直到 9 月 20 日。而 8 月 20 日和 9 月 20 日的警告之後，都在兩分鐘內有一次提交將筆記檔案恢復到 400 行以下。

在 84 次提交的起始與結束之間，舊的檢查機制在 96 次呼叫中只識別出 2 次提交。修正方法是：當指令使用 -q 或 --quiet 參數，且輸出內容不包含「nothing to commit」、「nothing added to commit」、「no changes added to commit」、「error:」、「fatal:」或「aborting commit」時，掛鉤現在會將其視為一次提交。

如果存在結束代碼，它仍然是判斷的首要依據。將新的檢查機制應用於相同的 96 次呼叫，它接受了 94 次。它拒絕的兩次是真正的失敗：一次遇到了殘留的 index.lock，另一次則指定了一個不存在的檔案。現在有八個測試涵蓋了這個機制，這些測試是根據日誌中的指令和輸出格式建立的，其中三個在變更前是失敗的。

這些規則顯示，決定何時發出警告的檢查機制也需要測試，並且這些測試應該使用實際執行的指令來編寫。在沒有結束代碼的情況下，不應從裝飾性輸出判斷成功。摘要行就是一種裝飾，而且一個旗標就可以將其關閉。

如果每次運行都能測量，就應該將其變成一個測試。大小測試每次都以相同的方式失敗，這表示警告機制是基於猜測。我們應該計算警告的次數，而不僅僅是規則本身。在 84 次超過限制的提交中，只有兩次警告一直存在於日誌中。

這篇文章的來源。這裡的每一篇貼文都來自於我每天運行的一個設定：一個 CLAUDE.md 檔案、代理在執行任何操作前讀取的記憶檔案，以及一個獨立的稽核代理，它會返回「PASS」或「FAIL」。關於這個設定的書籍，前三章提供免費 PDF 試閱。

完整版包含 11 章，外加 4 個即用模板（CLAUDE.md 入門、記憶檔案、稽核清單、測量指南），以及每章的實作部分，PDF 售價 19 美元。歡迎在評論中提出關於此設定的問題，我將根據實際發生的情況而非理論來回答。