CLAUDE.md 怎麼寫？768 行砍到 153 行，AI 從通用助理變懂我的同事

我以前一直以為 AI 只能給我很通用但不一定符合我需求的答案，直到我替 Claude Code 寫了一份它每次開工都會先讀的 CLAUDE.md，同一個模型突然從「通用顧問」變成「懂我系統的同事」。這篇我不藏私分享我自己用的 CLAUDE.md，並告訴你它到底放了什麼、為什麼這樣放，最後你會發現同一套東西可以「搬」到 Codex 的 AGENTS.md，也可以給其他 AI 使用。

• CLAUDE.md 不是設定檔，是 AI 每次對話開頭自動載入的「常駐記憶」，它決定 AI 是通用助理還是你的分身。
• 我的現役檔案只有 153 行，主體是一段 ## 通用規則——兩個 AI 都該遵守的共識層。
• 這份檔同時是 CLAUDE.md 也是 AGENTS.md——兩者都是指向同一個檔案的 symlink，只要編輯一份，Claude 與 Codex 都可以同步。

一、AI 給的建議總是不符合需求？我一度以為是模型不夠聰明

2026 年 3 月底我開始學 Claude Code，那陣子最挫折的不是它不會做事，而是它做的事漏東漏西，也沒辦法針對我的現況給出最優的建議。我請它「幫我規劃開發一個股市分析聊天機器人」，它推薦一堆我現有資源根本無法使用的線上工具，導致我實際跟著 AI 執行了半天之後，發現這個方案我無法執行；我請它整理筆記，它給我一套教科書式的資料夾結構，完全不知道我已經有 Notion、Obsidian、PostgreSQL，導致功能衝突，知識管理系統疊床架屋，最後還花了很大的力氣簡化成符合我需求的系統。

那時我的反應跟多數人一樣：是不是要換更強的模型、是不是 prompt 寫得不夠精準？於是我把 prompt 越寫越長，每次對話都重新交代一次「我有甚麼資源、請你在任務失敗時務必告知我原因及改進方向、請你在規劃時務必檢視有沒有與我現有的系統重疊等等的提示詞」。重點是寫了之後它還不一定會每次都好好地遵守，這次提醒下次忘記。

二、AI 沒有你的記憶，才是建議不符合需求的真正原因

AI 給的建議不符合需求，不是因為它笨，是因為它根本沒有你的記憶。 每一個新的對話，模型都是從零開始，它不知道我是誰、用什麼工具、哪些是他無法自行決定的權限。你以為你在「調教」它，其實對話一關，那些脈絡就全部蒸發了，跟屢勸不聽的同事有的比。

CLAUDE.md 解決的就是這件事。Anthropic 官方文件也把它定義成「給 Claude 的持久指令」：本質上只是一個放在專案根目錄的純文字 Markdown 檔，Claude Code 在每個對話開始就自動讀它、把內容注入這次工作階段，就是「每次開工先讀一遍說明書」。

但這也是最多人可能踩雷的地方。Claude Code 系統提示本身已經塞了大約 50 個指令，佔掉模型能可靠執行的指令量一大半。所以你的 CLAUDE.md 不是寫越多越好——指令越少、越精要越好，社群共識是控制在 200 行以下，超過就建議精簡。我自己的檔案從一開始的 768 行一路砍，收斂成現在的 153 行。

三、CLAUDE.md 怎麼寫？我的規則檔逐段公開

下面是我一次次使用上遇到困擾時就做修正，並陸續使用了 3 個月的精華。核心是這段 ## 通用規則——兩個 AI 都吃的共識層。我把小節標題抽出來、附一句註解，後面再逐區講為什麼這樣規劃：

# AI Workspace — 柴柴的 AI 工作室
> 本檔 = Claude Code 與 Codex 的共用規則「單一真相源」
> 根目錄 CLAUDE.md 與 AGENTS.md 都是指向本檔的 symlink，
> 編輯只改這一份，兩個 AI 各從自己入口讀到全部

## 通用規則
### 溝通原則          # 繁中／具體步驟／先說原生有沒有／新設計案先掃業界／不確定就問
### 對外寫作標準       # 動筆前先讀 writing-style.md（真相源），Notion 頁只是唯讀快照
### 環境架構（雙軌制）  # 開發=Mac Mini 互動；自動化=Zeabur headless + n8n + Discord
### 資料夾地圖         # 三層導航表 + 架構變更鐵則 + Vault 公私隔離
### 開發規範          # 台灣時間／中文 commit／不寫死 API Key／改 code 外科手術式
### 人類決策分級       # 🔴 等我 ／ 🟡 做完通知 ／ 🟢 全自動
### 待辦管理          # 唯一真相源 = Notion「AI開發待辦事項」DB
### Session 接力協議   # progress.md：開工先 READ、收工 WRAP UP
### 記憶系統取用協議    # memory/knowledge/ 單一真相源；Claude 自動載入、Codex 手動讀
### 自動化任務失敗處理   # 失敗主動通報、不疊補丁、自我驗證

一份檔，多入口：我不維護兩份規則

