讓 Claude Code 讀懂你的專案:CLAUDE.md 與給對脈絡

上一課，你靠猜告訴 Claude Code「問題大概在 auth/session.ts」。它做對了，但你每次都得當人肉索引，很累。

這一課解決這件事：讓它自己讀懂你的專案。 它越懂你的 codebase，你越不用手把手指路。

先理解一個限制：它不是「記得」你整個 repo

很重要的一個觀念：Claude Code 不是把你整個 repo 都裝進腦袋。它一次能讀進來的內容有上限，這個上限叫 context window。它的做法是需要時去讀相關的檔，而不是把所有東西都含著。

這帶來一個反直覺但關鍵的原則：

給對，比給多重要。 把整個 repo 塞給它，不如指出真正相關的幾個檔——脈絡裡的雜訊越少，它越不會被無關的東西帶歪。

第一招：寫一份 CLAUDE.md

最省力的長期投資，是在 repo 根目錄放一份 CLAUDE.md。Claude Code 會自動讀它，把它當成這個專案的「給代理人的說明書」。

把那些你每次都得重講的事寫進去一次：

• 專案怎麼跑、怎麼測(npm run dev、npm test、用哪個 package manager)
• 程式慣例(命名、檔案結構、要遵守的 lint 規則、用 X 不用 Y)
• 邊界與雷區(哪些目錄是 generated 不要改、哪些動作要特別小心)
• 常用的領域知識(這個專案的核心概念、縮寫)

寫好之後，你不用每次交代任務都附一段「順帶一提，我們用 pnpm、測試在 __tests__、別動 dist/」——它已經知道了。CLAUDE.md 就是把你的好指令裡固定不變的那部分，存成一次。

第二招：讓它先探索，再動手

面對陌生或大的任務，別一上來就叫它改。先叫它讀和解釋:

「先別改任何東西。讀一下 payments/ 這個模組，告訴我退款流程怎麼運作、相關的檔有哪些、你覺得要改哪裡才能加上『部分退款』。」

讓它先把它的理解講給你聽。你確認方向對了，再讓它動手。這一步幫你抓出「它誤會了你的架構」的情況——在它改壞之前。它也能順便把相關檔讀進脈絡，接下來改起來更準。

第三招：給對檔案與範圍

當你知道相關的檔，直接指給它，別讓它從零搜：

• 「改 api/orders.ts 和它的測試 api/orders.test.ts，參考 api/users.ts 的寫法。」
• 「這個 bug 只在 web/ 這個 package，不用看 mobile/。」

指明範圍有兩個好處：它更不會跑歪去改不相關的東西，也省 context(省成本)。 范围越聚焦，首次就做對的機率越高。

動手：給你的 repo 寫一份 CLAUDE.md

挑你最常用 Claude Code 的那個 repo，花十分鐘：

1. 在根目錄建 CLAUDE.md。
2. 寫下：怎麼跑/測、程式慣例、不要碰的地方、這專案的核心概念。
3. 下次給任務時，看看你是不是不用再重講那些固定的事了。

你會發現，前期花十分鐘寫說明，之後每個任務都省下重複交代——而且它做得更準。

入門到這裡告一段落

兩課下來，你已經能：在乾淨工作區跑一個真任務、審 diff、並讓 agent 讀懂你的專案。這已經足以讓 Claude Code 在日常幫你做掉不少事。

接下來上手階段，把品質和控制力一起拉高。第一件事最關鍵：怎麼把任務講成一份它做得對的規格——同一個任務，講得清不清楚，結果天差地遠。

林子睿（編輯：廖玄同），《讓 Claude Code 讀懂你的專案:CLAUDE.md 與給對脈絡》，矽基前沿 [Si]gnals，2026-06-19。https://signals.tw/articles/claude-code-project-context/