Claude Code系列文3：CLAUDE.md — 教 AI 認識你的專案

發佈留言 / AI工作流程, Claude Code系列文, 科技工具 / 作者:
觀看人次： 11

目錄

新人第一天上班

想像你帶了一個新人進團隊。

他的技術底子很好，演算法刷得多、框架也熟。你給他任務：「幫這個API加一個欄位。」

他打開專案，看到幾十個資料夾、上百個檔案。他不知道這個專案用的是哪種架構。不知道API的格式有一套團隊約定的規範。不知道改完之後要跑哪個測試指令。不知道deploy之前有一個一定要執行的lint檢查。

他花了半天摸索，改完之後跑了npm test，但這個專案的測試指令其實是pnpm run test:api。他提了PR，但commit message格式不對，CI直接擋了下來。

問題不在他的能力。問題在他不認識這個專案。

Claude Code碰到你的專案時，處境完全一樣。

他是一個能力很強的夥伴，但他第一次打開你的repo，對這個專案的慣例、架構、地雷一無所知。每次新對話開始，他都像新人第一天上班。

CLAUDE.md就是你給新人的專案指南。

什麼是CLAUDE.md

CLAUDE.md是一個放在專案根目錄的Markdown檔案。Claude Code每次啟動時會自動讀取。

CLAUDE.md的內容會被注入到每個session的一開始的context中。這意味著CLAUDE.md是每一次Claude Code執行，都一定會參照的內容！

你在CLAUDE.md裡寫的每一條規則，都會影響Claude code在這個專案中的每一個決策：

  • 要不要建立檔案？
  • 函式怎麼命名？
  • 測試怎麼跑？
  • commit message怎麼寫？

一個好的CLAUDE.md的作用是，讓Claude Code從「能力很強但不認識專案的陌生人」變成「熟悉團隊所有慣例的資深同事」，讓產出品質能夠大大增強。

該寫什麼：六個必備區塊

很多人都知道應該要有CLAUDE.md，但不知道該寫什麼。以下是六個你應該涵蓋的核心區塊：

1. 專案概述

告訴Claude Code這個專案是做什麼的，用了什麼技術：

## 專案概述
xxx 是一個餐飲科技平台，提供餐廳管理、訂單處理、會員系統。
- 前端：Next.js 14 (App Router) + TypeScript
- 後端：NestJS + Prisma + PostgreSQL
- 部署：Vercel (前端) + Railway (後端)
- Monorepo：Turborepo 管理

這些內容看起來基本，但非常重要。沒有這些資訊，Claude Code需要花時間掃描你的package.json、tsconfig.json、目錄結構，才能推理拼湊出同樣的理解。

2. 程式碼慣例

你的團隊怎麼命名、怎麼組織檔案、coding style等。

## 程式碼慣例
- 檔案命名：kebab-case（例：user-profile.tsx）
- 元件命名：PascalCase（例：UserProfile）
- API routes放在app/api/下，一個資料夾一個endpoint
- 使用barrel exports（每個資料夾都有index.ts）
- 禁止使用any，必須明確定義型別
- React元件優先使用function declaration，不用arrow function
- 錯誤處理統一使用AppError class

這是影響最直接的區塊。沒有這些內容，Claude Code會用自己預設習慣寫Code。他的預設習慣不差，但與團隊慣例不同，就會造成風格不一致的問題，讓你每次都需要手動修正。

3. 開發工作流程

怎麼安裝依賴、跑dev server、deploy。

## 開發指令
- 安裝依賴：pnpm install
- 啟動開發：pnpm dev（同時啟動前後端）
- 只啟動前端：pnpm dev:web
- 只啟動後端：pnpm dev:api
- 建構：pnpm build
- 資料庫遷移：pnpm db:migrate
- 產生 Prisma client：pnpm db:generate

讓Claude Code不需要再猜你的專案用npm還是pnpm還是yarn。不需要猜dev指令叫什麼。當他需要驗證修改是否正確時，他會直接跑正確的指令。

4. 常見地雷

需要持續維護與優化的區塊。你轉暗裡那些踩過的地雷，都寫在這裡。

