M4：專案級 CLAUDE.md¶

目標：幫你的 todo-list 專案加一份 CLAUDE.md，下次回來繼續做時，Claude 一進來就知道狀況。時長：20 min

為什麼需要專案級 CLAUDE.md？¶

回想一下：M2 你寫的 Global CLAUDE.md，記錄了「你是誰、你的偏好」。但 Claude 不知道「這個專案是做什麼」。

舉個情境： - 你下週要修改 todo-list 加新功能 - 啟動 Claude，它看到一個叫 app.py 的檔案 - 它不知道這專案的目的、不知道你已經做過什麼改造、不知道為什麼選 JSON 不選 SQLite

所以每次你都要重新交代一遍。煩。

專案級 CLAUDE.md 就是放在這個專案根目錄的一份文件，讓 Claude 一進來就有 context。

對照：Global vs 專案級¶

	Global	專案級
位置	`~/.claude/CLAUDE.md`	專案根目錄 / `CLAUDE.md`
適用範圍	你所有專案	只有這個專案
該放什麼	個人偏好（語言、語氣）	專案脈絡（目的、技術棧、約束、決策紀錄）
機敏資料	絕對不行	看公司控管程度，可放專案內部細節
誰會看到	你自己（電腦上）	整個專案的協作者（如果用 Git 分享）

步驟 1：進入專案資料夾、啟動 Claude¶

你現在要做

WindowsmacOS

cd $HOME\Desktop\todo-list
claude

cd ~/Desktop/todo-list
claude

步驟 2：用 `/init` 讓 Claude 自動生成草稿¶

Claude Code 有一個內建指令叫 /init，會自動掃描專案、產生一份 CLAUDE.md 草稿。

你現在要做

在 Claude Code 對話框輸入：

/init

按 Enter。

你應該看到

Claude 會： 1. 用 Read / Grep / Glob 等工具掃過你的專案 2. 產生 CLAUDE.md 草稿，跳 Write tool 權限提示 3. 你選 Yes，檔案就建立了

Claude 跑 /init：依序顯示 Read app.py、Read README.md、Glob *.py、Read TASKS.md、Write CLAUDE.md，最後權限提示

草稿大概長這樣：

# Todo List

一個極簡的 Todo List CLI 工具。

## Tech Stack
- Python 3.12+
- 標準庫 only（無外部相依）

## Structure
- `app.py` — main CLI entry
- `todos.json` — data storage
- `README.md` — usage doc
- `TASKS.md` — improvement ideas

## Commands
- `python app.py add "..."` — add todo
- `python app.py list` — list all
- `python app.py done N` — mark done
- `python app.py remove N` — delete

## Data Format
`todos.json` is a list of dicts: `{"text": str, "done": bool}`

卡住了？

Claude 沒讀檔直接寫了一份空的 → 告訴它「請先讀過 app.py 跟 README.md 再寫」
草稿太長太詳細 → 告訴它「請縮到 30 行內，重點是脈絡而非完整文件」

步驟 3：看草稿、跟 Claude 對話補資訊¶

/init 出的是草稿，不是終稿。它只知道程式碼寫了什麼，不知道你為什麼這樣做、未來打算怎麼動。

你現在要做

打開新建的 CLAUDE.md 看一眼（Windows 用記事本、macOS 用 TextEdit 都行）。然後跟 Claude 對話補幾段：

跟 Claude 說

請幫我在 CLAUDE.md 加幾段：

「使用者」段：這個工具是給我（HR 同事）自己用的，記錄日常工作待辦

「設計決策」段：為什麼用 JSON 不用 SQLite — 因為我想用記事本直接看資料

「不要做的事」段：

不要加雲端同步（個人工具，不需要跨裝置）

不要改成 Web 版（CLI / GUI 已經夠用）

不要引入外部相依套件（保持「只要有 Python 就能跑」）

「最近改造」段：我在 M3a 加了 [你做的功能]

寫完貼整份內容給我看。

你應該看到

Claude 改完 CLAUDE.md，貼給你看。應該多了你交代的四段。

步驟 4：驗證效果（這步最有感）¶

光寫好還不算數。要看「Claude 真的有讀進去」。

你現在要做

結束目前 Claude Code 對話（/exit 或 Ctrl+C 兩次）
在同一個資料夾重啟：
```
claude
```
問它：

跟 Claude 說

不用看任何檔案、不用工具。請只憑你看到的 CLAUDE.md，告訴我：

