一份放在專案根目錄的文件

Claude Code 有一個約定：專案根目錄放一份 CLAUDE.md，每次它在這個專案工作，都會先讀這份文件。官方定位是「專案說明」，但我用了幾個月之後的體會是：這份文件真正的價值，是當作專案的病歷。

我的 CLAUDE.md 裡最重要的一節叫「地雷清單」，開頭就寫明：「每一條都是真實事故，改碼前先讀。」

為什麼 AI 特別需要這份文件

人類工程師在一個專案待久了，會長出肌肉記憶：看到某種寫法會本能地皺眉頭，因為上次就是這裡炸的。AI agent 沒有肌肉記憶——每個新的工作階段，它對這個專案的「直覺」都是從零開始。

沒有地雷清單的情況下，agent 寫出來的程式碼是「一般而言正確」的：符合語言慣例、邏輯正確、測試會過。但「一般而言正確」恰恰是地雷的形狀——我專案裡每一條地雷，都是「看起來完全正常的程式碼，在這個專案的特定條件下會炸」。這種知識不存在於任何公開語料裡，只存在於這個專案的事故史裡。你不寫下來，agent 就會再踩一次。

實際的條目長什麼樣

舉一條真實條目的去識別化版本：

SQL 字面 % ＋參數：正式站驅動程式會把 % 當佔位符——本機全綠、只炸正式站。防線在 db.py 的轉換層，寫含 % 的 SQL（LIKE、日期格式化）要特別確認。

注意它的結構：症狀（本機全綠只炸正式站）＋根因（驅動程式解析）＋防線位置（db.py）＋觸發條件（LIKE、日期格式化）。四個要素齊了，agent 下次寫到含 % 的 SQL 就會停下來檢查，而不是自信地送出一段「一般而言正確」的程式碼。

寫這份文件的三個紀律

一、只寫「為什麼」，不寫「做什麼」。 程式碼本身就說明了做什麼。文件要留的是程式碼說不出來的事：這裡為什麼繞了遠路、那個看似多餘的檢查在防什麼。

二、每一條都必須是真的出過事。 「理論上可能出錯」的事情無限多，寫進去只會稀釋真正重要的條目。我的標準很硬：沒有對應事故的教訓，不配佔一條。這也讓整份清單自帶優先級——每一條都是用真實損失換來的。

三、教訓寫在出事的程式碼旁邊，清單只做索引。 重大事故的註解直接留在案發現場，CLAUDE.md 是總目錄。agent 讀碼時在現場看到警告，比在另一份文件裡看到更有效。

這份文件的意外收穫

寫到後來我發現，這份「給 AI 看的文件」同時是我自己最好的交接文件——如果哪天有第二個人加入，或半年後的我自己回來看，這份帶著事故日期的清單比任何架構圖都有用。

給 AI 的文件跟給人的文件，寫到極致是同一份：具體、誠實、帶後果。接下來十天，我把清單裡最痛的十條一一攤開。