精華筆記

· @aihub.tw

Claude 新手指南

CLAUDE.md:給專案一份「開機記憶」,AI 一啟動就懂你

CLAUDE.md:給專案一份「開機記憶」,AI 一啟動就懂你

上一課你把 Claude Code 裝好、跑出了第一個結果。用久了你大概會發現一件煩事:它每次重開都失憶。你昨天才告訴它「這專案用 Next.js、測試要跑 npm test、不要碰 legacy/ 那包舊程式碼」,今天重開一個對話,它又問你「這專案用什麼框架?測試怎麼跑?」——因為 Claude Code 每一次啟動,都是從一張白紙開始。

這不是它笨,是設計如此:每個對話都有全新的「脈絡窗(context window,你可以想成它的短期記憶)」,關掉就清空。要讓它跨對話記得事情,你得給它一份「開機就會自動讀」的檔案。這份檔案有固定的名字,叫 CLAUDE.md。寫好它,AI 一啟動就懂你的專案,不用再每次從零開始重講。

這堂課適合誰 適合:已經裝好 Claude Code、想讓它記住專案規矩、少走冤枉路的人。需要基礎:會在終端機開 Claude Code、下過幾句自然語言指令就夠,零程式底子也能跟著寫(CLAUDE.md 就是純文字)。前置課:第 3 課(Claude Code 入門)——那裡 `/init` 產生的那份檔案,就是這堂的主角。

這堂學什麼

  • CLAUDE.md 到底是什麼:為什麼它能讓 AI「跨對話記憶」,以及跟它有沒有差在哪
  • 四層位置怎麼疊:組織、個人、專案、本機四種放法,決定誰看得到、要不要進 git
  • 該寫什麼、不該寫什麼:一份好 CLAUDE.md 的解剖,以及一個可以直接抄的範本
  • 正確的養成流程:別從空白開始——用 /init 生草稿、精修、再持續維護
  • 2026 新機制「自動記憶」:Claude 會自己做筆記,它跟 CLAUDE.md 怎麼分工
  • 進階整理:@ 匯入與子目錄各自的 CLAUDE.md,加上四個新手常踩的坑

觀念一:CLAUDE.md 是專案的「開機記憶」

先把最核心的畫面立起來。CLAUDE.md 就是一份放在專案根目錄的 Markdown 純文字檔,名字固定(全大寫 CLAUDE)。Claude Code 每次啟動,會自動把它整份讀進這次對話的脈絡——等於每次開機都先幫你把「這專案的須知」念一遍給 AI 聽。

有沒有 CLAUDE.md 的差別:沒有就每次重講,有的話開場就記得直接開工

差別很直接:沒有它,你每開一個新對話都要重講框架、指令、慣例;有了它,這些事開場就在 AI 腦子裡,它直接進入狀況。你可以把 CLAUDE.md 想成貼在新人座位上的一頁 A4 新人須知:最重要的規矩、指令、禁區,一進門就看得到。

它是「建議」,不是「鐵律」官方講得很白:CLAUDE.md 是當成脈絡(context)餵給 Claude,不是強制設定。它會盡量照做,但寫得越具體、越精簡,遵守得越穩;模糊或互相矛盾的指令,它可能隨便挑一個。真的要「不管怎樣都必須執行」的動作(例如每次 commit 前跑檢查),那要用 hook,不是寫在 CLAUDE.md——這超出新手範圍,先知道有這回事就好。

觀念二:四層位置,全部疊加

很多新手以為 CLAUDE.md 只能放專案根目錄,其實它有四種位置,各自負責不同範圍,而且會全部疊在一起載入(不是互相覆蓋)。載入順序是從最廣到最貼近你,所以越後面讀到的、越貼近你的設定,優先權越高。