這個專案是做什麼的？

為什麼用 JSON 不用 SQLite？

我做過什麼改造？

有哪些「明確不要做的事」？

你應該看到

Claude 直接回答上面四題，不用讀檔。

這就證明 CLAUDE.md 已經自動載入到 Claude 的 context 裡了。

步驟 5：對比體驗（強烈推薦做）¶

把 CLAUDE.md 暫時改名、感受沒有它時 Claude 有多茫然。

你現在要做

退出 Claude Code
改名：
```
mv CLAUDE.md CLAUDE.md.bak
```
重啟 Claude
問同樣的問題：「這個專案是做什麼的？為什麼用 JSON？」

你應該看到

Claude 會說「我需要看一下檔案才能回答」、然後跑去讀 app.py 自己推敲。它猜得到「這是 todo list」，但完全猜不到你的設計決策（為什麼選 JSON）跟改造歷史。

做完之後記得改回來

mv CLAUDE.md.bak CLAUDE.md

為什麼讓你做這個對比？

「有 vs 沒有 CLAUDE.md」的差異不做一次不會有感。做完這個對比，你會記得：以後任何要花 1 小時以上的小專案，都值得花 10 分鐘寫 CLAUDE.md。

進階：CLAUDE.md 該寫什麼？¶

寫得好的 CLAUDE.md 有幾個特徵：

✅ 該寫¶

目的：這個專案要解決什麼問題、給誰用
約束：技術選型的理由、不能用什麼
不要做的事：明確的紅線，避免 Claude 過度發揮
決策紀錄：為什麼選 A 不選 B（過幾個月你自己也會忘）
跑法：怎麼啟動、怎麼測試

❌ 不該寫¶

程式碼結構：Claude 自己 grep 就知道，寫了會 rot
完整 API 文件：留給 README.md 或 docstring
個人偏好：那是 Global 的事
機敏資料：除非專案在公司控管環境

黃金原則¶

寫「Claude 不看 code 就不會知道的事」。程式碼能說的，讓程式碼說。

M4 完成檢查¶

CLAUDE.md 存在於 todo-list/ 根目錄
內容包含：目的、約束、設計決策、不要做的事
重啟 Claude 後它能不看檔案就回答關於專案的問題
做過一次「改名 / 改回來」對比實驗
你能說出 Global vs 專案級 CLAUDE.md 的差別

✅ 全部 → 🎉 你結業了

結業！下一步呢？¶

你現在會： 1. 在自己電腦跑 Claude Code 2. 用對話方式建立小工具 3. 看懂 Claude 改的東西、跑得起來、修壞掉 4. 寫 Global + 專案級 CLAUDE.md 讓 Claude 「進入狀況」

接下來建議：

想做什麼	怎麼開始
改造你的 todo-list 加更多功能	看 `TASKS.md`，挑一個再做
做別的小工具	想一個你日常重複做的雜事（例如「整理 Excel 欄位」），跟 Claude 說「我想做一個 ...」
學更深的 Python	隨便挑一個你感興趣的小東西，請 Claude 教你做
把 todo-list 給同事用	做完 M3b 的 .exe 路徑，給他 `dist/app.exe`

給你一個離別贈禮¶

把這段話存起來，下次卡住時用：

卡住時的萬用 prompt

我在做 X 工具，遇到 Y 問題。

我已經試過： - [試過的方法 1] - [試過的方法 2]

錯誤訊息整段：
[貼整段 traceback]
請： 1. 解釋這個錯誤是什麼意思（白話） 2. 告訴我可能的 2-3 個原因 3. 列出怎麼診斷確認是哪一個 4. 對應的修法

這個 prompt 結構幾乎適用所有 debug 情境。

← M3b ｜回首頁

M4：專案級 CLAUDE.md¶

為什麼需要專案級 CLAUDE.md？¶

對照：Global vs 專案級¶

步驟 1：進入專案資料夾、啟動 Claude¶

步驟 2：用 /init 讓 Claude 自動生成草稿¶

步驟 3：看草稿、跟 Claude 對話補資訊¶

步驟 4：驗證效果（這步最有感）¶

步驟 5：對比體驗（強烈推薦做）¶

進階：CLAUDE.md 該寫什麼？¶

✅ 該寫¶

❌ 不該寫¶

黃金原則¶

M4 完成檢查¶

結業！下一步呢？¶

給你一個離別贈禮¶

步驟 2：用 `/init` 讓 Claude 自動生成草稿¶