自 2025 年初以來，我每天都在使用 Claude Code，我可以告訴您，獲得有用輸出的單一最大因素不是提示工程或巧妙的技巧。是背景資訊。具體來說，它是位於專案根目錄的編寫良好的 CLAUDE.md 檔案。這一個檔案是 AI 助手與您的程式碼庫對抗和感覺像是在您的團隊中待了幾個月的資深開發人員之間的區別。

如果您一直在向 Claude Code 提示並得到通用、錯誤或令人沮喪的結果，本指南適合您。我將準確說明如何構造您的 CLAUDE.md、要包括什麼、要排除什麼，並分享來自我們在 Social Animal 發布的生產專案的真實範例。

目錄

什麼是 CLAUDE.md 及其重要性

CLAUDE.md 是您放在儲存庫根目錄的 markdown 檔案，Claude Code 在每次開始工作階段時自動讀取。將其視為您的 AI 配對程式設計師的入職文檔。當新的開發人員加入您的團隊時，您不只是遞給他們一台筆記型電腦並說「弄清楚」。您會逐步說明架構、解釋奇怪的部分、指出地雷。CLAUDE.md 對 Claude 做同樣的事情。

沒有它，Claude Code 必須從您的檔案結構、package.json 和碰巧讀取的任何檔案推斷所有內容。這就像要求新員工通過閱讀隨機原始檔案來理解您的整個系統。他們會把一些事情做對，但他們也會做出浪費每個人時間的假設。

有了紮實的 CLAUDE.md，我見過任務完成準確度從大約 60% 躍升至首次嘗試時超過 90%。這不是一個小改進 — 它是 AI 輔助開發成為生產力倍增器和令人沮喪的時間消耗之間的區別。

Claude Code 如何讀取您的專案背景資訊

Claude Code 有一個特定的背景資訊載入階層。理解這一點很重要，因為它會影響您如何組織專案記憶體。

背景資訊載入順序

  1. ~/.claude/CLAUDE.md — 您的全域偏好設定（應用於每個專案）
  2. ./CLAUDE.md — 您儲存庫根目錄的專案層級檔案
  3. ./subdirectory/CLAUDE.md — 目錄特定覆蓋
  4. .claude/settings.json — 專案特定工具權限和設定
  5. 工作階段背景資訊 — 您在目前對話中告訴 Claude 的內容

專案層級的 CLAUDE.md 是您將花費大部分時間的地方。全域檔案對個人偏好很好（「我更喜歡函數式元件」或「始終使用 TypeScript 嚴格模式」），但真正的價值在於每個專案的背景資訊。

這很關鍵：Claude Code 在每個工作階段開始時讀取 CLAUDE.md，但它也有有限的背景資訊視窗空間。如果您的 CLAUDE.md 是 5,000 字的繁瑣文檔，您正在燒用可用於實際程式碼推理的令牌。簡潔明了。具體化。每一行都應該佔據一席之地。

優秀 CLAUDE.md 檔案的剖析

在編寫和優化數十個專案的 CLAUDE.md 檔案後（Next.js 應用程式、Astro 網站、無頭 CMS 整合、API 服務），我已經著陸了一個一致的結構，很有效。

理想結構

# 專案名稱

## 概觀
一段話解釋這個專案做什麼以及誰使用它。

## 技術棧
確切的版本和框架。

## 架構
各個部分如何組合在一起。

## 關鍵慣例
編碼標準、命名模式、檔案組織規則。

## 常見命令
建構、測試、部署和開發命令。

## 重要背景資訊
從程式碼中不明顯的東西。

## 已知問題 / 陷阱
要避免的地雷。

## 不要做的事
AI 應該永遠不做的明確事情。

讓我們深入探討每一部分。

逐節分析

概觀

將其保持在最多 2-3 句。Claude 不需要您的產品路線圖 — 它需要理解領域以便做出適合背景的決定。

## 概觀
這是 Acme Corp 的行銷網站，Acme Corp 是供應鏈管理的 B2B SaaS 平台。該網站通過靜態生成，具有用於表單處理和潛在客戶捕獲的動態 API 路由。內容由行銷團隊透過 Sanity CMS 管理。

