CLAUDE.md 點寫：畀 Claude Code 睇得明你個專案規矩

每次都要重複解釋，就值得寫低

你個專案用 Vitest，Claude 卻加咗 Jest；元件一直用 PascalCase，新檔案又用另一套命名。呢啲情況唔一定要靠更長嘅 prompt 解決，可以將穩定嘅專案背景放入 CLAUDE.md。

Claude Code 會按位置載入相關指示，但 CLAUDE.md 係提供背景，唔係強制執行規則嘅程式。測試、格式檢查同權限設定仍然要各司其職。官方記憶文件有各層檔案嘅載入說明。

1. 先寫四類有用資料

唔需要再抄一份 README。先揀 Claude 做任務時需要、但單睇程式未必容易發現嘅內容：

1. 技術組合：用乜框架，重要版本同專案用途。
2. 可執行指令：開發、建置、測試、型別檢查，講明各自用途。
3. 慣例：檔案命名、資料夾分工、現有工具。
4. 陷阱同限制：曾經出過問題嘅寫法，附原因同替代做法。

以下係內容網站嘅簡化例子，唔係所有專案都適用：

# 專案背景
Next.js App Router、TypeScript、MDX。純內容網站，冇資料庫。

## 指令
- pnpm dev：本機開發。
- pnpm build：產生內容、建置網站及搜尋索引。
- pnpm typecheck：檢查 TypeScript；修改資料結構後要執行。

## 慣例
- React 元件用 PascalCase，例如 UseCaseCard.tsx。
- 工具函數用 camelCase，例如 formatIssueNumber。
- 文章 slug 用 kebab-case，已有網址唔好隨意更改。

## MDX 陷阱
大括號會被當成 JavaScript 表達式。
提示詞嘅填寫位置用 [填寫內容]，唔好用未定義嘅變數。

版本要由專案核對，指令要真係存在。如果文章範例同你個 package.json 唔同，跟你專案實際情況改。

2. 將含糊規矩改成可檢查要求

「寫好啲」太空泛；「沿用現有 Button 元件，唔新增第二套按鈕樣式」就容易驗收。「全部用 PascalCase」亦唔夠準，因為路由、測試同一般工具檔案可能各有慣例。

每條規矩寫清楚範圍、理由同例子。避免同一份文件一邊話唔准加套件，一邊又要求任務必須安裝新工具。遇到例外時，講明要先指出衝突，唔好自行猜。

密鑰、資料庫連線字串同客戶資料唔應放入指示檔。只寫環境變數名稱同取得方式，唔貼真值。

3. 用細任務驗收，唔好只問「明唔明」

先讀取適用嘅 CLAUDE.md 同現有文章列表元件。

請提出新增「歷史期數」頁面嘅最小方案，列出預計改動檔案、沿用元件同驗證指令。暫時唔寫程式。

如果文件同現有程式有矛盾，列出實際檔案作證，等我決定點修正。

再做一個小改動，睇實際結果有冇跟命名、沿用工具同執行檢查。冇跟規矩時，先查規矩有冇載入、係咪過時或者互相衝突，唔好每次都再加一條重複禁令。

4. 按範圍分層

Monorepo 可以喺根目錄寫共通規矩，再喺各個套件嘅 CLAUDE.md 寫局部差異。例如根目錄講工作區指令，apps/api 講 API 測試方式。子目錄文件唔好再抄父層全部內容。

文件太長時，將專題資料拆出去，留下清晰連結或者按官方支援方式引用。唔好靠堆疊粗體同「永遠」「必須」解決互相衝突嘅要求。

接手舊專案，可以先叫 Claude 起草

讀 package.json、鎖定檔、測試設定、主要資料夾同現有開發文件，起草 CLAUDE.md。

每條規矩標明根據邊份檔案觀察到。將「現況」同「你建議改進」分開；冇證據嘅慣例唔好寫成團隊規定。保留草稿畀我逐條核對。

換測試工具、升級框架或者修改建置流程時，就同步改指示檔。一直遵守嘅規矩未必應該刪除；應該刪嘅係過時、重複、含糊或者可以由工具更可靠執行嘅內容。

一份有用嘅 CLAUDE.md 唔需要好長。佢應該令下一次任務少啲猜測，亦令你容易指出「呢度同約定唔一致」。