CLAUDE.md 完整指南：一個 Markdown 檔案如何讓 AI 編碼助手記住你的一切
CLAUDE.md 是 Claude Code 在每次對話開始時自動載入的設定檔，能讓 AI 持續記住你的專案結構、程式碼風格和工作流程偏好。截至 2026 年 5 月，這個機制已從開發者的個人筆記演化為跨團隊協作的基礎設施。與此同時，OpenAI 在 2025 年 8 月推出的 AGENTS.md 已被超過 60,000 個開源專案採用，並在 2025 年 12 月由 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）接管治理。兩套標準的競合關係，正在重塑開發者與 AI 助手互動的方式。
這篇文章拆解 CLAUDE.md 的運作原理、實戰寫法、與 AGENTS.md 的差異，以及 Andrej Karpathy 那份被上萬名開發者下載的行為規則檔到底解決了什麼問題。
CLAUDE.md 是什麼？為什麼它重要
LLM 是無狀態函數。權重在推論時已經凍結，不會隨時間學習。每次打開 Claude Code，它對你的程式碼庫一無所知。CLAUDE.md 就是解決這個問題的檔案。
Anthropic 官方文件的描述很直接：CLAUDE.md 會在每次對話開始時被載入系統提示。你寫進去的專案脈絡、程式碼風格規範、常用指令，Claude 每次啟動都會讀到。不需要額外操作，不需要每次重複解釋。
實際上它做的事情更接近「新人入職手冊」。一位開發者在 HumanLayer 部落格上分享：他用了三個月的 Claude Code，每次都要糾正同樣的錯誤——「不是 npm，我們用 pnpm」、「測試指令是 make test-integration，不是 pytest」。建了一份 40 行的 CLAUDE.md 之後，這些糾正一夜之間消失了。
檔案放置有三個層級，由上往下合併：
| 層級 | 路徑 | 作用範圍 |
|---|---|---|
| 全域 | ~/.claude/CLAUDE.md |
所有專案 |
| 專案根目錄 | ./CLAUDE.md |
當前專案（可 commit 到 git） |
| 子目錄 | ./子目錄/CLAUDE.md |
特定子模組（按需載入） |
還有一個 CLAUDE.local.md 用於個人偏好設定，建議加入 .gitignore，不跟團隊共享。
怎麼寫一份有效的 CLAUDE.md
Anthropic 的最佳實踐頁面給了一個關鍵建議：跑 /init 指令產生初始版本，然後刪掉大部分內容。
這個建議反直覺，但理由充分。/init 會分析你的程式碼庫，偵測建置系統、測試框架和程式碼模式，產出一份相當完整的描述。問題是它會包含很多顯而易見的資訊，例如 TypeScript 專案就寫「這是 TypeScript 專案」，但 Claude 看到 package.json 就知道了。每一行 CLAUDE.md 都在跟你的實際工作搶注意力。
業界共識是控制在 300 行以內。研究顯示前沿 LLM 能可靠遵循大約 150 到 200 條指令，而 Claude Code 的系統提示本身已經占掉約 50 條。超過上限，Claude 就會開始忽略你的規則。
有效的 CLAUDE.md 只需要回答三個問題：
WHAT：這是什麼專案？ 一句話。「Next.js 電商平台，串接 Stripe 和 PostgreSQL」就夠了。
HOW：怎麼跑這個專案？ 精確指令。不是「格式化程式碼」，而是 pnpm lint:fix、make build-docker。Claude 會照抄這些指令執行。
WHY：哪些事情 Claude 會搞錯？ 這才是 CLAUDE.md 的核心價值。把你過去三個月反覆糾正的問題列出來：「我們不用 default export」、「測試檔放在 __tests__ 不是 tests」、「API 回應永遠包 envelope」。
每寫一行，問自己：「拿掉這行，Claude 會犯錯嗎？」如果不會，就刪。
Karpathy 的四條核心規則
2026 年 1 月 26 日，前 Tesla AI 總監、OpenAI 創始成員 Andrej Karpathy 在 X 上發了一串推文，描述他從 80% 手寫程式碼切換到 80% AI 驅動程式碼後遇到的問題。開發者 Forrest Chang 把這些觀察整理成一份 CLAUDE.md 檔案，放在 GitHub 上。這個 repo 被上萬名開發者下載，原因是它用四條原則解決了 AI 編碼最常見的三類失敗模式。
Karpathy 指出的三個問題：
- 無聲假設。模型代替你做假設，然後沿著錯誤方向跑，不質疑、不釐清、不反推。
- 過度複雜化。50 行能解決的事寫 200 行，愛加抽象層、不清理死碼。
- 附帶傷害。改 A 功能時順手動了 B 檔案的註解和程式碼，即使兩者完全無關。
Chang 對應設計的四條原則：
原則一：先想再寫。 不要默默假設。如果需求有多種解讀方式，列出來。如果有更簡單的做法，說出來。需要時主動問，必要時反推。
原則二：保持簡單。 不加未被要求的功能。不對一次性程式碼做抽象。不為極端邊緣情境寫大量防禦性程式碼。
原則三：只改該改的。 變更限制在必要範圍內。不碰不理解的程式碼。不順手「改善」不相關的部分。
原則四：目標驅動執行。 把命令式指令轉成可驗證的目標。「修 bug」變成「寫一個能重現問題的測試，然後讓它通過」。有明確的成功標準，模型才能自主迭代而不需要你每步都介入。
這四條規則的設計邏輯值得注意：它不告訴模型「做什麼」，而是定義「怎麼想」。Karpathy 自己觀察到，LLM 在有明確成功標準的任務上表現最好——給它目標和驗證條件，比給它步驟更有效。
CLAUDE.md vs. AGENTS.md：兩套標準的競合
2025 年 8 月，OpenAI 隨 Codex CLI 推出 AGENTS.md。2025 年 12 月 9 日，Linux Foundation 成立 Agentic AI Foundation（AAIF），Anthropic 捐出 MCP、OpenAI 捐出 AGENTS.md、Block 捐出 Goose。截至 2026 年 4 月，AAIF 已有超過 170 家會員組織。
兩套標準的定位不同：
| 維度 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 發起者 | Anthropic | OpenAI → Linux Foundation AAIF |
| 支援工具 | Claude Code 原生 | Codex CLI、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Aider 等 |
| 治理 | Anthropic 維護 | Linux Foundation 開放治理 |
| 採用規模 | Claude Code 生態系 | 60,000+ 開源專案（至 2025 年 12 月） |
| Fallback 機制 | Claude Code 找不到 CLAUDE.md 時會讀 AGENTS.md | 無反向相容 |
| 格式 | 純 Markdown，無特定結構要求 | 純 Markdown，無特定結構要求 |
實務上最重要的一點：Claude Code 支援 fallback。如果目錄裡沒有 CLAUDE.md 但有 AGENTS.md，Claude Code 會自動讀取 AGENTS.md。這表示團隊如果同時使用多套 AI 工具，維護一份 AGENTS.md 就能覆蓋大部分場景，再用 CLAUDE.md 補充 Claude 專屬的細節。
MCP（Model Context Protocol）是另一塊拼圖。Anthropic 在 2024 年 11 月開源 MCP，到 2026 年 3 月月下載量已超過 9,700 萬次，有超過 10,000 個已發布的 MCP 伺服器。MCP 處理的是工具連接層（讓 AI 存取外部資料和功能），CLAUDE.md / AGENTS.md 處理的是行為指引層（告訴 AI 怎麼在特定專案裡工作）。兩者互補，不互斥。
超越程式碼：非開發者也能用 CLAUDE.md
CLAUDE.md 不限於寫程式的人。任何需要讓 Claude 持續記住脈絡的場景都適用：
寫作者可以鎖定語氣、禁用特定詞彙、指定引用格式。比如：「所有文章用繁體中文台灣用語，不用中港用語。破折號全文最多 3 次。不用否定排比句。」
行銷人可以定義目標受眾、品牌聲音、競品清單。Claude 不會每次都問「你的目標客群是誰」，因為 CLAUDE.md 裡已經寫了。
研究者可以固定輸出結構、引用格式、分析框架。學術引用用 APA 還是 Chicago，寫一次就夠了。
管理者可以把公司背景、團隊結構、專案狀態寫進去。Claude 就像一個已經讀完所有內部文件的新同事。
用 Anthropic 的 Claude Code 產品術語來說，CLAUDE.md 搭配 Skills（.claude/skills/）和 Hooks（.claude/settings.json）形成完整的個人化系統。CLAUDE.md 放的是每次都該知道的全域規則，Skills 放的是特定領域知識（按需載入），Hooks 放的是必須無例外執行的自動化動作。
實戰建議：從今天開始建你的 CLAUDE.md
如果你從來沒建過 CLAUDE.md，以下是最小可行版本的起點：
# 專案概述
[一句話描述你的專案]
# 程式碼風格
- [你最常糾正 Claude 的 2-3 條規則]
# 常用指令
- 測試：[你的測試指令]
- 建置：[你的建置指令]
- 部署：[你的部署指令]
# 不要做的事
- [Claude 最愛犯的 2-3 個錯]
然後隨著使用迭代。每次你糾正 Claude 同一個錯誤兩次，就把那條規則加進 CLAUDE.md。每次你發現 Claude 忽略了某條規則，檢查檔案是不是太長了。
把 CLAUDE.md 當作程式碼來維護：commit 到 git、定期 review、團隊共同貢獻。Anthropic 的文件明確說「這份檔案的價值會隨時間複利成長」。
不只是設定檔，是 AI 時代的工作協議
CLAUDE.md 表面上是一個 Markdown 檔，底層反映的是 AI 輔助工作的核心挑戰：模型沒有記憶，你必須主動管理它的認知。
這跟帶一個新進員工沒什麼不同。差別在於，員工會隨時間學會你的習慣，而 LLM 每次對話都從零開始。CLAUDE.md 就是你寫給這個「永遠的新人」的工作手冊。手冊寫得好，新人第一天就能幹活；寫得差或沒寫，你就得每天花半小時重複解釋同樣的事。
AAIF 的成立、AGENTS.md 的跨工具標準化、Claude Code 的持續迭代，都指向同一個方向：AI 助手的記憶管理正在從個人技巧變成團隊基礎設施。在這個過渡期，最划算的投資就是現在花 30 分鐘寫一份 CLAUDE.md。
CLAUDE.md 需要多長？
Anthropic 建議控制在 300 行以內。研究顯示前沿 LLM 能可靠遵循約 150 到 200 條指令，Claude Code 系統提示已用掉約 50 條。超過上限會導致規則被忽略。每行都問自己：「拿掉這行，Claude 會犯錯嗎？」不會就刪。
Karpathy 的 CLAUDE.md 跟一般版本差在哪裡？
Karpathy 版本聚焦行為原則（怎麼想），一般版本聚焦專案脈絡（知道什麼）。Karpathy 那份由 Forrest Chang 整理的 repo 只有四條原則：先想再寫、保持簡單、只改該改的、目標驅動執行。它設計上是跟專案 CLAUDE.md 合併使用，不是替代。
CLAUDE.md 跟 AGENTS.md 能同時用嗎？
可以。Claude Code 找不到 CLAUDE.md 時會自動讀取 AGENTS.md 作為 fallback。團隊如果同時用多套 AI 工具（Cursor、Copilot、Codex CLI 等），建議維護一份 AGENTS.md 作為通用設定，再用 CLAUDE.md 補充 Claude 專屬規則。
非開發者適合用 CLAUDE.md 嗎？
適合。任何需要讓 Claude 持續記住脈絡的場景都能用：寫作者鎖定語氣和禁用詞彙、行銷人定義受眾和品牌聲音、研究者固定引用格式和分析框架。核心概念一樣：把你反覆跟 Claude 說的事寫下來，讓它自動載入。
CLAUDE.md 要不要 commit 到 git？
Anthropic 建議 commit 到 git，讓團隊共同貢獻。個人偏好用 CLAUDE.local.md 並加入 .gitignore。Hooks 和 Skills 檔案放在 .claude/ 目錄下，也建議跟團隊共享。
引用來源
- Anthropic — Best practices for Claude Code
- Anthropic — Using CLAUDE.md files: Customizing Claude Code for your codebase
- Linux Foundation — Formation of the Agentic AI Foundation (AAIF)
- OpenAI — OpenAI co-founds the Agentic AI Foundation
Author Insight
我們團隊在過去一年多的實務中，最常見的問題不是檔案太短，是太長。有個專案的 CLAUDE.md 寫了 800 行，結果 Claude 幾乎忽略所有規則。我們砍到 120 行之後，遵循率馬上改善。另一個觀察：把 Karpathy 四原則跟專案脈絡分開管理（前者放 Skills，後者放 CLAUDE.md），比全部塞在一個檔案裡效果好很多。AI 工具的能力天花板還在快速拉高，但「怎麼告訴它你要什麼」這件事的投資報酬率，可能是所有 AI 投資裡最高的。