檔案最上面三行就是靈魂：先宣告「本檔是兩個 AI 的共用真相源」，再說明 CLAUDE.md（Claude Code 讀）和 AGENTS.md（Codex 讀）都是指向它的捷徑檔。所以我不是維護兩份規則、是維護一份，再讓多個 AI 平台同步取用，維護難度直接砍半。

通用規則只放「兩個 AI 都要守」的共識

這段是共識層。其中兩條是我拿教訓換來的：「先說原生有沒有」：別讓 AI 動不動就重建工具官方系統就有的功能；「新設計案先掃業界」：動筆前先花 10 分鐘查前人怎麼做過。

在規則裡寫死「誰能決定什麼」

同一段裡的人類決策分級 🔴🟡🟢，是我跟 AI 的權限邊界：花錢、對外發布要我點頭，純整理它自動做。權限講清楚，我才敢放手讓它自己跑。

指路不搬運：規則檔只存指標，不存內容

「對外寫作標準」只寫一句「去讀 writing-style.md」、待辦只寫「真相源是那個 Notion DB」。規則檔本身不存內容，只存「真相住在哪」的指標；要引用就指過去、不複製，檔案才不會越長越胖。

四、寫好 CLAUDE.md 之後，AI 的建議真的變準了

最直接的變化是行數。這份檔案我一路砍：768 行 → 120 行 → 88 行 → 現在是 153 行。每次修正前我都先觀察，看哪幾條規則「從來沒被觸發」或「被誤觸發」。規則不是寫了就有用，是要被準確觸發才有價值。

和 AI 溝通上的改變更明顯：以前我得每次交代「不要推薦新工具」，現在「溝通原則」裡的「先說系統原生有沒有」讓它直接用我既有的工具資源給方案；以前它把我每件專案的開發待辦事項存在日報、分析、計畫等各個檔案，現在靠「資料夾地圖」那張表加上「待辦只認 Notion DB」的規定，它知道「日報走 logs/、計畫走計畫資料庫、待辦寫進 Notion，不要誤存也不會忘記取用」。連我最在意的公私業務分離也靠「Vault AI 隔離規則」好好的分離——工作業務內容絕不會混進我的自媒體草稿。以相同模型開發，差別只在我替它寫好了規則。

五、規則寫進 CLAUDE.md，不等於 AI 就會照做

但我也得誠實講翻車現場，而且不只一次。5 月中我做了 SKILL 健康度監測計畫，結果閉門造車了 1.5 小時，很興奮地加了我自行發想的功能，結果事後盤點發現 80% 是在重造業界早有前案的系統；隔天又規劃多 agent 互相監督、5 個 agent 的編制、還沒補 trace／eval 就想讓系統自我迭代，後來請 AI 查了一樣網路上的案子，才知道這些規劃全是已經被試過、被放棄的方向。「新設計案先掃業界」這條鐵則，就是這兩次教訓固化出來的。

但更扎心的是：把規則寫進 CLAUDE.md，不等於它就會被執行。 文字化只是第一步，你還得在每次對話裡真的盯它有沒有照做。這也是為什麼我把這條設成「動筆前必做」的硬規定，而不是溫柔的建議。

六、Codex 要另外寫 AGENTS.md 嗎？其實是同一份檔

不用另外寫。我根本沒有第二份檔——「搬到 Codex」不是把規則複製一份、改個檔名叫 AGENTS.md。

Codex 讀的 AGENTS.md 和 CLAUDE.md 同樣為純 Markdown、沒有必填欄位，放的東西一模一樣（身份、慣例、決策邊界、紅線），這個規格被 OpenAI Codex、Cursor、Amp 等 30 多個工具、超過 6 萬個 repo 採用。既然兩邊放的東西一樣，我就不維護兩份：規則全部收進一份檔案當單一真相源，再用 symlink 讓 CLAUDE.md、AGENTS.md 都指向它。我改一行，兩個 AI 下次開工都讀到。

結論

三個月下來，我把個人 AI 系統建立的經驗濃縮成三個重點：

1. 讓 AI 變強的不是換模型，是給它執行說明書。
2. 規則要精簡、不可過於冗長。 只留「每個任務都要遵守」的通用規則，其餘交給 Skill 按需載入。
3. 一份規則，多入口載入。 用 symlink 把 CLAUDE.md 跟 AGENTS.md 接到同一個來源，跨工具不必維護兩份。

如果你還沒有整理自己的 AI 脈絡，可以先從我前面寫過的兩篇開始：AI 資料庫建好了，你的 AI 才真的好用 先處理「AI 要讀什麼」，Notion 第二大腦怎麼建？我的四個核心資料庫公開 則處理「資料要怎麼放」。

你不用是工程師才需要 CLAUDE.md。只要你有一套自己的系統、有不想每次重講的提示詞，這份檔案就是你把 AI 從「通用助理」變成「你的分身」的第一塊地基。

寫好這份檔，只是整套系統的起點。接下來我會把 Agent、Skill、MCP、排程、Hook 這些機制一篇一篇寫清楚——想追的話，到 Threads 找 @tech_shiba，新文都會在那邊發；也歡迎留言告訴我，你的 CLAUDE.md 會先寫哪一條規則。