Shashank Trivedi

當在專案中設定 Claude Code（或由 Claude 驅動的 AI 程式碼助理）時，有效率地組織指令是獲得精準程式碼生成並同時降低 token 消耗的關鍵。

了解何時使用單一的 CLAUDE.md，以及模組化的 .claude/rules/ 檔案，將有助於讓你的 AI 助理保持敏銳、專注且可預測。

核心階層與範圍

Claude Code 會在多個層級中尋找設定：

├── ~/.claude/                      # 使用者 / 全域層級（適用於所有專案）
└── project-root/
    ├── CLAUDE.md                   # 專案全域層級（載入每個工作階段）
    ├── .claude/rules/              # 模組化與範圍限定規則（選擇性載入）
    └── sub-app/
        └── CLAUDE.md               # 子目錄 / Monorepo 範圍

進入全螢幕模式 離開全螢幕模式

  1. CLAUDE.md（全域速查表）請將 CLAUDE.md 視為 AI 的主要 ReadMe。它提供高層級的脈絡與必要的專案記憶體。使用 CLAUDE.md 的時機：常用 CLI 指令：建置、測試、lint 及執行指令碼（npm test、docker compose up）。核心架構：技術堆疊摘要、整體資料夾結構及設計原則。全域規則：適用於整個專案且不可違背的指南（例如「嚴格使用 TypeScript，禁止使用 any」）。

專案脈絡：電子商務 Web App

建置與測試指令

  • 建置：npm run build
  • 測試單一檔案：npx jest src/components/Button.test.tsx
  • Lint：npm run lint

高層級指南

  • 所有 UI 元件都必須使用 React 19 的函式語法。
  • 切勿硬編碼密鑰或環境變數。
  1. .claude/rules/（模組化與路徑範圍規則）隨著專案規模成長，將所有指南塞進 CLAUDE.md 會使提示上下文過於龐大，並降低整體遵循度。 .claude/rules/ 目錄讓你能夠建立模組化、特定主題或路徑範圍的規則（使用 .yml 或 .md 格式）。使用 .claude/rules/ 的時機：路徑特定規則（globs）：僅適用於特定檔案的指南（例如 API 路由 vs. React 元件）。領域區隔：將規則拆分到專用檔案（testing.yml、security.yml、db-migrations.yml）。Token 最佳化：編輯 CSS/React 元件時，避免將後端遷移規則載入上下文。

.claude/rules/api-routes.yml

name: API & Endpoint Rules
globs:

  • "src/api/*/.ts"
  • "src/controllers/*/.ts"

rules:

  • id: input-validation description: 使用 Zod 結構描述驗證所有傳入的 payload。
  • id: error-handling description: 切勿在 API 回應中暴露內部 DB 錯誤追蹤。

專業提示與最佳實踐

  • 保持 CLAUDE.md 簡潔：目標控制在 100–150 行以內。將特定領域的細節移至 .claude/rules/。
  • 結合兩種策略：將指令與核心支柱放在 CLAUDE.md[cite: 1]。將框架/目錄特定內容放在 .claude/rules/[cite: 1]。
  • 在 Monorepo 中使用子目錄 CLAUDE.md：在特定 package/app 內放置本地化的 CLAUDE.md 檔案（例如 apps/web/CLAUDE.md 及 services/auth/CLAUDE.md），讓子團隊維護隔離的上下文[cite: 1]。