技術棧

準確無誤。不要只是說「React」— 指定版本、框架、渲染策略。這防止 Claude 建議在 React 18 中有效但在 React 19 中中斷的模式，或在您使用 App Router 時推薦 Pages Router。

## 技術棧
- **框架**：Next.js 15.1（App Router，預設使用 RSC）
- **語言**：TypeScript 5.7（嚴格模式）
- **樣式**：Tailwind CSS v4 和 CSS 優先配置
- **CMS**：Sanity v3 和實時預覽
- **部署**：Vercel（生產環境和預覽環境）
- **套件管理員**：pnpm 9.x
- **Node**：v22 LTS
- **測試**：Vitest + Playwright
- **狀態管理**：Zustand（最小，僅用於客戶端 UI 狀態）

架構

這是大多數人要麼寫得太少，要麼寫得太多的地方。您不是在寫系統設計文檔。您正在給 Claude 一個心理模型。

## 架構
- `app/` — Next.js App Router 頁面和佈局
- `app/api/` — API 路由（表單提交、網頁鉤子）
- `components/` — 共用 UI 元件（原子設計：atoms/、molecules/、organisms/）
- `lib/` — 實用函數、API 客戶端、類型定義
- `lib/sanity/` — Sanity 客戶端、查詢 (GROQ) 和類型生成
- `content/` — 部落格文章的 MDX 檔案（與 frontmatter 一起存放）
- `public/` — 靜態資產（優先對所有圖像使用 next/image）

資料流：Sanity CMS → lib/sanity/queries.ts 中的 GROQ 查詢 → 伺服器元件 → 客戶端元件（僅在需要互動性時）

除了 /blog/[slug]/preview 使用草稿模式外，所有頁面都在建構時靜態生成。

關鍵慣例

這個部分節省了最多時間。沒有它，Claude 將遵循可能與您團隊選擇衝突的一般最佳實踐。

## 關鍵慣例
- 元件命名為 PascalCase，每個檔案一個元件
- 使用命名匯出，永遠不使用預設匯出（除頁面/佈局外）
- 所有資料擷取都在伺服器元件中發生 — 永遠不要使用 useEffect 進行資料擷取
- API 響應類型存在於 lib/types/ 中，並從 Sanity 架構自動生成
- 使用 `cn()` 實用程式（lib/utils.ts）進行條件式類別合併，而不是模板字面值
- 錯誤邊界包裝每個主要頁面部分，而不是整個頁面
- 所有表單處理使用 react-hook-form + zod 驗證架構
- 提交訊息遵循傳統提交（feat:、fix:、chore:）

常見命令

這看起來很基礎，但 Claude Code 實際上運行這些命令。如果它不知道正確的命令，它會猜測，並且經常猜測錯誤。

## 常見命令
- `pnpm dev` — 啟動開發伺服器（連接埠 3000）
- `pnpm build` — 生產建構
- `pnpm lint` — ESLint + Prettier 檢查
- `pnpm test` — 執行 Vitest 單元測試
- `pnpm test:e2e` — 執行 Playwright E2E 測試
- `pnpm sanity:typegen` — 在架構變更後重新生成 Sanity 類型
- `pnpm db:migrate` — 執行 Drizzle ORM 遷移

重要背景資訊

這是 Claude 無法透過讀取程式碼弄清楚的東西。業務邏輯、外部約束、人類審核者需要 30 分鐘才能解釋的事情。

## 重要背景資訊
- 我們為所有 CMS 頁面使用 ISR (revalidate: 3600)。除非絕對必要，否則永遠不要使用 `force-dynamic`。
- /api/revalidate 上的 Sanity 網頁鉤子處理隨需重新驗證 — 不要添加手動重新驗證邏輯。
- 圖像最佳化透過 Sanity 的 CDN (cdn.sanity.io) 進行，而不是用於 CMS 內容的 next/image。
- 驗證由 Clerk 處理 — 永遠不要建構自訂驗證流程。
- /api/leads 端點通過 Upstash Redis 有速率限制。不要移除速率限制中介軟體。

