有了 CLAUDE.md 還需要 README 嗎？
核心結論：兩者分工不同，各司其職，都值得好好寫。README 是給人類看的入職手冊，CLAUDE.md 是給 AI agent 看的規則書。延伸閱讀：Claude.md 的使用與優點。
README 與 CLAUDE.md 的定位
README 最終還是回到由人類開發者閱讀，主要回答「這個專案是什麼」，需要說明：專案內容、技術選用、如何啟動、環境要求、license、功能描述。
CLAUDE.md 則負責用命令式語句簡述：技術選用、一段啟動用的 code、coding style、git rule、如何開始開發等，回答「你（AI）必須做什麼」。
內容該放哪裡
| Content | README.md | CLAUDE.md | Neither |
|---|---|---|---|
| What the project is | Yes | ||
| Tech stack versions | Yes | Yes (compressed) | |
| Startup commands | Yes (step by step) | Yes (one code block) | |
| Environment requirements (Node >= 20) | Yes | ||
| Git commit rules | Yes | ||
| Coding conventions | Yes | ||
| Testing conventions | Yes | ||
| Development workflow | Yes | ||
| Roadmap / TODO | Yes (use Issues) | ||
| License | Yes | ||
| Feature descriptions | Yes |
常見問題
Q：是否該 commit CLAUDE.md？ A：是。應該分享 AI 協作標準，就像 eslint、prettier 等基礎設定一樣。
Q：CLAUDE.md 還是 AGENTS.md？ A：若要考慮多個 AI 工具的支援，可以使用 AGENTS.md，並在 CLAUDE.md 內用指標指向 AGENTS.md。
Q：CLAUDE.md 該多長？
A：不該超過 300 行，更多行數只會造成效率降低；可以用 @ 來匯入檔案。
Q：README.md 是否應提及 CLAUDE.md？ A：否。如同 eslint config 也不會在 README.md 被提到。
對照總結
| README.md | CLAUDE.md | |
|---|---|---|
| In one sentence | Onboarding handbook for humans | Rulebook for AI agents |
| Core question | ”What is this project? How do I run it?" | "What must you do?” |
| Writing style | Expository | Imperative |
| Industry trend | Stable | Converging toward AGENTS.md standard |
Each file handles its own job. A well-written README lets a new developer run the project in 5 minutes. A well-written CLAUDE.md lets AI follow your conventions without repeating “remember to push” or “remember to filter by merchant_id” every session. Neither is hard to write. Both are worth writing well.
CLAUDE.md 範例（命令式語句）
# Repository Guidelines
- Repo: `git@example.com:myteam/erp.git`, branch: `main`
- Monorepo: cross-border e-commerce multi-tenant SaaS admin
## Project Structure
- Frontend: `frontend/` (Vue 3.5 + TypeScript 5.8 + Vite 6.3 + Ant Design Vue 4.2 + Pinia)
- Backend: `backend/` (Django 5.2 + DRF 3.16 + SimpleJWT + MySQL 8.0 + Qiniu storage)
## Coding Style
### Backend
- All models inherit `TimestampedModel` + `SoftDeleteModel`.
- All business data must include `merchant_id` field (multi-tenant isolation).
- ViewSet `get_queryset` must filter by `merchant_id`.
## Commit & Push Guidelines
- Commit + push immediately after completing a feature.
- **After commit, you MUST `git push`. Never commit without pushing.**
- Commit message format: `type: short description`