CLAUDE.md 的四層:組織政策、使用者、專案、本機,全部疊加載入

  • 組織政策(公司 IT 部署,個人關不掉):公司統一規範,你自己一個人用不到,知道有這層即可。
  • 使用者(~/.claude/CLAUDE.md):放你所有專案共用的個人偏好,例如「回答一律用繁體中文」「commit 訊息用中文」。設一次,每個專案都吃得到。
  • 專案(./CLAUDE.md 或 ./.claude/CLAUDE.md):這堂的重點。放跟這個專案綁定的規矩,會進 git,團隊每個人共用同一份。
  • 本機(./CLAUDE.local.md):只有你、只在這個專案的私人設定,例如你自己的測試網址。記得加進 .gitignore,不要上傳。

對個人使用者來說,九成場景就用專案那層(./CLAUDE.md),把個人跨專案偏好丟到 ~/.claude/CLAUDE.md,這兩層搞懂就夠了。

觀念三:CLAUDE.md、自動記憶、README——別搞混

到了 2026,Claude Code 的「記憶」其實有兩套系統,加上一個老朋友 README,新手最容易混淆。一張圖講清楚:

三種給 AI 的檔案對照:CLAUDE.md 你寫的規則、自動記憶 Claude 自己寫、README 給人看的

  • CLAUDE.md:你寫的規則與指令,每次開場全部載入。這是你主動掌控 AI 行為的地方。
  • 自動記憶(auto memory):Claude 自己寫的。這是 2026 新增、預設開啟的機制——它一邊做事一邊把學到的東西(常用指令、你糾正過的偏好、除錯心得)記進 ~/.claude/projects/<專案>/memory/ 底下的 MEMORY.md。你不用動手,它自己累積。當你在畫面上看到「Writing memory / Recalled memory」,就是它在寫或讀這份筆記。
  • README.md:寫給人看的專案介紹與安裝步驟。Claude 不會自動整份讀它(要的話你得自己叫它讀,或用等一下講的 @ 匯入)。

一句話分工:CLAUDE.md 是你下給 AI 的指令,自動記憶是 AI 幫自己做的筆記,README 是給人類看的說明書。 兩套記憶系統可以並存:你負責寫「規矩」,它負責記「它學到的細節」。

自動記憶小提醒自動記憶需要 Claude Code v2.1.59 以上(打 claude --version 可看)。它只會把 MEMORY.md 的前 200 行(或 25KB)在開場載入,所以它會自己把細節搬到別的分頁檔、保持索引精簡。想看它記了什麼,打 /memory 就能瀏覽、編輯、刪除——全部都是你看得懂的純文字。

實戰:別從空白開始,三步養出一份好 CLAUDE.md

新手最容易犯的錯,是打開一個空檔案對著它發呆。正確做法是先讓 AI 生草稿,你再精修,之後持續維護。

養成一份好 CLAUDE.md 的三步:/init 生草稿、刪到剩精華、用 /memory 持續累積

用 /init 生一份草稿

在你的專案資料夾裡開 Claude Code,直接打:

/init

它會自己掃過整個專案,推斷你的技術棧、找出建置與測試指令、觀察程式碼慣例,自動生一份 CLAUDE.md 草稿。這是最省事的起點,別自己從零寫。

2026 的貼心改動:如果專案已經有 CLAUDE.md,/init 不會覆蓋它,而是提出改進建議讓你選擇,所以放心跑不會弄丟原本的內容。

刪到只剩精華(這步最多人跳過)

/init 生出來的草稿常常太囉嗦,把 AI 從程式碼一看就知道的東西也寫進去了。你的工作是刪:把「AI 自己看得出來」的廢話砍掉,只留「AI 猜不到、但每次都需要知道」的事。

官方建議一份 CLAUDE.md 控制在 200 行以內。為什麼要這麼克制?因為它每次開場都佔用 AI 的脈絡(記憶空間),塞太多不但燒 token,還會稀釋重點、讓它更不聽話。把它當一頁 A4,不是一本手冊。

照四個區塊補齊內容

