專案說明檔：給 Agent 的工作手冊

上一堂的 spec.md 說明的是「這次要做什麼」。但還有一些事情是每次都一樣的：這個專案怎麼執行、測試用什麼指令、註解用什麼語言、哪些檔案不能碰。

如果每次開新對話都要重講一遍，很快就會累。更麻煩的是，你一忘記講，Agent 就照它的習慣做，結果不符合你的規矩。

說明檔是什麼？

說明檔是一份放在專案資料夾裡的 Markdown 文字檔，Agent 每次開始工作時會自動讀取它。你可以把它想成新同事到職第一天拿到的工作手冊。

• Claude Code 會讀專案裡的 CLAUDE.md。
• 許多其他工具（例如 OpenAI Codex、Cursor、GitHub Copilot 等）支援 AGENTS.md，這是多家工具共同採用的慣例。

名稱不同，寫法和用途幾乎一樣。各工具支援哪些檔名、放在哪裡會被讀取，可能隨版本更新，請以官方文件為準。

四個區塊就夠用

以前面的記帳程式為例，一份完整但簡短的 CLAUDE.md 可能長這樣：

# 記帳工具 expense-app

## 專案簡介
給個人使用的命令列記帳工具，資料存在 CSV 檔。
- main.py：處理使用者輸入與畫面輸出
- storage.py：讀寫 expenses.csv
- tests/：pytest 測試

## 常用指令
- 執行程式：`python main.py`
- 跑全部測試：`pytest`
- 跑單一測試檔：`pytest tests/test_storage.py`
- 環境：Windows 11、Python 3.12，使用專案內的虛擬環境 .venv

## 寫法慣例
- 只使用 Python 標準函式庫；要加新套件前先問我
- 函式要有型別提示（type hints）
- 註解和錯誤訊息用繁體中文
- 金額一律用整數（新台幣元），不用浮點數
- 每次修改後執行 `pytest`，全部通過才算完成

## 不要做的事
- 不要修改或刪除 expenses.csv，那是我真實的記帳資料；測試請用 tests/ 裡的範例檔
- 不要讀取或輸出 .env 的內容
- 不要自行執行 git push
- 不要為了讓測試通過而修改測試的預期結果，有疑問請先問我

專案簡介

一兩句話說明專案是什麼，再列出主要的檔案或資料夾。Agent 雖然會自己讀檔案，但有這段簡介，它能更快找到方向。

常用指令

這是 Agent 最常用到的區塊。怎麼執行、怎麼測試，寫得越精確越好，直接寫出可以複製執行的指令。

寫法慣例

把你的偏好寫下來。注意「金額一律用整數」這種規則：它看似小事，卻能避免浮點數造成的計算誤差，而 Agent 不會自己知道你想這樣做。

不要做的事

這是最重要的保護。真實資料、秘密檔案、會影響別人的動作（例如推送到 GitHub），都寫在這裡。第一單元學的安全底線，在這裡變成具體的規則。

寫得好的規則 vs 寫不好的規則

不太有用	比較有用
請寫出高品質的程式碼	每次修改後執行 pytest，全部通過才算完成
注意安全	不要讀取或輸出 .env 的內容
保持簡潔	函式超過 40 行就拆開
用好的命名	變數用英文 snake_case，例如 monthly_total

原則是：Agent 讀了之後，知道要具體做什麼、能不能檢查自己有沒有做到。

另外，說明檔要簡短。它每次都會被讀進上下文，太長的話，重要的規則反而容易被淹沒。只寫真正需要的。

怎麼開始寫

不用從空白頁開始。Claude Code 有一個 /init 指令，會讀取你的專案，幫你產生一份 CLAUDE.md 草稿。產生之後，一定要自己讀一遍，刪掉不正確或不需要的內容，補上你的紅線。

也可以直接請它幫忙：

讓說明檔跟著專案長大

說明檔最好的更新時機是：你發現自己第二次提醒 Agent 同一件事的時候。

例如你第二次說「測試資料不要用真實的 CSV」，就把它加進「不要做的事」。你也可以直接請 Agent 幫你更新：「把剛才這條規則加進 CLAUDE.md」。

幾週之後，這份說明檔會變成你專案最有價值的文件之一，不只對 Agent 有用，對未來的你、或接手的同事也一樣。