Canonical: https://seo.whoops.com.tw/claude-md/
Author: Sliven 褚崇名
Source robots: follow, index, max-snippet:-1, max-video-preview:-1, max-image-preview:large
Content modified (WordPress): 2026-11-05T12:08:55+00:00
Representation modified (content/template/converter): 2026-11-12T06:48:56+00:00

# CLAUDE.md 是什麼？2027 完整教學與可直接複製範本：四層結構與撰寫原則

 

圖片：CLAUDE.md 精選圖，呈現 Managed、User、Project、Local 四層結構與專案記憶範本。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-featured-image-v2.webp）

 

撰文作者 

[Sliven 褚崇名](<https://seo.whoops.com.tw/about/#founder-title>)

 

Whoops SEO 創辦人

 

SEO 與 AI SEO 專家，專長涵蓋技術 SEO、內容策略與 GEO 優化。從搜尋排名到 AI 答案中的品牌呈現，協助企業找出優化機會、排定執行順序，並追蹤實際成效。

 

圖片：Sliven 褚崇名肖像（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/sliven-portrait-navy.webp）

 

[作者背景與專業領域](<https://seo.whoops.com.tw/about/#founder-title>) 更新 2026-11-05 約 21 分鐘閱讀

 

本篇內容

 

### 本篇內容

 

## 先看重點

摘自本文

- CLAUDE.md 是 Claude Code 開機自動讀的專案設定檔，分四層疊加、建議壓在 150 行內，只寫「AI 不知道就會出事」的地雷級規則，用 Always 或 Never 開頭才會被穩定遵守，寫對一份等於把新人上工手冊永久固化。

[CLAUDE.md 是什麼？一句話定位與它解決的真問題](<https://seo.whoops.com.tw/claude-md/#CLAUDE.md-%E6%98%AF%E4%BB%80%E9%BA%BC%EF%BC%9F%E4%B8%80%E5%8F%A5%E8%A9%B1%E5%AE%9A%E4%BD%8D%E8%88%87%E5%AE%83%E8%A7%A3%E6%B1%BA%E7%9A%84%E7%9C%9F%E5%95%8F%E9%A1%8C>)
- 有效的 CLAUDE.md 遵守五個原則：精簡、具體可執行、放地雷不放常識、用指令語氣、定期更新。

[CLAUDE.md 怎麼寫才有效？五個撰寫原則與三個常見無效寫法](<https://seo.whoops.com.tw/claude-md/#CLAUDE.md-%E6%80%8E%E9%BA%BC%E5%AF%AB%E6%89%8D%E6%9C%89%E6%95%88%EF%BC%9F%E4%BA%94%E5%80%8B%E6%92%B0%E5%AF%AB%E5%8E%9F%E5%89%87%E8%88%87%E4%B8%89%E5%80%8B%E5%B8%B8%E8%A6%8B%E7%84%A1%E6%95%88%E5%AF%AB%E6%B3%95>)
- 退一步看，CLAUDE.md 的維護成本其實不高，關鍵是建立固定節奏而不是想到才改，每月一次的 review 不到半小時，卻能避免規則腐化帶來的累積傷害。

[CLAUDE.md 怎麼維護與診斷：寫了沒效的五個原因](<https://seo.whoops.com.tw/claude-md/#CLAUDE.md-%E6%80%8E%E9%BA%BC%E7%B6%AD%E8%AD%B7%E8%88%87%E8%A8%BA%E6%96%B7%EF%BC%9A%E5%AF%AB%E4%BA%86%E6%B2%92%E6%95%88%E7%9A%84%E4%BA%94%E5%80%8B%E5%8E%9F%E5%9B%A0>)

 

### 檢查網站的 SEO 基礎

從網站網址開始，檢視可讀性與頁面基礎訊號。

- 檢查標題與搜尋摘要標記
- 核對 canonical 與索引指令
- 整理公開 HTML 的待改善項目

[免費檢查網站](<https://seo.whoops.com.tw/free-seo-audit/>)

 

[將 Whoops 設為 Google 偏好來源（另開 Google 設定頁）](<https://www.google.com/preferences/source?q=seo.whoops.com.tw>)

 

## CLAUDE.md 是什麼？一句話定位與它解決的真問題

 

圖片：CLAUDE.md 專案上工手冊示意圖，呈現專案背景、慣例、地雷與 AI 開工記憶。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-context-onboarding-v2.webp）

CLAUDE.md 的作用，就是讓 AI 每次開工都先讀到專案背景、慣例與地雷。

 

CLAUDE.md 是 Claude Code 每次啟動時自動載入的 Markdown 專案說明檔，讓 AI 帶著正確的背景知識上工，而不是每次都從零猜你的慣例與地雷。把它放在專案根目錄就生效，不需要任何設定、不需要指令、不需要外掛，Claude Code 一開工就會去讀它。如果你還沒把 Claude Code 裝起來，先把[完整 Claude Code 教學](<https://seo.whoops.com.tw/claude-code/>)看過一遍，因為裝好之後，下一步就是把 CLAUDE.md 寫對，這份檔案決定了 AI 從第一句話開始有多聰明。要改工具呼叫或介面時，請另外評估 [Claude Mod 與規則檔的分工](<https://seo.whoops.com.tw/claude-mod/>)；mod 是載入 Claude Code 的程式碼，CLAUDE.md 提供的是讓模型讀取的專案指示。

 

若要核對目前版本如何載入檔案、何時讀取 AGENTS.md，以及 `` /doctor prompt-audit `` 怎麼檢查規則，可搭配[CLAUDE.md 載入規則與診斷教學](<https://seo.whoops.com.tw/what-is-claude-md/>)使用，再把適用的指令放回自己的範本。

 

它解決的真問題只有一個：沒有它，AI 像一個新來的同事對你的專案一無所知。每次開工你都得口頭解釋「我們用 ESM 不要混 CJS」「標題不能送 slug 到 API」「API 要帶 User-Agent」，解釋完它下一輪還是會踩同一顆雷，因為這些規則沒有寫進它的記憶。寫對一份 CLAUDE.md，等於幫 AI 建立一份永久上工手冊，它每一次對話都會帶著這份手冊進來，不用你再重複交代。這也是為什麼 Claude Code 跟一般的對話型 AI 工具體驗差這麼多，[Claude Code](<https://seo.whoops.com.tw/claude-code/>) 有持久記憶，而一般對話每次都是失憶狀態，每一次都要你重新教一遍。你可以把它想成幫新同事寫一份 onboarding 文件，差別在於這份文件 AI 每天都會重讀一次，不會忘。還不熟悉 Claude 這條產品線的讀者，可以先看[Claude 使用入門](<https://seo.whoops.com.tw/claude-ai-tutorial/>)，認識聊天、[Cowork](<https://seo.whoops.com.tw/claude-cowork/>) 與 Claude Code 的分工。

 

> TL;DR：CLAUDE.md 是 Claude Code 開機自動讀的專案設定檔，分四層疊加、建議壓在 150 行內，只寫「AI 不知道就會出事」的地雷級規則，用 Always 或 Never 開頭才會被穩定遵守，寫對一份等於把新人上工手冊永久固化。

 

跟 [Claude 產品線](<https://seo.whoops.com.tw/claude-ai-tutorial/>)裡的對話工具不同，CLAUDE.md 是 Claude Code CLI 專屬的記憶機制，副檔名固定、檔名固定、沒得客製化。它跟 [Claude 桌面版](<https://seo.whoops.com.tw/claude-desktop/>)共用同一套底層引擎，但檔案層級與載入行為是 CLI 才有的特性。底層引擎持續在換代，[Claude 家族 2026 年 9 月的旗艦改版](<https://seo.whoops.com.tw/claude-opus-5-5/>)就是最新一輪，而 CLAUDE.md 這層記憶不受影響，規則寫對一次，跨模型版本都有效。換句話說，同一個專案、同一個模型，有沒有寫 CLAUDE.md，AI 的行為會差到像是兩個不同的助理。下面從四層結構講起，一路講到可直接複製的範本與維護流程，這套方法不只適用 Claude Code，你在 Claude 相關的任何工作流程裡都能借鏡「把規範寫成可執行指令」這個核心觀念。

 

## 四層結構一次搞懂：Managed、User、Project、Local 各放什麼

 

圖片：CLAUDE.md 四層結構圖，呈現 Managed、User、Project、Local 的範圍與覆蓋關係。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-four-layer-stack-v2.webp）

Managed、User、Project、Local 是四層疊加，不是隨便放一個檔案就結束。

 

CLAUDE.md 不是單一檔案，而是四層疊加：Managed 企業強制鎖定、User 全域適用你所有專案、Project 這個專案全員共用、Local 只你自己且不進 git。範圍由大到小、後者補充前者，四層全部都會被載入，發生衝突時小範圍覆蓋大範圍。理解這個疊加邏輯，才知道每條規則該寫進哪一層，這也是新手最常搞混的地方。很多人以為 CLAUDE.md 就是一個檔案，寫錯位置、放錯層級，結果規則要嘛沒生效、要嘛污染到不該影響的專案。把四層想成四個同心圓，外圈是大範圍的共通規則，內圈是越來越個人化、越來越專案化的細節，全部疊在一起才是 AI 實際拿到的那份完整記憶。

 

第一層 Managed，是企業管理員設定，使用者無法覆寫，適合放合規與資安紅線，例如「Never commit secrets to version control」「Never disable security telemetry」。這一層是公司層級的硬規定，員工改不了，所以適合放絕對不能違反的東西，像是不能把金鑰寫進程式碼、不能關閉稽核日誌、不能繞過 code review 流程。如果你是個人開發者，這一層通常用不到，可以跳過，直接從第二層開始寫。第二層 User 全域，放在 `` ~/.claude/CLAUDE.md ``，裝的是你個人的通用偏好與跨專案編碼風格，像程式碼 review 心態、最小變更原則、不要引入不必要依賴這類你到哪個專案都成立的東西。這一層的好處是寫一次，所有專案都受益，等於你的個人工程紀律被永久固化，不管是哪個倉庫，Claude Code 都會帶著這套紀律上工。

 

第三層 Project，放在專案根目錄的 `` CLAUDE.md ``，是大家最常講、也最常寫錯的那一份。內容是技術棧、架構、規範、常用指令，還有最該投資的 Known Gotchas 高風險地雷段。這份會進版控、全員共用，所以寫在這裡的東西必須對整個團隊都成立，不能摻雜個人偏好。一個常見的錯誤是把「我習慣用 vim」「我喜歡某個 linter 設定」這類個人事寫進 Project 層，結果其他用不同編輯器、不同習慣的隊友就被綁住。第四層 Local 是 `` CLAUDE.local.md ``，裝本機路徑、個人除錯習慣、暫存筆記位置，務必寫進 `` .gitignore `` 不進版控，免得隊友 pull 下來看到一堆只存在你電腦上的路徑。這四層的設計哲學很清楚：越往底層越是個人化、越往頂層越是組織化，中間的 Project 層是團隊共識的載體。

 

這裡最常踩的雷是內容放錯層。個人路徑絕對不能進 Project 層，否則隊友 pull 之後看到的規則在他們機器上完全不成立，AI 還會傻傻去讀那些不存在的路徑報錯，這種問題很難察覺，因為你自己的機器上一切正常，只有隊友會踩到，而且他們通常不會立刻反應是 CLAUDE.md 的問題。企業資安紅線也絕對不能只靠 User 層自律，因為使用者可以自己改自己的全域檔，等於沒有紅線，這也是為什麼 Managed 層的存在是必要的，它讓合規要求變成不可繞過的硬限制。判斷放哪層的標準很簡單，四選一：這條規則是「全公司不能違反」「我個人所有專案都這樣」「這個專案全員都要」「只有我自己要用」。把這四個問題問一遍，答案就是它該住的層。很多人把 CLAUDE.md 寫壞，根因都是沒想清楚這個分層，把所有東西倒進 Project 層一份檔案，結果個人偏好污染團隊、企業紅線又沒有強制力，兩頭不討好。

 

## 到底該寫什麼？一個判斷公式與六個必寫區塊

 

圖片：CLAUDE.md 六個必寫區塊圖，包含規範、指令、地雷、流程、範本與診斷。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-six-block-formula-v2.webp）

有效的 CLAUDE.md 只寫 AI 不知道就會出事的規則，六個區塊就能撐起大多數專案。

 

判斷公式只有一句：拿掉這條規則，AI 會不會犯錯？會就寫、不會就不寫，別把整份 README 複製貼進去。這句話聽起來像廢話，但我看過太多人把 CLAUDE.md 當成專案文件總整理，技術背景、公司沿革、API 設計理念、架構演進史全塞進去，結果 AI 讀完抓不到重點，真正該遵守的地雷反而被淹沒在長篇大論裡，遵守率反而比沒寫還差。判斷公式的核心精神，跟 [技術 SEO](<https://seo.whoops.com.tw/technical-seo/>) 講的「只做會影響排名的事」是同一個邏輯，把資源投在真正會出事的地方。一個簡單的驗證方式：把你想寫的每條規則，套上「拿掉它，AI 會怎樣」這個問句，如果答案是「沒差，它本來就會做對」，那這條就是多餘的，果斷刪掉。

 

用這個公式過濾一遍，真正該寫的會收斂成六個區塊。第一是專案概覽，一行講清楚這是什麼、給誰用、解決什麼問題，讓 AI 第一時間建立正確心智模型，這比你想像的重要，因為 AI 對專案的理解錯了，後面所有產出都會跟著錯，例如它以為這是內部工具就會隨便寫，以為是對外產品就會更謹慎，定位決定它的謹慎程度。第二是技術棧與常用指令，AI 不會猜你要用 `` npm run dev `` 還是 `` pnpm dev ``，也不會知道測試是 `` npm test `` 還是 `` pytest ``，這些必須明寫，省下每次確認的往返，也避免 AI 自己選一個你沒裝的指令然後報錯給你看。

 

第三是架構與目錄結構，讓 AI 知道改某個功能要去哪個資料夾、動到哪些檔案會牽一髮動全身，這對大型專案特別關鍵，因為 AI 沒有你的心智地圖，它只看得到你這次開給它的檔案，架構段等於幫它建立全域視野。第四是規範與慣例，例如命名風格、錯誤處理模式、是否偏好函數式寫法、要不要加註解、commit message 格式。第五、也是最該投資的一段，是高風險地雷 Known Gotchas，寫那些 AI 不知道就會把生產環境搞爆的規則，像是「送 API 前要先 re-GET 確認」「這個欄位送錯會 clobber 其他資料」「這個設定檔改了要 purge 快取」「這個指令跑順序錯了會鎖死資料庫」。第六是常用工具呼叫方式，例如部署腳本、上傳腳本、資料庫遷移指令的正確參數與順序，這些 AI 用猜的很容易出事，因為它會用最常見的慣例去套，而你的專案慣例很可能跟主流不同。

 

每個區塊都有一行反例可以對照。「本專案使用 React」是常識不用寫；「本專案用 ESM，`` .mjs `` 用 import、`` .js `` 用 require，兩者不可混在同一檔案」才是該寫的地雷。「程式碼要簡潔」是廢話；「prefer smallest safe change, reuse existing helpers instead of adding new dependencies」才是可執行指令。把每條規則都拿這個標準檢驗一次，你的 CLAUDE.md 當場瘦身一半，而且更有效。地雷級規則的具體寫法，下一節直接用真實案例示範，比列一百條原則更有感。

 

## 真實 before/after：有寫規則 vs 沒寫，AI 行為差在哪

 

圖片：CLAUDE.md before after 行為差異圖，對照沒有規則與有規則時 AI 行為的不同。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-before-after-behavior-v2.webp）

有沒有寫清楚規則，差別會反映在 AI 是否反覆踩同一個專案地雷。

 

同一條規則寫進 CLAUDE.md 前後，AI 的產出會從「每次踩雷你要手動修」變成「自動避開」。這一節用我自己這個 codex 倉庫真實發生過的三條地雷規則示範，這些不是從官方文件抄來的理論，是踩過痛才寫進去的教訓。講了這麼多原則，不如看三個血淋林的對照，你會立刻理解為什麼寫規則的投資報酬率這麼高。

 

第一條，禁用中文破折號裡的雙連號符號。沒寫這條規則時，AI 寫中文長文會大量產出這個符號當連接號與轉折，我得手動全篇搜尋替換，一篇文章改下來幾十處，而且每次新生成都會再犯，等於永無止境的手工活。寫了之後，AI 產出零誤用，它自動改用括號、句號或其他合法寫法。這條規則的投資報酬率極高，一行字省下每篇文章十幾分鐘的手動清理，累積到幾百篇文章就是幾十小時。

 

第二條，不送 `` title: <slug> `` 到 WordPress REST API。沒寫時，AI 為了省事直接拿 URL slug 當標題送進 `` wp/v2/posts/{id} ``，結果一次 clobber 掉 16 篇文章的標題與 Rank Math SEO 標題，復原花了一整個下午還有幾篇救不回完整狀態，這是那種會讓人冷汗直流的生產事故。寫了之後，AI 只送真實中文標題、同時送 `` rank_math_title ``，而且發布完會主動 re-GET 驗證 `` title.rendered `` 是 CJK 字元、不是 slug 字串，等於多了一道自動防線。這條規則背後牽涉的是 [技術性設定](<https://seo.whoops.com.tw/technical-seo/>)的嚴謹度，一個欄位送錯就連帶影響 SEO 表現。

 

第三條，WordPress REST API 必帶 User-Agent header。沒寫時，API 回 403，我一度以為是應用程式密碼權限問題、還是 IP 被擋，繞了一大圈才發現純粹是缺一個 header，這種誤判會讓你浪費好幾個小時查錯方向，因為 403 直覺上就是權限問題，很少有人會聯想到是 header 缺失。寫了之後，AI 每次 GET 或 PUT 都自動補上 User-Agent，再也沒出現 403。這條規則還帶出一個更大的教訓：很多 API 錯誤訊息會誤導你，403 不一定是權限、500 不一定是伺服器壞掉，真正的根因常常藏在你看不到的細節裡，把這類經驗寫進地雷段，AI 才不會重蹈你查錯方向的覆轍。

 

把這三條放一起看，會發現一個共同結構：每一條都是「觸發條件＋禁止或必做動作＋正確做法」三段式，而且都用 Always 或 Never 開頭。這不是巧合，是寫法決定了遵守率。散文式的「記得注意一下標題格式」「API 呼叫時留意一下 header」，AI 幾乎不會當一回事；寫成「Never send title as slug, always send real title and re-GET verify」「Always include User-Agent header on every WP REST request」，AI 就會穩定遵守。原因在於指令式語言讓 AI 能直接對應到動作，而散文需要它自己推斷你到底要什麼，推斷就會出錯。這也是為什麼 Claude Code 的記憶檔要當程式碼來寫，而不是當文章來寫，每一條規則都該像一行可執行的指令。

 

## 可直接複製的 CLAUDE.md 範本：四層各一份加極簡版

 

以下四份範本可直接複製貼上對應路徑：User 全域、Project 專案、Local 個人，外加一份 35 行極簡專案版給不想寫長的人。每份都標了複製後要改哪幾格，別原封照抄，因為你的專案技術棧與地雷跟我不會一樣。範本是骨架，真正讓它有效的是你把自己踩過的雷填進去。

 

User 全域範本，放在 `` ~/.claude/CLAUDE.md ``，內容是個人編碼原則與 review 心態，這些是你到哪個專案都成立的通用紀律：

 

````
# 全域原則
- Read before editing. 永遠先讀相關檔案再改。
- Prefer smallest safe change that solves the actual problem.
- Reuse existing helpers, never introduce new dependencies without reason.
- Never fabricate test results, file contents, or API behavior.
- Review mindset: assume work will be inspected line by line.
- Preserve existing architecture, style, and naming conventions.
````

 

Project 範本，放在專案根目錄 `` CLAUDE.md ``，內容是完整六區塊，重點是開頭的 Quick Reference 高風險規則，這是全篇注意力最高的位置：

 

````
# {專案名}

## Quick Reference（最高風險，放最前）
- Never send title:slug to WP API, only real titles + re-GET verify.
- Always send User-Agent header on WP REST, or 403.
- Never commit secrets; .env is local-only.

## Overview
{一句話定位 + 目標讀者}

## Tech Stack & Commands
- 語言、框架、建置指令、測試指令、部署指令

## Architecture & Directory Structure
{目錄樹 + 各資料夾職責 + 牽一髮動全身的檔案}

## Conventions
{命名、風格、錯誤處理模式}

## Known Gotchas
{踩過才寫的地雷，每條配 before/after 行為差異}
````

 

Local 範本，放在 `` CLAUDE.local.md ``，記得加進 `` .gitignore ``，內容是本機專屬的東西：

 

````
# 本機專屬
- 本機測試網址：http://localhost:8080
- 我的除錯捷徑：npm run debug:watch
- 暫存筆記放 ~/notes/{project}/，勿進版控
````

 

35 行極簡版給新專案快速起步，只留專案概覽、技術棧、三條地雷、常用指令，其他等真的踩到雷再補。這個版本的好處是門檻低，先有再求好，比一份空白檔案強十倍。很多人卡在「不知道寫什麼」就一直不開工，結果 AI 從頭到尾都在裸奔，踩的雷累積成一堆手動修正工時；與其完美主義，不如先丟一份極簡版進去，邊用邊補，CLAUDE.md 是活的文件不是一次定稿的交付物。你可以想成，這份檔案會跟著你的 Claude Code 工作流一起演化，今天寫的 35 行，半年後可能長成 150 行的完整版，每一條規則背後都有一個真實踩過的雷當依據，這才是最可靠的累積方式。

 

## CLAUDE.md 怎麼寫才有效？五個撰寫原則與三個常見無效寫法

 

有效的 CLAUDE.md 遵守五個原則：精簡、具體可執行、放地雷不放常識、用指令語氣、定期更新。最常見的無效寫法只有一種，就是把它當 README 寫。很多人以為寫得越完整越好，其實剛好相反，寫太多 AI 反而抓不到重點，地雷被淹沒在常識海裡。攤開來說，寫 CLAUDE.md 考驗的不是文筆，是判斷力，你能不能分辨哪些是 AI 本來就會的、哪些是它一定會踩的雷。判斷力來自實戰經驗，這也是為什麼資深開發者寫出來的 CLAUDE.md 比新手有效，不是因為文筆好，而是因為踩過的雷多，知道哪些規則真正值得寫進去。新手不必氣餒，從極簡版開始、邊踩雷邊補，半年後你的 CLAUDE.md 也會變得很有殺傷力。

 

原則一精簡優先，建議壓在 150 行以內，超過這個數字 AI 開始遺漏後半段內容，下一節會講背後的 context 成本理由。精簡不是少寫，是只寫有用的，兩者差很多，少寫是漏掉該寫的，精簡是砍掉不該寫的。原則二具體勝過抽象，「用簡單程式碼」這種寫法完全無效，AI 不知道你定的簡單是什麼標準；「prefer smallest safe change, reuse existing helpers」才有可執行性，AI 知道該怎麼對應到實際行為。你可以這樣測試一條規則夠不夠具體：把這條規則拿給一個不懂你專案的人看，他能不能照著做？不能的話，就是太抽象。抽象的形容詞是 CLAUDE.md 的毒藥，具體的動作描述才是解藥。

 

原則三放地雷不放常識，AI 本來就懂的東西不用寫，例如「JavaScript 是弱型別語言」這種常識寫了也是浪費 context，只寫它不知道會出事的。原則四用指令語氣，Always、Never、Prefer 開頭的規則，遵守率明顯高於散文描述，這在前面三條 before/after 案例已經驗證過，同樣的意思寫成「記得別用某符號」跟寫成「Never use 該符號」，後者效果天差地遠。原則五定期更新，地雷會演化，過時的規則比沒有規則更危險，因為它會誤導 AI 做出錯誤行為還自以為合規。

 

三個最常見的無效寫法要特別避開。第一是當 README 抄，把架構設計理念、技術選型理由、歷史演進全塞進去，AI 讀完只記得背景故事不記得地雷。第二是規則互相矛盾，例如同時寫「always add comments to every function」又寫「minimize diff and avoid noise」，AI 只好猜你要哪個，結果兩邊都不滿意。第三是寫成願景宣言，「我們重視程式碼品質」「追求卓越」這種句子對 AI 沒有任何行為指引，刪掉就好，留著只是佔 context。老實說，把這三種無效寫法都避開，你的 CLAUDE.md 已經比八成的人寫得好。

 

## CLAUDE.md 多少行才適合？長度取捨與 context 成本

 

圖片：CLAUDE.md 長度與 context 成本圖，呈現 150 行、高風險規則與 context 成本取捨。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-length-context-cost-v2.webp）

CLAUDE.md 不是越長越好，真正要留下的是高風險、可執行、會改變行為的規則。

 

實務建議控制在 150 行以內、地雷段集中在開頭的 Quick Reference。理由很直接：CLAUDE.md 會佔用每一次對話的 [context 空間](<https://seo.whoops.com.tw/what-is-llm/>)，寫太長等於每次開工都先付一筆固定的 context 稅，還擠壓你真正任務能用的空間，同時讓 AI 抓不到重點。這不是感覺問題，是可量化的成本，每多一行就是每次對話多一份固定開銷，累積到幾百次對話就是顯著的浪費。更實際的影響是，當任務本身需要大量 context（例如讀一個大檔案、分析一段長程式碼），被 CLAUDE.md 吃掉的空間會直接壓縮你能餵給 AI 的任務內容，導致它看不全、判斷失準。所以控制長度不是潔癖，是效能最佳化。

 

為什麼抓在 150 行這個數字，是兼顧資訊密度與 AI 注意力的經驗值。觀察到的行為是，超過這個長度，AI 對檔案後半段的遵守率會明顯下降，你寫在結尾的地雷幾乎等於沒寫，這跟人類讀長文會越讀越漏抓不到重點是同一個機制。所以最該被遵守的高風險規則一定要放最前面，開頭是 AI 注意力最高的位置，這也是為什麼範本裡 Quick Reference 永遠在最頂端。直白地講，位置比數量重要，三條寫在開頭的地雷，效果勝過三十條寫在結尾的規則。如果你發現自己想寫的東西超過 150 行，先問自己：這些真的都是 AI 不知道就會出事的嗎？多半會發現有一半是常識或裝飾，砍掉就達標了。

 

降載的方法是拆層。把個人偏好移到 User 層、把專案細節移到對應子目錄的 CLAUDE.md，Claude Code 會依工作目錄載入對應層級，等於按需載入而不是一次全塞。比方說一個 monorepo 裡有前端、後端、基礎設施三個子專案，與其把三邊的地雷全塞進根目錄，不如各自在子目錄放一份 CLAUDE.md，當你在前端目錄工作時只載入前端相關規則，context 占用立刻減三分之二。什麼時候可以超過 150 行？大型 monorepo、多地雷專案這種情況可以放寬，但前提是搭配目錄結構分流，讓每個子目錄自己消化一部分地雷，而不是全部塞進根目錄那一份變成失控的長文。回顧一下，核心原則就是地雷放最前、個人移到全域、細節拆到子目錄，這三招組合起來，再大的專案都能把 CLAUDE.md 控制在有效範圍。

 

## CLAUDE.md vs AGENTS.md：差在哪、團隊兩種 agent 並存怎麼辦

 

圖片：CLAUDE.md 與 AGENTS.md 團隊工作流圖，呈現兩種 agent 指令檔如何分工與維護。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/06/claude-md-agents-md-team-workflow-v2.webp）

當團隊同時使用 Claude Code 與 Codex，CLAUDE.md 與 AGENTS.md 要分工清楚、規則一致。

 

CLAUDE.md 是 Claude Code 的持久指示檔；[AGENTS.md 的規格與共用方式](<https://seo.whoops.com.tw/what-is-agents-md/>)則面向多種 coding agent，包括 [OpenAI Codex](<https://seo.whoops.com.tw/openai-codex/>)。兩者都是 Markdown，通用的專案慣例、測試指令與禁區可以放在同一份內容裡。真正要核對的是各工具找檔案的位置、載入條件與工具專屬的設定。

 

[AGENTS.md 官方規格](<https://agents.md/>)沒有必填欄位，也不要求固定標題。CLAUDE.md 的組織、使用者、專案與本地層，以及 Codex 的全域、專案與子目錄指示鏈，屬於工具的載入機制，不能直接互套。共用內容之前，先確認那條規則需要跨所有專案生效，還是只適用於目前的 repo。

 

團隊同時用兩種 agent 時，保留一份通用規則可避免內容漂移。[Claude Code 官方記憶文件](<https://code.claude.com/docs/en/memory>)提供的做法是在 CLAUDE.md 寫 `` @AGENTS.md ``，共用規則留在 AGENTS.md，Claude 專屬指示寫在匯入之後；也能用 `` /config `` 的 `` claude-md-and-agents-md `` 設定並讀。單工具專案可維持原本的檔案，不必為了尚未使用的工具多養一份規則。工具選擇可另看〈[Codex vs Claude Code 完整比較](<https://seo.whoops.com.tw/codex-vs-claude-code/>)〉。

 

## CLAUDE.md 怎麼維護與診斷：寫了沒效的五個原因

 

CLAUDE.md 寫了卻沒效，九成是下面五個原因之一：檔案沒被載入、規則太長被忽略、寫成 README 抓不到重點、規則互相矛盾、過時未更新。診斷的第一步永遠是先確認檔案到底有沒有被載入，因為前面四個原因再怎麼調都沒用，前提是檔案根本沒進到 AI 的視野。不過話說回來，很多人連這第一步都跳過，直接懷疑模型不夠聰明，其實問題出在自己的設定。

 

原因一檔案位置錯，沒放專案根目錄、檔名拼錯、放錯層，都會讓 Claude Code 讀不到。這是最常見也最容易被忽略的原因，因為你不會收到任何錯誤訊息，Claude Code 不會跳出來跟你說「我找不到 CLAUDE.md」，它只是靜默地用沒有記憶的狀態工作，你卻以為規則有生效。確認方法是用 `` /memory `` 指令，它會列出目前實際載入的所有 CLAUDE.md 內容，沒看到你的規則就是沒載到。原因二規則太長，超過 150 行 AI 開始忽略後半，解法是精簡或拆層。原因三寫成 README，AI 抓不到可執行指令，改用 Always 或 Never 語氣重寫，把散文改成指令。

 

原因四規則矛盾，兩條規則打架 AI 只好用猜的，審查時直接刪掉一條或合併成一條明確的。這種矛盾常常是無意間造成的，例如你三月寫了「always add type annotations」，六月又補了一條「minimize diff for hotfix」，遇到 hotfix 時 AI 就不知道該不該加型別標註。原因五過時，專案演化後舊規則反而誤導，例如改了框架但規則還寫舊框架的指令、改了部署流程但規則還寫舊腳本，這種隱形地雷最危險，因為它會讓 AI 自信地做錯事，你還以為它照規則來沒問題，其實規則本身已經是錯的。退一步看，CLAUDE.md 的維護成本其實不高，關鍵是建立固定節奏而不是想到才改，每月一次的 review 不到半小時，卻能避免規則腐化帶來的累積傷害。

 

維護流程建議這樣跑：每個月固定 review 一次，把過時的刪掉、把新踩到的雷補上；每次發生地雷事件，當下立刻補一條規則，趁記憶鮮明寫得最準，事後補通常會漏掉細節，因為你會忘記當時具體是哪個欄位、哪個參數出問題；用 git 追蹤 CLAUDE.md 的變更原因，commit message 寫清楚是哪個事件觸發的修正，這樣未來 review 時看得到每條規則的來龍去脈，也方便隊友理解為什麼有這條規則存在。把 CLAUDE.md 當程式碼一樣版本控，它才會越用越準、越用越貼近專案真實狀態，而不是一份越積越厚、沒人敢動的化石文件。這套維護紀律，跟你經營 [技術 SEO](<https://seo.whoops.com.tw/technical-seo/>) 一樣，需要的是持續校準而不是一次到位，網站的技術債會累積，CLAUDE.md 的地雷清單也會累積，差別只在於你有沒有定期清。

 

寫好 CLAUDE.md 後，下一步是用 Plan Mode 與權限護欄鎖住 AI 行為（〈[Claude Code 安全設定實戰](<https://seo.whoops.com.tw/claude-code-permissions-plan-mode/>)〉），並評估自己的方案成本（〈[Claude Code 費用與方案選擇](<https://seo.whoops.com.tw/claude-code-pricing/>)〉）。

 

## 常見問題（FAQ）

 

### CLAUDE.md 要寫什麼？

 

只寫「AI 不知道就會出事」的內容，收斂成六個區塊：專案概覽、技術棧與指令、架構與目錄、規範與慣例、高風險地雷、工具呼叫方式。判斷標準只有一句，拿掉這條規則 AI 會不會犯錯，會就寫、不會就別寫，更不要把整份 README 抄進去。地雷段是最該投資的一塊，因為它直接決定 AI 會不會把生產環境搞爆，這也是 Claude Code 用得好不好的分水嶺。新手最常犯的錯是花太多力氣寫概覽跟技術棧，卻在地雷段只寫兩三條敷衍的，本末倒置。

 

### CLAUDE.md 有幾層？Managed、User、Project、Local 差在哪？

 

四層。Managed 是企業強制鎖定、使用者不能改；User 全域在 `` ~/.claude/CLAUDE.md ``，裝你個人到哪都用的偏好；Project 在專案根目錄，是全員共用的技術與地雷；Local 是 `` CLAUDE.local.md ``，只你自己、不進 git。範圍由大到小、後者補充前者，衝突時小範圍覆蓋大範圍。個人路徑千萬別進 Project 層，企業紅線也別只靠 User 自律。個人開發者通常只會用到 User 跟 Project 兩層，加上偶爾的 Local，Managed 層是團隊與企業才需要關心的。

 

### CLAUDE.md 多少行才適合？可以超過 150 行嗎？

 

建議 150 行以內，因為它會佔用每次對話的 context。超過這個長度，AI 對後半段遵守率下降，地雷放結尾等於沒寫。大型 monorepo 或多地雷專案可以放寬，但前提是拆到子目錄分流，讓每個子目錄自己消化一部分地雷，而不是全塞根目錄那一份。關鍵判斷是資訊密度，不是總行數，同樣 150 行，全塞地雷跟摻一半常識，效果天差地遠。真的不確定，就從 50 行開始，用一陣子看 AI 哪裡常出錯，再針對性地補，比一開始就想寫滿 150 行更務實。

 

### CLAUDE.md 跟 AGENTS.md 差在哪？團隊兩個都用怎麼辦？

 

CLAUDE.md 是 Claude Code 的專案指示檔，AGENTS.md 是供多種 coding agent 共用的開放格式；兩者都是 Markdown。跨工具團隊可把通用規則集中在 AGENTS.md，再由 CLAUDE.md 用 @AGENTS.md 匯入，Claude 專屬指示另外保留。載入位置、優先順序與是否預設讀取仍要依各工具確認。

 

### CLAUDE.md 寫了 AI 還是不遵守怎麼辦？

 

依序排查五個原因：檔案沒被載入（用 `` /memory `` 確認）、規則太長被忽略、寫成 README 抓不到重點、規則互相矛盾、過時未更新。八成是前三個，尤其要檢查規則是不是用 Always 或 Never 開頭，散文式描述的遵守率明顯較低。先確認有沒有載入，再檢查寫法，接著才考慮內容本身。如果五個都排除了還是不遵守，那通常代表這條規則本身寫得不夠具體，AI 理解不了你要的精確動作，把它改寫成帶觸發條件與明確動作的三段式指令再試一次。

 

### CLAUDE.local.md 是什麼？要進 git 嗎？

 

CLAUDE.local.md 是第四層 Local，裝本機路徑、個人除錯習慣、暫存筆記這類只屬於你的東西。絕對不要進 git，要寫進 `` .gitignore ``，否則隊友 pull 下來會看到一堆只存在你電腦的路徑，也會把個人偏好污染到團隊規範，造成規則來源混亂。它的存在就是為了讓個人流東西有地方放，又不影響其他人，概念上跟 `` .env.local `` 之類的本機設定檔一樣，是個人化的、不入版控的、只對你自己生效的一層。

 

### 怎麼確認 CLAUDE.md 有被 Claude Code 載入？

 

在對話裡輸入 `` /memory `` 指令，它會列出目前實際載入的所有層級 CLAUDE.md 內容。如果看不到你寫的規則，代表檔案位置錯、檔名拼錯、或放錯層，回頭檢查是不是放在專案根目錄、檔名是不是正好 `` CLAUDE.md `` 這幾個字、有沒有多打空格或副檔名。這是診斷沒效問題的第一步，確認載入之後才談得上調內容。養成習慣，每次新增或大改 CLAUDE.md 之後跑一次 `` /memory `` 確認，省得事後除錯半天才發現規則根本沒進 AI 的視野。

 

說到底，CLAUDE.md 不是文件，是給 AI 的行為指令。寫對一份，等於把新同事的上工手冊永久固化，AI 每次都帶著它進對話，不再踩同樣的雷，你也不用每次開工都重新教一遍。關鍵就三件事：只寫地雷級規則、用 Always 或 Never 開頭、壓在 150 行內。這套方法落地，建議先從一份 35 行極簡版開始，踩到雷再補，比追求一次寫完美更實際，也更容易養成維護習慣。記住，CLAUDE.md 的價值不在於一次寫得多漂亮，而在於它能不能持續攔截 AI 會犯的錯，這是一場長期賽，不是一次性交付。

 

想從安裝到進階用法一次看懂 Claude Code，回到[完整 Claude Code 教學](<https://seo.whoops.com.tw/claude-code/>)主篇；如果你關心的是 AI 搜尋時代的內容曝光，[AEO 是什麼](<https://seo.whoops.com.tw/what-is-aeo/>)、[技術 SEO 基礎](<https://seo.whoops.com.tw/technical-seo/>)與[llms.txt 指南](<https://seo.whoops.com.tw/llms-txt-guide/>)是延伸方向，把 AI 工具鏈跟搜尋曝光串起來看會更有全局感；想理解 AI 怎麼讀懂網站之間的關聯，[內部連結是什麼](<https://seo.whoops.com.tw/what-is-internal-link/>)能補上這塊，因為 AI 引擎跟傳統搜尋引擎一樣會爬內部連結來理解站點結構；而要把 Claude 生態看全，Claude 產品線總覽、[桌面版介紹](<https://seo.whoops.com.tw/claude-desktop/>)與 [Codex 對照](<https://seo.whoops.com.tw/codex-vs-claude-code/>)值得一併讀，搞清楚每個工具的定位，才知道 CLAUDE.md 在整個工作流裡扮演什麼角色。把這些讀完，你對 AI coding 的設定與協作會有完整的地圖，不會再只盯著單一檔案見樹不見林。

 

[AI Agent](<https://seo.whoops.com.tw/tag/ai-agents/>)[Claude](<https://seo.whoops.com.tw/tag/claude/>)[知識管理](<https://seo.whoops.com.tw/tag/knowledge-management/>)

 

喜歡這篇內容？讓下次搜尋，更容易遇見 Whoops。

[將 Whoops 設為 Google 偏好來源（另開 Google 設定頁）](<https://www.google.com/preferences/source?q=seo.whoops.com.tw>)前往 Google 選取並確認，即可完成設定。

 

[## Sliven 褚崇名](<https://seo.whoops.com.tw/about/#founder-title>)

Sliven 褚崇名是 Whoops SEO 創辦人，負責技術 SEO、內容與關鍵字策略、WordPress 網站重建，以及 AI SEO、AEO、GEO 的量測與內容優化。作者頁可查閱由他署名的〈SEO 是什麼〉與〈AI SEO 是什麼〉等教學；內容中的自有量測、模型觀測與第三方來源應分開判讀，並以各頁標示的方法與限制為準。是否適合特定專案，仍需依網站現況、目標、執行範圍與可驗證成果判斷。

[查看作者文章 →](<https://seo.whoops.com.tw/about/#founder-title>)

 

## 討論與提問

 

### 發佈留言

 

WHOOPS / JOURNAL

## 更多值得一讀的文章

[探索知識庫 ↗](<https://seo.whoops.com.tw/blog/>)

[AI 工具與應用約 23 分鐘閱讀

### 最佳 CLAUDE.md 完整教學：位置、寫法與規則排查

CLAUDE.md 是 Claude Code 保存專案規則的 Markdown 檔案。整理檔案位置與載入順序、CLAUDE.local.md、AGENTS.md 支援、auto memory、@ 匯入與路徑規則，附三個可修改範例及規則未生效的排查方式。

閱讀文章](<https://seo.whoops.com.tw/what-is-claude-md/>) [AI 工具與應用約 19 分鐘閱讀

### 最佳 Claude SEO 完整教學：關鍵字研究與內容最佳化

Claude SEO 是把 Claude 放進 SEO 流程：關鍵字研究、搜尋意圖分類、競爭頁面分析、既有內容更新與 Search Console 資料分析。本文整理八步工作流程、四組可直接複製的 Prompt 範本、常見錯誤與工具界線，帶你把資料變成可執行的工作清單。

閱讀文章](<https://seo.whoops.com.tw/claude-seo/>)
