CLAUDE.md：放哪裡、怎麼載入、怎麼寫

放在哪裡，就對誰生效

工作目錄以及它的所有上層目錄中的 CLAUDE.md 與 CLAUDE.local.md 會在啟動時載入；子目錄裡的則是在 Claude 讀到該目錄下的檔案時才載入。如果在大型 monorepo 裡會撈到其他團隊的 CLAUDE.md，可以用設定 `claudeMdExcludes` 寫 glob 排除。

該寫什麼、不該寫什麼

官方給的判準很清楚：把「你遲早會再解釋一次」的內容寫進去。具體的觸發時機是——同一個錯誤被犯第二次、程式碼審查抓到 Claude 本來就該知道的事、你又打了一次上次打過的更正、新同事也需要同一段說明。出現其中任何一項，就是該補的時候。

• 要寫：建置與測試指令、資料夾結構、命名慣例、「一律要做 X」這類規則。
• 不要寫：多步驟的操作流程，以及只影響程式碼某一小塊的規定。前者應該做成 skill，後者放進 `.claude/rules/` 的路徑限定規則。
• 要具體：寫「縮排用兩個半形空格」而不是「把程式碼排整齊」；寫「commit 前執行 `npm test`」而不是「記得測試」。
• 不要自相矛盾：兩份檔案講反話時，模型可能會任選其一。

用 @import 拆檔

用 `@path/to/file` 可以引入其他檔案。相對路徑是相對於寫下該 import 的檔案，而不是工作目錄；被引入的檔案還可以再引入別的檔案，最多四層。有個容易誤會的地方：被引入的檔案同樣會在啟動時展開進上下文，所以拆檔是為了整理，並不會節省上下文。

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

已經有 AGENTS.md 的儲存庫

Claude Code 讀的是 CLAUDE.md，不是 AGENTS.md。如果儲存庫已經為其他代理程式維護了一份 AGENTS.md，官方建議的做法是建立 CLAUDE.md 並用 `@AGENTS.md` 把它引入，這樣兩邊讀到同一份內容，不必雙重維護，還能在下面補上 Claude 專用的指示。在 Windows 上建立符號連結需要系統管理員權限或開發人員模式，所以用 import 的方式比較保險。

@AGENTS.md

## Claude Code

src/billing/ 底下的修改一律使用計畫模式。

用路徑限定規則省上下文

CLAUDE.md 變長之後，把主題拆進 `.claude/rules/`。在 YAML frontmatter 寫 `paths` 的規則，只有在 Claude 讀到符合樣式的檔案時才會載入；沒有 `paths` 的規則則無條件載入，優先度與 `.claude/CLAUDE.md` 相同。

---
paths:
  - "src/api/**/*.ts"
---

# API 開發規則

- 所有端點都要做輸入驗證
- 錯誤回應使用統一格式