Chapter 22

CLAUDE.md 深度指南

講義

CLAUDE.md 是 Claude Code 社群中討論度最高的功能之一。它是一個特殊的 Markdown 檔案，讓你可以為 Claude 提供持久化的專案指令、編碼規範和上下文資訊。簡單來說，CLAUDE.md 就是你寫給 AI 的「開發者手冊」。

為什麼 CLAUDE.md 很重要？

每次你啟動一個新的 Claude Code 會話，Claude 都會自動讀取 CLAUDE.md 檔案。這意味著你不需要在每次對話 開頭重複說明專案的架構、命名規範或測試策略。它讓 Claude 從第一條訊息開始就「了解」你的專案。

層級結構

CLAUDE.md 支援三個層級，Claude 會按順序載入所有找到的檔案：

  1. ~/.claude/CLAUDE.md（全域級）：適用於你所有專案的通用偏好，例如「我偏好繁體中文回應」或「使用 ESLint + Prettier」
  2. 專案根目錄 CLAUDE.md（專案級）：專案特定的架構說明、依賴管理和編碼規範
  3. 子目錄 CLAUDE.md（目錄級）：某個子模組或套件的特定規則，例如 packages/api/CLAUDE.md

當多個層級的 CLAUDE.md 同時存在時，Claude 會合併所有內容。子目錄的規則只在你工作於該目錄下的檔案時生效。

應該放什麼內容？

以下是社群驗證過的最佳實踐分類：

  • 編碼規範：命名慣例、import 順序、檔案結構偏好
  • 專案架構：目錄結構說明、核心模組關係圖
  • 測試模式：測試框架選擇、測試命令、覆蓋率要求
  • 常見錯誤提醒：「不要使用 any 型別」、「所有 API 回應都需包裝在 Result 型別中」
  • 建置與部署：建置命令、環境變數說明、部署流程

React/TypeScript 專案範本

# Project: My App

## Architecture
- Frontend: React 18 + TypeScript + Vite
- State: Zustand for global state, React Query for server state
- Styling: Tailwind CSS v4
- Testing: Vitest + React Testing Library

## Coding Conventions
- Use functional components with hooks only
- Prefer named exports over default exports
- File naming: kebab-case for files, PascalCase for components
- IMPORTANT: Always use `const` over `let` unless reassignment is needed

## Testing
- Run tests: `npm run test`
- Run single test: `npx vitest run src/path/to/test.ts`
- YOU MUST run relevant tests before committing changes

## Mistakes to Avoid
- DO NOT use `any` type — use `unknown` and narrow with type guards
- DO NOT import from barrel files (index.ts) in the same package
- DO NOT use inline styles — use Tailwind classes
- DO NOT commit console.log statements

最佳實踐

  • 控制長度：保持在 2000 tokens 以內。過長的 CLAUDE.md 會佔用寶貴的上下文空間
  • 使用強調標記：對關鍵規則使用 IMPORTANT: 或 YOU MUST，這些標記會讓 Claude 更嚴格地遵守
  • 具體而非抽象：寫「使用 Vitest 而非 Jest」而非「使用適當的測試框架」
  • 定期更新：隨著專案演進更新 CLAUDE.md，移除過時的規則

常見錯誤

  • 檔案臃腫：把整個 README 或 API 文檔塞進去。CLAUDE.md 是指令，不是文檔
  • 規則衝突：全域級說「用分號」，專案級說「不用分號」。確保層級間規則一致
  • 放入臨時資訊：「今天的部署版本是 v1.2.3」這類資訊不適合放在 CLAUDE.md 中
  • 忽略 Mistakes to Avoid：社群發現，明確列出「不要做什麼」比只列出「要做什麼」更有效

「Mistakes to Avoid」模式

這是社群最受歡迎的 CLAUDE.md 模式。與其告訴 Claude「如何寫好的代碼」，不如明確列出常見的錯誤。 Claude 對否定指令的遵守度非常高，特別是搭配 DO NOT 或 NEVER 標記時。

建議在每次 Claude 犯錯後，將該錯誤添加到 CLAUDE.md 的 Mistakes to Avoid 區塊中， 這樣它就不會再犯同樣的錯誤。