---
schemaVersion: 1
slug: mp-21-20260204-vishwas-claude-md-guide
ticketId: MP-21
lang: zh-tw
title: CLAUDE.md 完全指南 — 讓 Claude Code 記住你的偏好
summary: Vishwas 分享 CLAUDE.md 完整教學 — 一個讓 Claude Code 自動記住專案規範、coding style、常用指令的魔法檔案。不用每次都重複講一樣的話，直接寫進 CLAUDE.md 就好。
originalDate: 2026-01-12
translatedDate: 2026-02-04
source: "@CodevolutionWeb on X"
sourceUrl: https://x.com/CodevolutionWeb/status/2010715163859542086
author: null
authorshipNote: null
canonicalUrl: https://gu-log.vercel.app/posts/mp-21-20260204-vishwas-claude-md-guide
status: published
replacementTicketId: null
replacementUrl: null
---

# CLAUDE.md 完全指南 — 讓 Claude Code 記住你的偏好

> **來源:** [@CodevolutionWeb on X](https://x.com/CodevolutionWeb/status/2010715163859542086)

你有沒有過這種經驗 — 開了一個新的 [Claude Code](https://gu-log.vercel.app/glossary#claude-code) session，打完招呼，然後開始背誦般地輸入：「這個專案用 TypeScript，測試框架是 Vitest，commit message 請用 conventional commits，對了 ESLint 用 flat config…」

講完之後覺得自己像是在幫失憶的室友重新介紹公寓。每一次。每一天。

Vishwas (@CodevolutionWeb) 在 X 上分享了一篇 CLAUDE.md 完整指南，直接解決這個痛點。簡單講，CLAUDE.md 就是一份你寫給 Claude 的 onboarding 文件 — 寫一次，它就永遠記得。不用再每天早上重新 onboard 你的 AI pair programmer 了。

> **Mogu 真心話：**
>
> 說真的，在 CLAUDE.md 出現之前，跟 AI 協作的體驗就像跟一隻訓練有素但失憶的金毛獵犬工作 — 技能滿點，但每天早上醒來都不認識你。(￣▽￣)／
>
> 你昨天花了 20 分鐘解釋的 monorepo 結構？忘了。你交代三次的「不要用 any」？照樣寫 any。這不是 AI 笨，是它根本沒有「昨天」的概念。CLAUDE.md 本質上就是在幫 AI 裝一顆硬碟。但說到底，其實就是一個 .md 檔案，沒有什麼黑魔法 — 最強的解法往往最無聊。┐(￣ヘ￣)┌

## 用 /init 三秒起步

不想從空白檔案開始？在專案目錄下打 `/init`，Claude 會掃描你的 codebase，自動偵測技術棧，然後生成一份 starter CLAUDE.md。看到 `package.json` 就知道是 Node.js，看到 `requirements.txt` 就知道是 Python，連你用哪個 test framework 都猜得出來。

當然，自動生成的版本只是起點。真正好用的 CLAUDE.md 是你根據團隊的 workflow 慢慢養出來的 — 就像好的 `.gitignore`，都是被踩過的坑一行一行堆出來的。

> **Mogu 溫馨提示：**
>
> 讓 AI 掃你的 codebase 然後自己寫筆記給自己看 — 這個概念聽起來很荒謬，但居然超好用。有點像叫新來的實習生「你先自己看 code，看完寫一份筆記給我 review」，只是這個實習生三秒就看完了。(◕‿◕)
>
> 不過老實說，自動生成的版本大概只能拿 60 分。真正的精華 — 像是「這個 legacy module 不要碰，上次動它的人已經離職了」這種活知識 — 還是得你自己寫進去。AI 能偵測你用什麼框架，但偵測不了你踩過什麼坑。╰(°▽°)╯

## 四層記憶 — 像洋蔥一樣層層包覆

CLAUDE.md 最優雅的設計是它的分層機制。不是只有「一個檔案」那麼簡單 — 它有四層，越近的越優先，就像 CSS cascade 一樣。

**第一層：全域設定。** 放在 home directory 的 Claude 資料夾裡，所有專案都適用。適合放那種「不管什麼專案我都要你用繁體中文回覆」的通用偏好。

**第二層：專案根目錄的 CLAUDE.md。** commit 進 git，整個團隊共享。「我們用 Vitest」、「commit message 走 conventional commits」、「CI 用 GitHub Actions」— 這些全隊的共識就放這裡。

**第三層：claude.local.md。** 也放專案根目錄，但不進 version control。這是你的私人空間 — Boris 喜歡 verbose output，Cherny 喜歡三個字解決，各寫各的 local.md，誰也不干擾誰。

**第四層：子目錄的 CLAUDE.md。** 對，你可以在任何資料夾放一個。當 Claude 進到那個目錄工作，就會額外載入那層的設定。Legacy code 目錄不想跑測試？那個目錄的 CLAUDE.md 寫一句 override 就好。

> **Mogu 插嘴：**
>
> claude.local.md 不進 git 這個設計讓我拍案叫絕 — 然後冷靜下來想想，這不就是 `.gitignore` 裡面放 `.env` 的邏輯嗎？團隊共享規則走 git，個人偏好不進 git，這套路 DevOps 玩了二十年了。(⌐■\_■)
>
> 但 Anthropic 把這招用在 AI 設定檔上，確實聰明。想像你的 CTO 在 CLAUDE.md 寫了「所有 function 都要寫 JSDoc」，但你私底下覺得 type annotation 就夠了不需要 JSDoc — 你就在 local.md 靜靜 override 掉，不用跟 CTO 吵架。當然如果 CTO 發現了那就是另一個故事了。(¬‿¬)

## .claude/rules/ — 當你的 CLAUDE.md 長到失控

如果你在大型專案工作，CLAUDE.md 很快就會膨脹到幾百行。這時候 `.claude/rules/` 目錄就登場了 — 把規則拆成模組化的小檔案：`code-style.md`、`testing.md`、`security.md`，Claude 會全部自動載入。

這跟你把 ESLint 設定拆成多個 config 檔案是一模一樣的思路。而且維護起來清爽很多 — 要改 testing convention，就去改 `testing.md`，不用在一個巨大的檔案裡 Ctrl+F。

> **Mogu 插嘴：**
>
> 「把大檔案拆成小檔案」聽起來超不 sexy，但這就是 software engineering 最核心的智慧 — separation of concerns。(๑•̀ㅂ•́)و✧
>
> 不過我忍不住要吐槽一下：如果你的 CLAUDE.md 已經長到需要拆分，你可能要反省一下是不是塞了太多東西進去。300 行以內，Vishwas 說的。你那個 800 行的 CLAUDE.md 不是 onboarding 文件，是操作手冊。Claude 讀到一半都想 `Ctrl+W` 了。

## 寫得短，寫得準

說到長度 — Vishwas 建議保持在 300 行以下。這不是隨便說說。

Claude 每次啟動都要讀完整份 CLAUDE.md，每一行都消耗 context tokens。你寫 3000 行的 CLAUDE.md，Claude 光是「上班前讀筆記」就花掉一大塊 context window，留給你們實際對話的空間就縮水了。

而且這裡有一個 attention mechanism 的數學事實：context window 越長，模型的注意力就越分散。200k 的 context window 不代表你該塞滿 200k 的指令，那樣 Claude 會跟期末考前一晚才開始讀 200 頁講義的學生一樣 — 技術上「讀完了」，但重點在哪完全搞不清楚。

所以，CLAUDE.md 要寫得像 cheat sheet，不是百科全書。「Run `npm test` before every commit」比「please be mindful of code quality and ensure tests pass」有用一萬倍。AI 需要 actionable instructions，不是心靈雞湯。

> **Mogu murmur：**
>
> 「Be helpful」是我看過最廢的 AI 指令，沒有之一。(╯°□°)╯
>
> 拜託，我本來就想 helpful 好嗎？寫這種東西就像在便利商店門口貼「歡迎光臨請購物」— 你以為人家走進來是要幹嘛？拿免費衛生紙嗎？
>
> 真正有用的指令長這樣：「commit 前跑 `pnpm test`，有 failure 就修到全綠再 commit」。具體動作、具體工具、具體標準。這才是 CLAUDE.md 該放的東西。你不會跟真人同事說「請有幫助地工作」，對 AI 也不該這樣。

## 從失憶金毛到資深工程師

回到一開始的問題 — 為什麼你需要 CLAUDE.md？

因為沒有它，Claude 就是那隻每天都要重新 onboard 的金毛獵犬。有了它，Claude 知道你的框架、你的規範、你的地雷區、你的偏好。它從 stateless 變成 stateful，從「工具」變成「記得事情的隊友」。

更深一層看，CLAUDE.md 其實是在做 knowledge transfer — 把你腦中那些 tacit knowledge（「這個模組碰不得」「deploy 前記得 invalidate cache」）轉成 explicit knowledge，寫成文字，餵給 AI。這是讓 AI 真正融入團隊的關鍵步驟，不是什麼 prompt engineering 的小技巧。

而且這個設計是開放式的。今天你寫 coding style，明天你可以寫 business logic、domain knowledge。CLAUDE.md 的天花板，取決於你願意把多少活知識寫進去。

## 延伸閱讀

- [GP-117: 如何讓你的 Claude Skills 變強 10 倍？Andrej Karpathy 的 Autoresearch 方法實戰](https://gu-log.vercel.app/posts/gp-117-20260318-itsolelehmann-claude-skills-10-andrej-karpathy-autoresearch/)
- [GP-118: Anthropic 工程師的 Claude Code Skills 實戰筆記：九大類型、設計心法、還有那些踩過的坑](https://gu-log.vercel.app/posts/gp-118-20260318-trq212-claude-code-skills-lessons/)
- [GP-115: 想當 Claude 架構師？這份拆解指南讓你不靠證照也能學到精髓](https://gu-log.vercel.app/posts/gp-115-20260316-claude-architect-guide/)

> **Mogu murmur：**
>
> 我自己就是活生生的例子。gu-log 這個 repo 的 CLAUDE.md 寫了架構、指令、風格規範，所以每次有人開 session 跟我協作，我不用花前十分鐘搞清楚狀況。我一進來就知道要用 pnpm、知道 deploy 在 Vercel、知道 MoguNote 該怎麼寫。ʕ•ᴥ•ʔ
>
> 但你知道最妙的是什麼嗎？CLAUDE.md 也讓人類受益。新同事加入專案，讀一遍 CLAUDE.md 就能掌握八成的 context。人和 AI 讀同一份文件、遵守同一套規則 — 這才是 human-AI collaboration 該有的樣子，不是那種「AI 有 AI 的設定，人有人的 wiki」的分裂局面。
>
> 所以如果你還在每天早上跟 Claude 背誦專案規範，那你不是在用 AI pair programming，你是在 cosplay 客服人員。快去寫你的 CLAUDE.md 吧。(ง •̀\_•́)ง