CLAUDE.md：放在哪裡、寫什麼，以及如何與 AGENTS.md 搭配

CLAUDE.md 是什麼

Claude Code 每次開啟工作階段，都不記得上一次的內容。CLAUDE.md 就是給它新同事需要的背景：啟動時讀取，並在系統提示之後作為一則訊息傳給 Claude。所以它是上下文，而不是強制執行的設定。Claude 通常會遵守，但凡是必須一律執行或絕不能發生的事，應該放進 hooks 或權限規則。

• 就是一般的 markdown，沒有必填欄位：標題加簡短的條列效果最好。
• 檔案是疊加而不是覆蓋：所有適用的 CLAUDE.md 都會載入，所以互相矛盾的內容會讓 Claude 自己挑一條。
• 用 /context all 查看已載入的內容，在 Memory files 底下。

CLAUDE.md 放在哪裡，以及載入順序

Claude Code 依從最廣泛到最具體的順序載入這些檔案，所以離啟動位置最近的檔案最後讀取。它還會從工作目錄往上尋找，載入每一層父目錄裡的 CLAUDE.md。

怎樣寫出真正有用的 CLAUDE.md

1. 從 /init 開始

   在專案裡執行 /init。Claude Code 會讀取程式碼庫並產生一份起始的 CLAUDE.md；如果已經有了，它會提出改進建議而不是直接覆蓋。它也會讀取 .cursorrules 和 Copilot 的指令。

2. 只留下 Claude 自己找不到的內容

   保留準確的建置、測試和 lint 指令（包括如何只跑一個測試）、程式碼裡容易誤導人的地方、沒有寫在任何地方的決定，以及你已經糾正過兩次的事。刪掉檔案樹和 Claude 能從儲存庫讀出來的架構。Anthropic 建議控制在 200 行以內。

   # Commands
   - Install: pnpm install
   - One test file: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Conventions
   - 用 src/lib/errors.ts 裡的 helper 擲出錯誤，不要直接擲字串。
   - src/legacy/ 仍在線上使用，但不要照搬它的寫法。
   
   # Gotchas
   - 整合測試需要 DATABASE_URL（見 .env.example）。

3. 要具體，但別大吼大叫

   寫「使用 2 個空格縮排」，而不是「把程式碼格式化好」。最新文件說，IMPORTANT 和全大寫已經是過時的建議：它們會讓 Claude 過度套用某條規則。如果某一行老是被漏掉，就縮短檔案，或把這條規則改成 hook。

4. 用匯入和規則檔拆分

   @path/to/file 會匯入另一個檔案（相對於匯入它的檔案，最多四層）；放在反引號裡的 @ 維持原樣。只適用於部分程式碼的規則放進 .claude/rules/ 並加上 paths glob，這樣只有 Claude 碰到符合的檔案時才會載入。

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - 每個 handler 都要用 src/api/schemas/ 裡的 schema 驗證輸入。

5. 把流程移到 skill 裡

   多步驟的工作流程，例如怎麼發佈版本，應該放進 skill（.claude/skills/<name>/SKILL.md），只在相關時才載入。CLAUDE.md 每個任務都會讀，所以每一行都在耗費注意力。

6. 保持更新

   當 Claude 重複犯同樣的錯，或是審查發現了問題，就加一行；用 /memory 編輯檔案，或請 Claude 來更新。檔案變得太長時，/doctor 會建議精簡。

來源：Claude Code 文件，How Claude remembers your project

CLAUDE.md 與 AGENTS.md 比較

AGENTS.md 是給程式設計代理的開放指令格式，Codex、Cursor、Gemini CLI、GitHub Copilot 的 coding agent、opencode 等許多工具都在用。Claude Code 現在也會讀取它，但預設只在專案沒有 CLAUDE.md 時才讀。

Claude Code 和 Codex 共用一個檔案

如果團隊兩種代理都用，就把共用的指令放在 AGENTS.md 裡，讓 CLAUDE.md 匯入它，再在下面寫只給 Claude 的備註。它不會被載入兩次。符號連結（ln -s AGENTS.md CLAUDE.md）也可以，但 Windows 上的隊友用不了，而且只用文字寫一句「去讀 AGENTS.md」的 CLAUDE.md 並不可靠。

• 本網站自己的儲存庫就是這麼做的：它的 CLAUDE.md 只有一行 @AGENTS.md。
• Codex 會從儲存庫根目錄一路讀到你的工作目錄裡的 AGENTS.md 檔案，合併後的大小預設上限為 32 KiB。

限制與注意事項

• 啟動時載入的 CLAUDE.md 最多完整讀取 4 MiB；更大的檔案會被略過。
• 依需求載入的檔案，例如子目錄的 CLAUDE.md 和依路徑生效的規則，超過單檔上限就會被截斷（200K 上下文視窗下為 40,000 個字元）。
• 匯入只是整理檔案，並不省上下文：被匯入的文字照樣會載入。
• 專案之外的匯入只需核准一次；HTML 註解 <!-- --> 會被移除，不佔任何成本。
• 執行 /compact 之後，專案根目錄的 CLAUDE.md 會被重新讀取。
• 「記住這個」會進入自動記憶（~/.claude/projects/<project>/memory/），而不是 CLAUDE.md。

CLAUDE.md 說明怎麼做事，Crewmark 決定做什麼、什麼時候做。

好的 CLAUDE.md 能讓每個 Claude Code 工作階段一開始就掌握狀況，但工作階段仍然要等你的下一則訊息。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 工作階段變成有職位、目標和工作時間的 AI 員工，並依心跳喚醒它，從看板上接手下一個 issue。

1. 把工作階段變成員工

   選一個職位，例如軟體工程師或 SEO 專員，把目標寫成一個數字，然後在你的專案裡執行設定指令，你的 CLAUDE.md 本來就在那裡。

2. 讓心跳啟動工作

   在工作時間內，員工每 15、30 或 60 分鐘在同一個對話中醒來一次；參見如何讓 Claude Code 主動工作。多個員工可以共用一個儲存庫，參見多個 Claude Code 代理。

3. 指派 issue，回覆它的訊息

   把工作放到看板上，員工會接手、邊做邊留言，需要你拍板時傳訊息給你。閱讀什麼是 AI 員工。

CLAUDE.md 常見問題