CLAUDE.md 起手 — 把專案規則一次講清楚

用途

讓 Claude Code 讀完你的專案後，反過來幫你草擬一份 CLAUDE.md ── 把「這個專案該怎麼做事」的規則、慣例、禁忌寫成文件，之後每次對話都自動載入。

何時用

• 適合：剛把 Claude Code 接上一個既有專案、團隊規則散在各人腦袋裡、想讓 AI 產出穩定一致。
• 不要用：一次性腳本或玩具專案 ── 寫 CLAUDE.md 的成本不划算，直接對話就好。

Prompt

請先讀過這個專案的結構（package.json / 主要資料夾 / README / 既有設定檔），
然後幫我草擬一份 CLAUDE.md。

我要它涵蓋：
1. 專案一句話定位 + 主要技術棧
2. 資料夾職責（哪個資料夾放什麼、邊界在哪）
3. 開發慣例：命名、commit 訊息格式、測試怎麼跑
4. 重要指令（安裝 / 開發 / build / 部署）
5. 「做這件事的禁忌」：哪些檔案不要動、哪些操作要先問我

規則：
- 用條列、精簡，不要長篇大論
- 規則要可執行（能被你照著做），不要寫空泛原則
- 不確定的地方先標 TODO，列出來問我，不要自己編
- 用繁體中文寫說明，程式碼/指令保留原文

先給我草稿，我們再一起修。

範例 / 變體

• 既有專案：直接在專案根目錄開 Claude Code 跑這句，它會邊讀檔邊草擬。
• 變體（團隊版）：加一句「另外列出 3 條最容易被新人踩雷的規則，放到最上面」。
• 變體（精簡版）：「先只寫前 3 點，其他之後補」── 避免一次產出太長沒人看。

🎯 範例輸出（實測）

在 Claude Code 跑這句、在一個 Python FastAPI 專案根目錄執行的結果：

點開看 AI 實際輸出

Claude Code 掃描專案結構後草擬的 CLAUDE.md 節錄如下：

---

專案定位

訂單管理 API — 使用 FastAPI + PostgreSQL，提供訂單查詢、建立與發票開立功能，供前端 Next.js App 與 n8n 工作流呼叫。

技術棧：Python 3.12 / FastAPI / SQLAlchemy 2 / Pydantic v2 / PostgreSQL 15 / uv

---

資料夾職責

• src/api/ — 路由與 endpoint（只放 HTTP 層邏輯）
• src/services/ — 業務邏輯（跨 router 共用，不得直接操作 DB）
• src/models/ — SQLAlchemy ORM model（不放業務規則）
• src/schemas/ — Pydantic 請求/回應 schema
• tests/ — pytest 測試，目錄結構鏡射 src/

---

開發慣例

• 命名：snake_case（Python）、kebab-case（URL 路徑）
• Commit 格式：feat(scope): 簡短描述 / fix(scope): ...
• 測試：uv run pytest -v；新功能必須附帶測試，覆蓋率不得低於 80%

---

重要指令

uv sync && uv pip install -e .   # 安裝依賴
uv run uvicorn src.main:app --reload  # 本地開發
uv run pytest                    # 跑測試
uv run ruff check . && uv run ruff format .  # Lint + 格式化

---

禁忌清單

• 禁止直接在 src/api/ 裡寫 SQL 或 DB 查詢邏輯
• 禁止 pip install，統一用 uv
• 禁止 hardcode 任何 API Key 或密碼，一律用 .env
• 修改 src/models/ 後必須產生 Alembic migration，不要手動改 DB schema

---

TODO（等確認後補入）：

• [ ] 這個 API 的 rate limit 策略是什麼？
• [ ] 生產環境部署在哪裡（GCP / AWS / 自架）？

💡 實測心得：Claude Code 讀完 pyproject.toml 後通常能自動推斷技術棧，最有價值的是「禁忌清單」——它會根據你的設定檔（例如 .ruff.toml）猜測你的規範，但業務邊界（例如「哪些檔案不能動」）需要你確認，不要直接接受 AI 的猜測。

延伸

• 寫好 CLAUDE.md 是領域金字塔 做（標準化） 層的第一步：把判斷規則外化成文件。
• 想再進一步，可看「程式」場景裡的 Skills / SOP 類提示語，把更細的流程也外化。