已知陷阱

每個專案都有奇怪的東西。將其放在這裡，以便 Claude 不會被絆倒。

## 已知陷阱
- Sanity 的便攜式文字渲染器在 v3.2 中有嵌套清單的錯誤。我們在 components/portable-text/list-fix.tsx 中使用自訂序列化器
- Tailwind v4 不支援模組 CSS 檔案中的 `@apply` 指令 — 改用內聯類別
- vercel.json 對 /docs/* 的覆蓋代理到我們的 Mintlify 文檔網站。不要在檢查團隊前修改這些。
- 環境變數前綴為 NEXT_PUBLIC_ 的是僅可用於客戶端的變數。永遠不要以這種方式公開 API 密鑰。

「不要做的事」部分

這可能是最重要的部分。負面指示對 AI 模型非常有效。

## 不要做的事
- 不要在沒有先提問的情況下安裝新依賴項
- 不要使用 `any` 類型 — 查找或建立適當的類型
- 不要為可以在伺服器元件中完成的事情建立新 API 路由
- 不要在未確認遷移計劃的情況下修改 Sanity 架構檔案
- 不要使用 `"use client"` 除非元件確實需要瀏覽器 API 或事件處理程式
- 不要寫 CSS 檔案 — 一切都是 Tailwind 實用程式類別
- 不要將應該來自 CMS 的字串硬編碼

真實 CLAUDE.md 範例

範例：Next.js 行銷網站

這是 CLAUDE.md 簡化版本，我們在客戶專案中使用，特別是在建立帶有無頭 CMS 後端的 Next.js 網站時。

# Acme 行銷網站

## 概觀
Acme (acme.com) 的行銷網站。透過 Next.js 15 建構，使用 Tailwind v4 設計樣式，Sanity CMS 提供內容。目標：所有頁面上的 LCP 少於 2 秒。

## 技術棧
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## 架構
使用 RSC 的 App Router。所有資料擷取都在伺服器元件中透過 lib/sanity/queries.ts 中的 GROQ 查詢進行。客戶端元件僅用於互動式元素（模式、表單、輪播）。

頁面：/ (首頁)、/about、/pricing、/blog、/blog/[slug]、/contact

## 慣例
- 僅命名匯出（除 page.tsx/layout.tsx 外）
- 元件：PascalCase，每個檔案一個
- 用於類別合併的 cn()
- 所有表單驗證的 Zod 架構
- 不要將 useEffect 用於資料擷取。永遠。

## 命令
pnpm dev | pnpm build | pnpm lint | pnpm test

## 不要做的事
- 不正當化就添加「use client」
- 安裝套件但沒有先詢問
- 為元件使用預設匯出
- 在未確認遷移的情況下修改 sanity/schema/ 檔案
- 使用任何類型

範例：Astro 內容網站

對於 Astro 專案，CLAUDE.md 看起來有點不同，因為架構典範不同。

# 科技部落格 — Astro

## 概觀
有超過 500 篇文章的開發人員部落格。靜態優先，預設為零 JS。用於內容的 MDX 和自訂元件。

## 技術棧
Astro 5.x | MDX | Tailwind v4 | 部署到 Cloudflare Pages | 內容集合 v2

## 架構
src/content/ — 帶有 Zod 驗證 frontmatter 的 MDX 文章
src/components/ — Astro 元件（零 JS）和 React 島嶼（互動式）
src/layouts/ — 基礎佈局
src/pages/ — 基於檔案的路由

## 關鍵規則
- 預設使用 Astro 元件 (.astro)。僅對需要互動性的島嶼使用 React。
- client:visible 用於視口下方互動式元件
- client:idle 用於非關鍵互動式元件
- 除非絕對必要，否則永遠不要使用 client:load
- 所有圖像使用 Astro 的 Image 元件，具有適當的寬度/高度
- RSS 提要從內容集合自動生成 — 不要建構手動提要邏輯

## 不要做的事
- 在 Astro 元件能做時添加 React 元件
- 使用 client:load 指令
- 略過圖像尺寸（造成 CLS）
- 在未更新現有 frontmatter 的情況下修改內容集合架構

破壞 AI 背景資訊的常見錯誤

到目前為止，我已經審查了很多 CLAUDE.md 檔案。以下是一致導致不良結果的模式。

錯誤 為什麼傷害 修復
太長（2000+ 字） 燒用背景資訊視窗令牌，關鍵資訊遺失 保持在 800 字以下。連結到外部文檔進行深入探討。
太模糊（「我們使用 React」） Claude 用假設填補空白 明確：版本、模式、確切的工具
沒有負面指示 Claude 做「合理」的事破壞您的慣例 始終包含「不要做的事」部分
複製貼上 README.md README 適合人類，不適合 AI 背景資訊 從頭開始用 AI 特定的組框寫 CLAUDE.md
包括敏感資料 背景資訊檔案中的 API 金鑰、密鑰 永遠不要將密鑰放在 CLAUDE.md 中。改為參考 .env.example。
從不更新它 專案演進，背景資訊檔案不演進 每個衝刺或主要重構時檢查一次 CLAUDE.md
矛盾的指示 「使用伺服器元件」+ useEffect 擷取的範例 讓一個人擁有檔案，檢查一致性

CLAUDE.md 與其他 AI 背景資訊檔案

Claude Code 不是唯一讀取專案背景資訊檔案的 AI 工具。以下是 2025 年的景觀：

檔案 工具 自動讀取 範圍
CLAUDE.md Claude Code 是，在工作階段開始時 專案範圍
.cursorrules Cursor 是，在檔案開啟時 專案範圍
.github/copilot-instructions.md GitHub Copilot 是，在 Copilot Chat 中 儲存庫範圍
.windsurfrules Windsurf (Codeium) 是 專案範圍
AGENTS.md OpenAI Codex CLI 是 專案範圍
.ai/context.md 自訂慣例 否（手動參考） 變化

好消息：大多數內容是可轉移的。如果您編寫紮實的 CLAUDE.md，將其轉換為 .cursorrules 或 copilot-instructions.md 需要約 5 分鐘。結構和資訊相同 — 僅檔案名稱和次要格式不同。

如果您的團隊使用多個 AI 工具（2025 年有很多這樣做），請考慮維護單個事實來源，並從中生成工具特定的檔案。簡單的建構指令可以將您的主要背景資訊檔案複製到所有正確位置。

大型專案的進階模式

嵌套 CLAUDE.md 檔案

對於 monorepo 或大型程式碼庫，您可以在子目錄中放置 CLAUDE.md 檔案。Claude Code 將讀取您正在操作的目錄最具體的。

專案/
├── CLAUDE.md              # 全域專案背景資訊
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web 應用程式特定背景資訊
│   └── api/
│       └── CLAUDE.md      # API 特定背景資訊
├── packages/
│   └── ui/
│       └── CLAUDE.md      # 設計系統背景資訊

根 CLAUDE.md 涵蓋共用架構和慣例。每個嵌套檔案為該套件添加具體內容。

使用 /compact 的動態背景資訊

Claude Code 的 /compact 命令會總結目前對話並釋放背景資訊空間。對於長工作階段，我發現了一個有效的模式：

  1. 從自動載入的 CLAUDE.md 開始
  2. 在功能上工作
  3. 當背景資訊變重時執行 /compact
  4. 繼續 — Claude 保留 CLAUDE.md 背景資訊加上壓縮的摘要

團隊共用 vs 個人背景資訊

我們將 CLAUDE.md 保留在版本控制中（應該提交）。但個別開發人員也使用 ~/.claude/CLAUDE.md 進行個人偏好：

# 個人偏好設定
- 我更喜歡詳細的變數名稱而不是縮寫
- 在寫程式碼前向我展示理由
- 建議變更時，顯示完整檔案差異
- 我使用具有 Vim 鍵盤繫結的 VS Code（不要建議 IDE 特定的快速鍵）

這種分離使團隊檔案保持乾淨和專注於專案事實，同時讓個人自訂其體驗。

衡量影響

您怎麼知道您的 CLAUDE.md 是否有效？以下是我們內部追蹤的指標：

  • 首次嘗試準確度：Claude 的第一個響應需要零修正的頻率如何？一個好的 CLAUDE.md 將這個数字提高到 80% 以上。
  • 慣例違規：計算 Claude 違反編碼標準的次數。應該趨向於零。
  • 背景資訊問題：如果 Claude 一直在詢問「這是什麼框架?」或「我應該使用 App Router 嗎?」，您的 CLAUDE.md 遺漏資訊。
  • 撤銷頻率：您必須拒絕或還原 Claude 變更的頻率。越低越好。

一個中型初創公司的一支團隊報告說，在投資一小時在他們的 CLAUDE.md 後，他們的平均 AI 輔助任務時間從 12 分鐘縮短到 4 分鐘。這是一個檔案帶來 3 倍的改進。

常見問題

什麼是 CLAUDE.md 以及它放在哪裡？ CLAUDE.md 是放在專案儲存庫根目錄的 markdown 檔案。Claude Code 在每個工作階段開始時自動讀取它，以了解您的專案的架構、慣例、技術棧和約束。將其視為專門為您的 AI 編碼助手編寫的入職文檔。

CLAUDE.md 檔案應該有多長？ 目標是 300-800 字。較短的檔案遺漏關鍵背景資訊，但超過 1,000 字的任何內容開始進入您的背景資訊視窗 — 最好用於實際程式碼推理的空間。簡潔而具體。每句話都應該佔據一席之地。如果您需要更多深度，請連結到外部文檔而不是嵌入它。

我應該將 CLAUDE.md 提交到版本控制中嗎？ 絕對地。CLAUDE.md 應該被視為任何其他專案文檔 — 版本化、審查和保持最新。您的整個團隊都受益於一致的 AI 行為。個人偏好改為進入 ~/.claude/CLAUDE.md，它保留在每個開發人員的機器本地。

CLAUDE.md 與 .cursorrules 有什麼不同？ 內容幾乎相同 — 兩者都為 AI 編碼工具提供專案背景資訊。區別在於哪個工具讀取它們。CLAUDE.md 適用於 Claude Code (Anthropic 的 CLI 工具)，而 .cursorrules 適用於 Cursor IDE。如果您同時使用兩個工具，請維護一個事實來源並複製到兩個檔案，調整任何工具特定的格式。

CLAUDE.md 的最重要部分是什麼？ 「不要做的事」部分。負面指示對 AI 模型非常有效。告訴 Claude 要避免什麼 — 不要使用 any 類型、不要不必要地添加「use client」、不要在沒有詢問的情況下安裝新套件 — 防止最常見和令人沮喪的錯誤。一個好的禁令清單節省的時間比頁面積極指示還要多。

我可以將 CLAUDE.md 用於非編碼專案嗎？ 是的。CLAUDE.md 適用於任何與 Claude Code 互動的專案。我見過有效的文檔儲存庫、基礎設施即程式碼專案，甚至資料分析管道。原則相同：給 Claude 它需要的背景資訊以對您的特定專案做出良好決定。

我應該多久更新一次 CLAUDE.md？ 在每個主要重構時檢查它，至少每個衝刺一次。如果您升級框架版本、變更關鍵依賴項或採用新慣例，請立即更新檔案。陳舊的背景資訊比沒有背景資訊更糟，因為它主動誤導 AI。有些團隊將 CLAUDE.md 審查添加到基礎設施變更的 PR 檢查清單中。

CLAUDE.md 是否適用於網頁上的 Claude (claude.ai)？ 否。CLAUDE.md 專門由 Claude Code（基於 CLI 的編碼工具）讀取。如果您透過網頁介面或 API 使用 Claude，您需要手動貼上背景資訊或使用「專案」功能將其作為知識檔案附加。Claude Code 的自動載入是使該檔案如此強大的原因 — 零摩擦力、每個工作階段。