papercuts

Papercuts

在當下捕捉小摩擦，而不偏離目前任務。彙總的條目顯示儲存庫需要打磨的地方 — 因此標準是：_另一位_貢獻者會遇到相同情況，且_儲存庫_能對此採取行動。

兩個問題測試

只有在兩者皆成立時才記錄：

1. 對任何人皆可重現。 不同的人，在新的 checkout 上，在此儲存庫工作會遇到相同的摩擦。這不是你的沙箱、shell 設定、機器、網路或一次性問題所特有。
2. 可在儲存庫中修復。 變更儲存庫的程式碼、設定、腳本或文件即可預防或減少它。

如果任一答案為「否」，就撐過去並繼續 — 不要記錄。

不要記錄

• 你環境的失敗。 沙箱 EPERM / listen / IPC-socket 錯誤、網路被封鎖或 fetch failed、權限拒絕、缺少系統工具。那是執行環境的問題，不是儲存庫的。
• 你自己的 shell 錯誤。 保留或特殊變數名稱（status、path）、未加引號的 glob、壞掉的 login-shell hook。修正指令 — 儲存庫中沒有需要打磨的地方。
• 暫時性的不穩定。 重試後成功且沒有儲存庫端原因的指令（網路閃斷、push 卡住、鏡像緩慢）。
• 你弄壞的本地狀態。 切換分支後部分 node_modules、過時的 dev-server 連接埠、骯髒的快取。重新執行安裝或清理。
• 儲存庫無法改變的第三方或測試版工具限制 — 除非修復方法是值得寫下的儲存庫端 workaround（那就記錄_那個_ workaround）。
• 產品或程式碼正確性錯誤（立即修復或追蹤為實際工作），以及你完成了什麼（那屬於任務摘要）。
• 機密、憑證、個人資料、原始客戶 payload，或敏感路徑。

當某件事失敗時，先問「這是儲存庫的問題，還是我/我的環境的問題？」只有前者才是 papercut。

主動記錄

1. 搜尋 .agents/PAPERCUTS.md 尋找等效條目並避免重複。

2. 在 ## Open 下附加一個未勾選的項目，使用此格式：

   - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <摩擦，以及最小有用的修復或 workaround>。
   

3. 保持在一到兩句話：什麼阻礙了，以及可能的儲存庫端修復。以摩擦為主，而不是你在做什麼。

4. 繼續原始任務。不要將 papercut 擴展成無關的工作。

使用 UTC 時間戳記和簡短的 agent 標籤（codex、claude、human）。僅在有助於未來分類時加入 PR 或任務識別碼。

檢視或解決

僅在使用者明確要求時，才挖掘整個工作階段或進行廣泛檢視。

當被要求檢視檔案時：

1. 對每個開放條目重新執行兩個問題測試；刪除任何未通過的條目（混入的環境/shell/暫時性雜訊）。
2. 去重複並分組相關條目。
3. 驗證每個存活的 papercut 仍可重現。
4. 先修復最小安全且高槓桿的條目。
5. 將已修復的項目移至 ## Resolved，勾選它們，並附加解決日期或 commit。將真正的錯誤導向正常的 issue/修復工作；將重複的檢視政策缺口導向 maintain-greptile-rules。

保留真正解決的 papercut 的有用歷史；不要僅為了縮短檔案而刪除它們。（從未屬於的雜訊 — 見步驟 1 — 不同：移除它。）