一份好的 CLAUDE.md 大致長這樣——技術棧、常用指令、慣例、禁區,四塊講完收工:

好的 CLAUDE.md 解剖:技術棧、常用指令、慣例、禁區四個區塊

可以直接抄這個範本改:

# 專案說明

這是一個電商後台,前端 Next.js 15 (App Router) + TypeScript,
後端 Node.js + PostgreSQL。

## 常用指令
- 開發:`npm run dev`
- 測試:`npm test`(改完程式一定要跑)
- 型別檢查:`npm run typecheck`

## 慣例
- 元件放 `src/components/`,一個元件一個資料夾
- 用 2 空格縮排、不用分號
- API 錯誤一律回 `{ error: string }` 格式

## 注意
- 不要碰 `legacy/` 資料夾,那是舊系統
- commit 訊息用中文

寫的訣竅是具體到可以驗證:寫「用 2 空格縮排」而不是「格式排好看」;寫「commit 前跑 npm test」而不是「記得測試」。越具體,AI 越照做。

持續維護,不是寫完就丟

CLAUDE.md 是養出來的,不是一次寫死。判斷「什麼時候該加一條」很簡單:當你發現自己又在對話裡打同一句糾正、或 AI 第二次犯同樣的錯,就把它寫進 CLAUDE.md。

最省事的做法是直接跟 Claude 說:「把『改完 API 一定要更新對應的測試』這條加進 CLAUDE.md。」它會幫你寫進去。反過來,過期、用不到的規矩要主動刪掉——留著只會佔記憶、製造矛盾。

補充:寫給 AI vs 寫給人README 是寫給人看的說明書;CLAUDE.md 是寫給 AI 看的行為準則。你甚至可以在 CLAUDE.md 裡直接下命令,例如「回答一律用繁體中文」「除非我明講,否則不要順手重構其他程式碼」——它會當成每次開場的既定指令照著做。

進階:@ 匯入與子目錄各自的 CLAUDE.md

專案變大之後,你會想把規矩拆開整理。有兩個進階招式,新手先知道有,用得到再回來查:

進階整理:用 @ 匯入別的檔案,或在子目錄各放一份 CLAUDE.md

  • @ 匯入:在 CLAUDE.md 裡寫 @docs/style-guide.md,開場時就會把那個檔案一起展開載入,方便把長內容拆成多檔管理。相對路徑以「CLAUDE.md 自己的位置」為準,而且最多疊四層(A 匯入 B、B 再匯入 C…到第四層為止)。注意:@ 後面接路徑就會真的去匯入,如果你只是想在文字裡提到某個檔名、不想匯入它,要用反引號把它包起來(寫成 `@README`)。
  • 子目錄各放一份:大專案可以在 frontend/、backend/ 各放一個 CLAUDE.md,只寫該區的規矩。根目錄那份開場就載入,子目錄那份則是Claude 讀到該區檔案時才載入——這樣能省下平常用不到的脈絡空間。
再進階一點:.claude/rules/如果規矩多到想分主題管理,可以改用 .claude/rules/ 資料夾,把不同主題(測試、API、安全)拆成一檔一主題,甚至用 paths 設定讓某條規矩「只在改到特定檔案時才載入」。這是給大型專案的整理術,個人小專案先用單一 CLAUDE.md 就很夠。

常見坑

坑 1:CLAUDE.md 塞太多,AI 反而不聽話

新手直覺以為「寫越多它越懂」,結果剛好相反。CLAUDE.md 每次全份載入,塞成一本手冊會稀釋重點,重要規矩反而被淹沒,它就開始「選擇性遵守」。症狀是:明明寫了規矩,AI 卻常常沒照做。解法:回頭把它砍到 200 行內,只留 AI 猜不到、每次都需要的事;真的很多,就用上面講的 @ 匯入或 .claude/rules/ 拆檔。想確認哪些檔案這次真的被載入了,打 /memory 會列出來——沒出現在清單裡的檔案,AI 根本看不到。

