CLAUDE.md 寫得啱：Claude Code 自動跟你 project 規矩，唔再次次解釋

情境

你用咗 Claude Code 兩個禮拜，跑得幾順。但有個規律一直令人煩躁：

• 你叫佢加個 component → 佢用 camelCase 命名，但你 project 全部係 PascalCase
• 你叫佢修 bug → 佢 import 一個已棄用嘅 package，你頭先先至搬走嗰個
• 你叫佢加 test → 佢用 Jest，但你個 project 已經轉咗 Vitest
• 每次 session 開頭你都要打：「呢個 project 用 X、唔好用 Y、commit format 要 Z⋯」

呢啲磨擦嘅根源：Claude 唔知你 project 個背景。每次新 session 等於同一個新入職同事傾偈，由零開始帶佢上手。

解法叫 CLAUDE.md —— 放喺 project root 嘅一個 markdown file，Claude Code 自動讀入做 session context。

但好多人寫 CLAUDE.md 寫到似 README：「我哋係 Next.js 15 project、用 Tailwind、部署喺 Vercel⋯」。Claude 對呢類資訊興趣有限。佢真正受惠係命名規矩、指令、禁止用法、project 獨有嘅陷阱 —— 即係你會花時間口頭解釋畀新人嘅嘢。

呢篇用呢個 project（《我的好朋友 Claude》）本身嘅 CLAUDE.md 做實例示範，教你 30 分鐘寫一份真係用得嘅版本。

跟住做

1. CLAUDE.md 嘅四個必備 section（5 分鐘）

一份合格嘅 CLAUDE.md 至少要有：

1. Stack — 一句講晒。唔使賣廣告，淨係畀 Claude 對齊版本同 framework 嘅慣用寫法。
2. Commands — dev、build、test、typecheck、lint。每條附一句「幾時要跑」。
3. File / Code Conventions — 命名規矩、folder 結構、import 風格。呢度係最有價值嘅 section。
4. Gotchas / Forbidden Patterns — 你曾經炸過 prod 嘅教訓、framework 怪癖、唔可以破壞嘅設計規矩。

呢四個 section 加埋通常 50–100 行夠用。唔好寫到 500 行 —— Claude context window 寶貴，每個 token 都要值錢。

2. Section by section 寫法 + 例子（15 分鐘）

開個 CLAUDE.md 喺你 project root，跟住寫：

Stack（1–2 行，唔好長氣）：

## Stack

Next.js 15 (App Router) + TypeScript (strict) + MDX + Velite + Tailwind v4 + Pagefind + Vercel。純內容站、無 DB、無 auth。

最後嗰句「純內容站、無 DB、無 auth」最值錢 —— Claude 唔會建議你加 Prisma 或 NextAuth。

Commands（每條一句解釋）：

## Commands

- `pnpm dev` — Start dev server (parallel: velite --watch + next dev)
- `pnpm build` — Full build: velite → next build → pagefind index
- `pnpm typecheck` — TypeScript strict check, 改完 schema 要跑

「改完 schema 要跑」呢類提示令 Claude 識主動行 typecheck。

Conventions（具體例子）：

## File Conventions

- Components: PascalCase（`Masthead.tsx`、`UseCaseCard.tsx`）
- Lib utilities: camelCase（`formatMastheadDate`、`getAllUseCases`）
- MDX use cases: kebab-case slug（`tsa-homework-helper.mdx`）

永遠帶實例 file name，唔好淨講「PascalCase」就算 —— Claude 對名係 pattern matcher。

Gotchas（解釋「點解」）：

## MDX Gotchas

- **`{...}` 喺 MDX 入面係 JSX expression**，prerender 會試評估佢做 JS。
  寫 placeholder 用 `[xxx]` 或 `「xxx」`，唔好用 `{xxx}`，否則
  build 會死喺 `ReferenceError: xxx is not defined`。

呢條陷阱救咗我至少 3 次 build。唔講「點解」嘅規矩 Claude 會犯，因為佢推理唔到約束背後嘅原因。

3. 驗收：畀一個任務睇佢跟唔跟（5 分鐘）

寫完即刻測試。開新 Claude Code session，畀一個會踩晒你規矩嘅任務：

加一個新 page 叫「Issue archive」，列出歷史所有期數。

睇佢：

• File name 啱唔啱（IssueArchive.tsx 定係 issue-archive.tsx？）
• Import 路徑跟唔跟 project 別名
• 有冇用禁止寫法（漸變？圓角太大？寫死顏色？）
• 改完有冇主動 pnpm typecheck

每個唔啱嘅地方 = CLAUDE.md 入面缺一條 rule。審視一次補一次，2–3 個週期之後就準晒。

4. 每月調整一次（5 分鐘）

CLAUDE.md 唔係寫完就放低。每個月睇一次：

• 過去 30 日邊條指示我講過 3 次以上？→ 抽返入 CLAUDE.md
• 邊條規矩 Claude 一直跟得啱？→ 可以刪走
• Stack 有冇升級？dependency 有冇換？

我自己嘅習慣：每次 pnpm install 加新 dep，順手諗一句「Claude 需唔需要知？」需要就加一行。

變化

變化 1：Monorepo — root + sub-package 兩層

如果你係 monorepo（apps/web、apps/api、packages/ui），用兩層 CLAUDE.md：

• Root CLAUDE.md — 講 monorepo 結構、workspace tool（pnpm / turbo）、跨 package commands、shared conventions
• 每個 package 一份 — 只寫嗰個 package 特有嘅怪癖（例如 apps/api/CLAUDE.md 講 Prisma schema migration 流程）

Claude Code 喺 sub-folder 跑會自動讀兩層。記住：子層唔好重覆父層 —— 只寫差異。

