Claude Academy
載入中

CLAUDE.md 檔案

第 5 課3 分鐘

CLAUDE.md 為 Claude 提供新加入成員所需的背景資訊，涵蓋慣例、指令、架構，以及團隊最常見的錯誤。過去存在於人們腦中和 wiki 上的知識，變成了一個代理在每次會話開始時都會讀取的檔案，由整個團隊維護，並在每次出現錯誤時持續迭代。

開始使用

  • 先決條件：無。
  • 基礎設施：一個儲存庫、已安裝的 Claude Code，以及一位熟悉程式碼庫的工程師。

如何執行

  1. 在儲存庫中執行 /init。Claude 會根據其發現的內容生成一個初始的 CLAUDE.md。
  2. 將生成的檔案精簡為新加入成員在第一天所需的內容。保留建置、測試和 lint 指令、重要的慣例，以及 Claude 一直出錯的地方。
  3. 將 CLAUDE.md 提交到儲存庫根目錄的 Git 中，讓整個團隊共用同一個版本，並像審查程式碼一樣審查變更。
  4. 這裡有一個實用的規則：當 Claude 犯了兩次同樣的錯誤時，就將修正內容加入 CLAUDE.md。
  5. 保持在一頁以內，因為 Claude 會在會話開始時讀取全部內容，任何過時的內容都只是在佔用上下文而沒有任何好處。

實際樣貌

這個 CLAUDE.md 屬於一家保險公司客戶入口網站的儲存庫。保存理賠資料的較舊內部系統是 claims-core，而 intent/ 則保存每次變更的規劃檔案。

CLAUDE.md：

markdown
# Claims portal
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
- Run: make run (portal on :3000, claims-api on :8000)
## Conventions
- claims-api is Python 3.12 and FastAPI. portal is TypeScript and React.
- Every endpoint needs a test in claims-api/tests.
- Dates cross the API as ISO 8601, never as formatted text.
## Architecture
- portal/ is the customer site, claims-api/ is its backend, and
  intent/ holds the intent.md, spec.md and plan.md for each change.
- Only claims-api talks to claims-core. The portal never calls it.
- claims-core allows 50 requests a second. Cache reads; never poll it.
## Things Claude gets wrong
- Do not log request or response bodies in claims-api; they can hold PII.
- Do not bump dependency versions; the platform team owns them.

治理考量

CLAUDE.md 受版本控制，因此代理所遵循的指示是可審查且可稽核的。團隊慣例透過此檔案套用，對其的變更會記錄在 Git 歷史中，並由程式碼負責人在 PR 審查中核准這些變更。

如何衡量

  • 領先指標：Claude 重複犯下 CLAUDE.md 本應捕捉到的錯誤的頻率。對 CLAUDE.md 的修正或變更應在 Git 歷史中追蹤。
  • 落後指標：根據 PR 歷史，新團隊成員首次合併 PR 所需的時間。