坑 2:改了 CLAUDE.md,AI 卻好像沒吃到

你在對話中途改了 CLAUDE.md,或在對話裡口頭交代了一條規矩,結果 AI 沒反應、或過一陣子又忘了。兩個常見原因:一是子目錄的 CLAUDE.md 要 Claude 讀到那區檔案時才會載入,不是開場就吃;二是只在對話裡講、沒寫進檔案的指令,/compact(壓縮對話)之後會消失——只有專案根目錄的 CLAUDE.md 會在壓縮後被重新讀回來。解法:重要規矩一律寫進(根目錄的)CLAUDE.md,別只用嘴巴講;剛改完檔案沒生效,最保險是重開一次 Claude Code。

坑 3:@ 匯入沒作用,或不小心把整個檔案吸進來

用了 @ 匯入卻沒效果,常見兩種:第一次遇到外部匯入時 Claude Code 會跳一個核准對話框列出要匯入的檔案,如果你當時按了拒絕,匯入就會被停用、而且之後不會再問;另一種是路徑打錯或超過四層深度。反過來的坑是:你只是想在 CLAUDE.md 裡「提到」某個檔名,沒包反引號,結果 @ 開頭被當成匯入指令、把整份檔案吸進脈絡。解法:確認核准過、路徑對;純提及檔名時用 `@檔名` 包起來。

坑 4:把秘密寫進 CLAUDE.md,跟著 git 外洩

CLAUDE.md(專案那層)是會進 git、被團隊看到的檔案。有人圖方便把資料庫密碼、API 金鑰、內部網址直接寫進去當「背景資訊」,一 push 就外洩了。解法:秘密永遠不進會版控的檔案。私人、機密的內容放 ./CLAUDE.local.md,並確認它在 .gitignore 裡(跑 /init 選個人版會自動幫你加)。另外,如果你想留註解給人類看、又不想浪費 AI 的脈絡,可以用 HTML 註解 <!-- 這行給維護者看 -->——Claude 載入時會把區塊層級的 HTML 註解剝掉,不佔 token。

作業

  1. 生一份 CLAUDE.md:挑一個你手上的專案(沒有就用第 3 課做的那個),開 Claude Code 打 /init,看它自動生出草稿。
  2. 精修:打開那份草稿,刪掉「AI 一看程式碼就知道」的廢話,補上至少一條「AI 猜不到」的慣例或禁區(例如「commit 訊息用中文」「不要動 xxx/ 資料夾」)。目標:全份壓在自己讀得完的長度。
  3. 設一條個人偏好:在 ~/.claude/CLAUDE.md(沒有就新建)寫一行「回答一律用繁體中文」,重開 Claude Code,感受一下它跨專案都吃到這條。
  4. 看看它的筆記:打 /memory,瀏覽 Claude 幫你自動記了什麼(自動記憶),順便確認你的 CLAUDE.md 有出現在載入清單裡。
  5. 驗收:重開一個新對話,問它「這個專案用什麼技術、測試怎麼跑?」——如果它不用你講就答得出來,你的 CLAUDE.md 就成功了。

下一課預告

CLAUDE.md 讓 AI 記住「這個專案」的規矩。但如果你有一套流程——例如「幫我把一段訪談逐字稿整理成重點摘要」或「照公司格式產一份週報」——是想在很多專案、很多次都重複使用的呢?每個專案都複製一份 CLAUDE.md 顯然很蠢。

這時候需要的是 Skills(技能):把一套專業流程打包成一個模組,平常收在旁邊不佔記憶,AI 判斷需要時才自動載入來用。它比 CLAUDE.md 更聚焦、更可攜。下一課(第 5 課),我們就來把你最常重複的工作,一個一個打包成 Skill。

#Claude 新手指南#CLAUDE.md#Claude Code#AI 記憶

← 回所有文章