變化 2：Team CLAUDE.md — 人類 + AI 都讀

你 team 可能淨係一兩個人用 Claude Code，其他人用 VS Code。寫一份兩邊都用得到嘅版本：

# Conventions（呢份 doc 人類 + Claude Code 都會 read）

## Code style
- 函數 < 50 行、文件 < 400 行
- 永遠 immutable update，唔好 mutate

效果：人類上手快咗、AI 一致咗。你會發現 「寫畀 AI 嘅文檔」其實同「寫畀新人嘅文檔」幾乎一樣。

變化 3：接手 legacy codebase — 用 Claude 幫你寫 CLAUDE.md

接手一個你唔熟嘅程式庫？倒轉用 Claude：

你 read 過呢個 repo 嘅 package.json、tsconfig、src/ folder 結構，
幫我起草一份 CLAUDE.md：
1. Stack（一句）
2. Commands（從 package.json scripts 抽）
3. 你觀察到嘅 file naming conventions
4. 你發現嘅禁止用法或怪癖

我會 review + 改 + commit。

Claude 出嘅草稿通常 70% 啱、30% 估錯。你逐條核對一次，半個鐘有得交。比起人手由零寫快 5 倍。

拆解：點解 work，同邊度會仆街

跟到上面就已經用得。下面呢段係畀想由「跑一次驗收 OK」做到「日日用都唔失控」嘅人——初學者可以跳過，唔影響你跟住做。

CLAUDE.md 最唔老實嘅地方係：你寫得越多，Claude 跟得越唔齊。佢唔係一條條 if-else，而係連你成個 codebase 一齊塞落 context 度做提示。下面呢幾個位，係 demo 順、但日日用就會浮出嚟嘅陷阱，你要預咗：

1. 寫到 500 行，反而冇條 rule 跟得實 你越補越多 rule，份 CLAUDE.md 由 80 行脹到 400 行。Claude 唔會「逐條對」，佢係喺成段 context 度抽重點，rule 一多就稀釋，重要嗰幾條反而沉底。

• 會爆成點：你明明寫咗「唔好用漸變」，佢照用；你問返佢，佢答得出條 rule，但啱啱嗰下冇跟。
• 點救：分層。最 critical 嘅禁令（炸過 prod 嗰啲）擺前面、用粗體；次要嘅 nice-to-have 拆去 sub-folder 嘅 CLAUDE.md 或 slash command。寧願短而硬，唔好長而軟。

2. 規矩之間打架，Claude 揀錯邊 你某個位寫「全部 PascalCase」，另一個位又寫「test file 用 kebab-case」，再 import 一份 team doc 又有第三套講法。Claude 撞到衝突唔會停低問你，佢會自己估一個。

• 會爆成點：佢揀咗其中一套照做，你 review 先發現同你心目中嗰套唔同。
• 點救：自己讀一次成份 doc 搵矛盾；每條 rule 寫清楚適用範圍（「component file」定「所有 file」）。一個 project 一套真理，唔好兩個 section 各講各。

3. 你改咗 stack，但 CLAUDE.md 仲停喺上個月 篇文教你「每月調整」，但現實係你轉咗 Vitest、搬走咗個 deprecated package，份 doc 冇跟住改。Claude 照住份過時嘅 doc 做，比你乜都唔寫仲衰——因為佢會好有信心咁做錯。

• 會爆成點：佢「跟足 CLAUDE.md」去 import 你已經刪咗嘅 package，或者用返你已經淘汰嗰套 test framework。
• 點救：當 CLAUDE.md 係 code 嘅一部分。換 dep、改 convention 嗰個 commit，順手改埋 CLAUDE.md；過時嘅 rule 比冇 rule 更危險，定期清。

4. 寫死咗 secret 或內部資料落去 CLAUDE.md 通常會 commit 入 repo。有人為咗「畀 Claude 方便」，順手貼咗 staging 嘅 connection string、內部 URL、甚至 token 落去。

• 會爆成點：一個本應低調嘅 config file，連你啲 secret 一齊入咗 git 歷史，public repo 就更大鑊。
• 點救：CLAUDE.md 只放「點做」唔放「鎖匙」。要講環境變數就講名（例如「set DATABASE_URL」），唔好貼真值；commit 前當佢同其他 source code 一樣過一次 secret 檢查。

5. 抄人哋一份「萬用 CLAUDE.md」落自己 project 網上有好多現成範本，貼落嚟好快。但別人嗰套 convention、禁令、commands 同你個 project 唔對位，Claude 就會照住一份同你 codebase 唔 match 嘅指示做。

• 會爆成點：佢叫你跑一條你根本冇嘅 script、跟一套你 project 唔用嘅命名，同你個 codebase 越偏越遠。
• 點救：範本當靈感，唔好當答案。每條 rule 問返自己「呢個係咪我呢個 project 真係咁做」，唔啱就刪。短而真，好過長而抄。

呢幾個位，就係「跑一次驗收 OK」同「日日用都信得過」之間嘅距離。

一個心態

CLAUDE.md 嘅回報唔係寫嗰陣感覺到 —— 係寫完之後每一個 session 都慳返 5 分鐘解釋時間。

最大嘅心理障礙：你會覺得「呢啲嘢咁明顯，駛唔駛寫」。答案：要。對你明顯，因為你日日睇住個 codebase。對 Claude 每個新 session 都係第一次。

寫 CLAUDE.md 同寫入職指南同一個道理。分別係：

• 寫畀新人入職指南：1 年用 2 次（每次有新同事入職）
• 寫畀 Claude 嘅 CLAUDE.md：每日用幾十次

回報率懸殊到唔成比例。今晚抽 30 分鐘寫一版、跑一次驗收、commit。下個禮拜你會感覺到 Claude Code「終於變乖咗」。