您的 AI 編碼助手第一次打開您的儲存庫。它掃描檔案結構、依賴項，也許還有一份 README。然後它建議的路由器設定會破壞您現有的佈局系統，匯入您三個衝刺前棄用的套件，並使用您團隊去年放棄的風格編寫測試。助手並不笨——它是盲的。Claude Code、Cursor、Copilot、Cody——每個 AI 結對程式設計師都會遇到同樣的問題：他們無法單獨從提交歷史記錄讀取您的團隊上下文。專案根目錄中的一個 CLAUDE.md 檔案改變了這一切。這是助手與您的慣例對抗和像與您一起工作了數月的資深開發人員一樣擴展它們之間的區別。但大多數團隊編寫的 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. Session context — 您在當前對話中告訴 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 路由（表單提交、webhook）
- `components/` — 共享 UI 元件（原子設計：atoms/、molecules/、organisms/）
- `lib/` — 實用程式函數、API 客戶端、類型定義
- `lib/sanity/` — Sanity 客戶端、查詢 (GROQ) 和類型生成
- `content/` — 部落格文章的 MDX 檔案（與前置資料共置）
- `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 webhook 處理按需重新驗證——不要添加手動重新驗證邏輯。
- 影像優化通過 Sanity 的 CDN (cdn.sanity.io) 進行，不適用於 CMS 內容的 next/image。
- Auth 由 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 架構檔案
- 除非元件確實需要瀏覽器 API 或事件處理器，否則不要使用 `"use client"`
- 不要寫 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

## 架構
App Router 與 RSC。所有資料取得都在伺服器元件中通過 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/ 檔案
- 使用 any 類型

示例：Astro 內容網站

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

# 技術部落格 — Astro

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

## 技術堆疊
Astro 5.x | MDX | Tailwind v4 | 部署到 Cloudflare Pages | Content Collections v2

## 架構
src/content/ — 具有 Zod 驗證的前置資料的 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）
- 不要在沒有更新現有前置資料的情況下修改內容集合架構

破壞您的 AI 上下文的常見錯誤

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

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

CLAUDE.md 與其他 AI 上下文檔案

Claude Code 不是唯一讀取專案上下文檔案的 AI 工具。以下是 2026 年的情況：

檔案 工具 自動讀取 範圍
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 工具（許多在 2026 年都這樣做），請考慮維持單一事實來源，並從中生成工具特定的檔案。簡單的建置指令碼可以將您的主上下文檔案複製到所有正確的位置。

大型專案的高級模式

嵌套 CLAUDE.md 檔案

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

project/
├── 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 上下文加上壓縮摘要

團隊共享與個人上下文

我們將 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 倍改進。

如果您通過我們的無頭 CMS 開發服務與我們一起建立專案，我們會在每個專案交接時包括量身定制的 CLAUDE.md。這對於持續開發速度非常重要。

常見問題

什麼是 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，您需要手動貼上上下文或使用 Projects 功能將其附加為知識檔案。Claude Code 的自動載入是使檔案如此強大的原因——零摩擦，每個會議。