## 常見地雷
- 修改Prisma schema後必須執行pnpm db:generate，否則型別不會更新
- 環境變數在Next.js client端必須以NEXT_PUBLIC_開頭
- auth middleware會擋所有/api/admin/*路由，測試時需要mock token
- WebSocket連線在Vercel不支援，即時功能用Server-Sent Events
- 改動shared/下的程式碼會影響前後端，修改前要跑完整測試

Claude Code每次session對話都是新的開始，如果沒有把地雷記錄下來寫在CLAUDE.md裡，他每次都會重新犯相同錯誤。

這個區塊需要隨著專案成長也一起優化到最新狀態。

5. 測試

測試的方式、指令是什麼、怎麼算通過。

## 測試
- 單元測試：Vitest，檔案放在 __tests__/ 下，命名為 *.test.ts
- E2E 測試：Playwright，檔案放在 e2e/ 下
- 跑全部測試：pnpm test
- 跑單一檔案：pnpm test -- path/to/file.test.ts
- 跑E2E：pnpm test:e2e
- 新增API endpoint必須附帶至少一個integration test
- 測試資料庫使用Docker compose裡的test-db service

6. 架構筆記

關鍵的設計決策、重要的抽象層。

## 架構
- 使用 Clean Architecture：domain → application → infrastructure
- domain/ 下的程式碼不能 import 外層的任何東西
- 所有外部服務（支付、寄信、推播）都透過 adapter pattern 抽象
- API response 統一格式：{ success: boolean, data?: T, error?: AppError }
- 認證流程：JWT access token (15min) + refresh token (7d)
- 所有金額以整數（分/cents）儲存，顯示時才轉換

這幫助Claude Code理解系統邊界在哪裡。當他要新增功能時，他會知道應該在哪一層寫邏輯、應該怎麼跟現有系統整合，而不是在錯誤的地方加程式碼。

分層結構

當你的專案規模成長，一個根目錄的CLAUDE.md可能不夠用。Claude Code支援分層結構：

my-project/
├── CLAUDE.md              ← 全專案層級（通用規則）
├── packages/
 │   ├── web/
 │    │         └── CLAUDE.md      ← 前端專屬規則
 │   └── api/
 │              └── CLAUDE.md      ← 後端專屬規則
└── e2e/
           └── CLAUDE.md          ← 測試專屬規則

全專案層級的CLAUDE.md放通用規則——命名慣例、Git workflow、共用指令。

目錄層級的CLAUDE.md放該模組的專屬資訊。

例如前端的packages/web/CLAUDE.md可能包含：

## 前端規範
- 使用 Tailwind CSS，不寫自訂 CSS
- 元件資料夾結構：ComponentName/index.tsx + ComponentName.test.tsx
- 狀態管理：全域用 Zustand，表單用 React Hook Form
- 所有 API 呼叫走 lib/api-client.ts 的 wrapper function
- 圖片使用 next/image，禁止直接用 <img>

只有根木錄的CLAUDE.md檔案會在一開始對話的時候讀取，子目錄底下的CLAUDE.md不會在一開始讀取，只有在需要用到子目錄的檔案時才會讀取，所以拆分出來可以減少每次對話的token數量，避免不必要的浪費，也能讓這些規則更容易維護。

範例：完整的CLAUDE.md

以下提供一份真實專案的完整範例：

# CLAUDE.md

## 專案概述
xxx 是一個餐飲科技 SaaS 平台。
- Monorepo (Turborepo): packages/web (Next.js 14), packages/api (NestJS), packages/shared
- 語言：TypeScript (strict mode)
- 資料庫：PostgreSQL + Prisma ORM
- 認證：JWT (access + refresh token)
- 部署：Vercel (web) + Railway (api)

## 程式碼慣例
- 檔案命名：kebab-case
- 元件命名：PascalCase
- 變數/函式命名：camelCase
- 常數命名：UPPER_SNAKE_CASE
- 禁止 any，使用 unknown + type guard
- 優先用 interface，只在需要 union/intersection 時用 type
- React 元件用 function declaration
- 禁止 default export（除了 Next.js pages）

## 開發指令
- 安裝：pnpm install
- 開發：pnpm dev
- 建構：pnpm build
- 測試：pnpm test
- Lint：pnpm lint
- 型別檢查：pnpm typecheck
- DB 遷移：pnpm db:migrate
- DB seed：pnpm db:seed

## 常見地雷
- Prisma schema 修改後必須跑 pnpm db:generate
- Next.js client component 的環境變數要加 NEXT_PUBLIC_ 前綴
- shared/ 的修改會影響前後端，改完要跑 pnpm test（不是只跑單一 package）
- API rate limiting middleware 在 dev 環境也是開啟的
- 資料庫的金額欄位以 cents 儲存（integer），前端顯示時除以 100

## 測試策略
- 單元測試：Vitest，__tests__/*.test.ts
- E2E：Playwright，e2e/*.spec.ts
- API integration test：supertest，放在各 module 的 __tests__/ 下
- 新 API endpoint 必須有 integration test
- 新 UI 元件必須有基本 render test
- 跑完整測試：pnpm test
- 跑特定檔案：pnpm test -- --filter [package-name]

## 架構
- Clean Architecture：domain → application → infrastructure
- domain/ 不能 import 外層程式碼
- 外部服務用 adapter pattern 抽象（packages/api/src/adapters/）
- API response 格式：{ success, data?, error?, pagination? }
- 錯誤處理：AppError class + global exception filter
- 認證：access token 15min / refresh token 7d / HttpOnly cookie

## Git 慣例
- Commit message 格式：type(scope): description
- type：feat, fix, refactor, test, docs, chore
- Branch 命名：type/brief-description（例：feat/add-order-api）
- 所有 PR 必須通過 CI（lint + typecheck + test）

負面教材

你不需要一開始就寫出完美的CLAUDE.md。他是隨著你專案變大，會著一起成長的東西。

知道該寫什麼之後，也要知道什麼不該寫：

1. 過度冗長

CLAUDE.md的每一個字都佔用context window的token。把它當成給資深工程師看的備忘錄，不是給新手看的教學文件。

不要這樣寫：
我們的專案使用 React 框架，React 是一個由 Meta（前身為 Facebook）開發的
JavaScript 函式庫，用於建構使用者介面。我們選擇 React 是因為它的元件化設計
理念與我們團隊的開發哲學相符，而且社群生態系非常豐富......

應該這樣寫：
前端：React 18 + TypeScript

2. 矛盾的規則

矛盾的規則比沒有規則更糟。Claude Code會困惑，行為變得不可預測。定期檢查CLAUDE.md，確保沒有自相矛盾的地方。

不要這樣寫：
- 使用 arrow function 定義元件
  （然後在另一個段落寫）
- React 元件用 function declaration

3. 過時的資訊

過時的規則會讓Claude Code寫出跟現有程式碼不一致的新程式碼。每次做重大架構變更時，檢查一遍CLAUDE.md。

不要這樣寫：
- 使用pages/目錄的路由系統
  （但你的專案三個月前就遷移到App Router了）

4. 放不相關的內容

CLAUDE.md是「規則和指引」，不是「所有文件的集合」。超過200行就該考慮拆分到目錄層級的CLAUDE.md或其他機制（例如後續章節會介紹的Skills）。

不要放這些：
- 完整的 API 文件（太長，用連結代替）
- 會議記錄或決策歷程
- 所有環境變數的值（安全風險）
- 整段程式碼範例（用檔案路徑引導Claude Code去讀）

文章重點

  1. CLAUDE.md會在一開始的對話中被讀取，大大影響Claude Code的每一個決策
  2. 6個必備區塊：專案概述、程式碼慣例、開發工作流程、常見地雷、測試、架構筆記
  3. 分層結構讓大型專案的規則精確、可維護、省 token
  4. 從簡單開始，根據 AI 的錯誤行為迭代優化——發現重複問題就加規則
  5. 避免4大負面教材：過度冗長、規則矛盾、資訊過時、內容不相關

Related Posts

發佈留言

Subscribe
Subscribe