CLAUDE.md 是 Claude Code 專案裡最值得先建立的檔案。它的作用很像「給 AI 的專案說明書」：告訴 Claude Code 這個專案怎麼跑、用什麼技術、哪些檔案不能亂動、改完要跑哪些測試、文章或程式要遵守什麼風格。
如果你剛安裝 Claude Code，第一件事不是叫它重構專案，而是先執行 /init，讓它產生 CLAUDE.md，再把規則慢慢補齊。這會直接影響後續每一次 AI 協作的品質。
CLAUDE.md 是什麼？
CLAUDE.md 是 Claude Code 會在 session 開始時讀取的專案指令檔。官方文件把它視為 always-on context，也就是每次 Claude Code 進入這個專案時，都會先看這些規則。
- 專案啟動方式。
- 測試、lint、build 指令。
- 架構和命名規則。
- 不要修改的檔案或目錄。
- 部署、安全、資料庫操作限制。
- 內容語氣、語言、SEO 或文件格式規範。
為什麼 CLAUDE.md 很重要？
沒有 CLAUDE.md 的 Claude Code，就像剛加入專案的新同事。它可能很聰明，但不知道你的團隊習慣、專案禁忌和驗證流程。你每次都要重新提醒它，久了很浪費。
把固定規則寫進 CLAUDE.md 後，Claude Code 會更容易做出一致的決策。例如你不希望它直接改正式資料庫、不希望它把 Gutenberg block 轉成 Classic Block、不希望它在沒跑測試前說完成，這些都可以寫進去。
如何建立 CLAUDE.md？
在專案根目錄執行：
claude
/initClaude Code 會掃描專案並產生初版。產生後不要直接放著，建議你手動補這幾段。
推薦 CLAUDE.md 範本
# Project Instructions
## Project Overview
- This is a WordPress automation and content workflow project.
- Use Traditional Chinese for user-facing content.
## Commands
- Run tests with: pytest
- Search files with: rg
- Verify WordPress output with orca-wp get <id> --json
## Editing Rules
- Keep changes scoped to the requested task.
- Preserve Gutenberg block comments in WordPress HTML.
- Do not rewrite unrelated files.
## Safety
- Never run destructive database commands without confirmation.
- Never deploy or publish unless explicitly requested.
- Always report which commands were used for verification.這只是起點。真正好用的 CLAUDE.md，會隨著專案累積。當 Claude Code 第二次犯同樣錯誤，就把規則寫進去；當你第三次貼同一段操作流程，就把它整理成 skill 或文件。
CLAUDE.md、Skills、MCP 有什麼差別？
| 工具 | 用途 | 適合放什麼 |
|---|---|---|
| CLAUDE.md | 每次都要讀的專案規則 | 測試指令、禁忌、專案慣例 |
| Skills | 需要時才載入的工作流程 | 發布流程、review checklist、API 文件 |
| MCP | 連接外部工具和資料 | GitHub、資料庫、Google Drive、瀏覽器 |
官方文件也建議不要把所有東西都塞進 CLAUDE.md。永遠要用的規則放 CLAUDE.md；很長的流程放 Skills；需要外部工具能力就用 MCP。這樣 context 比較乾淨，Claude Code 也比較不會被資訊淹沒。
常見錯誤：把 CLAUDE.md 寫成流水帳
CLAUDE.md 不是公司 wiki，也不是全部文件的垃圾桶。寫太長會讓 Claude Code 每次都載入大量無關資訊。官方文件建議保持精簡，把 reference material 移到 skills 這類按需載入的地方。
- 不要貼完整 API 文件。
- 不要貼長篇會議紀錄。
- 不要把一次性任務寫成永久規則。
- 不要放會快速過期的帳密、token、客戶資料。
我的建議寫法
我會把 CLAUDE.md 當成「AI 協作底線」，而不是完整操作手冊。它只需要回答三件事：這個專案怎麼做、什麼不能做、做完怎麼驗證。其他像 SEO 發文流程、WordPress ACF 匯入、GitHub PR review，就更適合拆成 skills。
延伸閱讀：Claude Code 完整教學 2026、Claude Code MCP 教學。
常見問題 FAQ
CLAUDE.md 一定要放在專案根目錄嗎？
通常建議放在專案根目錄，讓 Claude Code 一進入專案就能讀到主要規則。大型專案也可以在子目錄放更細的規則。
CLAUDE.md 要寫多長？
越精簡越好。放永久且高頻的專案規則即可，長篇文件和可重複流程應該移到 Skills 或其他按需載入的文件。
CLAUDE.md 可以放密碼嗎？
不建議。CLAUDE.md 應該進版控或至少被專案長期使用，不應放 API key、密碼、客戶個資或任何敏感資訊。
