Claude Code 的 CLAUDE.md：如何讓 AI 真正理解你的專案
隨著 AI Agent 開發模式逐漸普及，許多開發者開始使用 Claude Code 來協助撰寫程式、重構架構、分析專案。
但在實際使用時，你很快會遇到一個問題：
AI 並不了解你的專案架構與開發規則。
例如：
- 你的專案使用 Clean Architecture
- API 必須遵循 特定命名規則
- Repository 與 Service 的使用方式不同
- 特定資料夾不能修改
如果每次都要重新在 Prompt 裡說明一次，會非常浪費 Token，也容易遺漏資訊。
Claude Code 提供了一個解決方案：
CLAUDE.md
什麼是 CLAUDE.md
CLAUDE.md 是 Claude Code 專用的專案說明文件，用來告訴 Claude：
- 專案架構
- 開發規範
- 工具使用方式
- 重要限制
簡單來說：
CLAUDE.md就是 給 AI 看的 README
但與 README 不同的是，它的目的是：
讓 AI Agent 在整個開發過程中保持一致的理解。
CLAUDE.md 的基本用途
在 Claude Code 中，CLAUDE.md 會在 AI 執行任務時被讀取，用來提供 專案上下文（Project Context）。
常見用途包括：
1. 說明專案架構
例如：
project/
├─ api/
├─ service/
├─ repository/
└─ domain/
你可以告訴 Claude：
## Architecture
This project follows Clean Architecture.
- api: controller layer
- service: business logic
- repository: database access
- domain: core models
這樣 Claude 在生成程式碼時，就會遵循架構。
2. 定義開發規範
例如：
## Coding Rules
- Use dependency injection
- Do not access database directly in controller
- All database logic must go through repository
Claude 生成程式碼時就會遵守這些規則。
3. 定義工具使用方式
例如：
## Database
Database: SQL Server
Use Entity Framework Core for ORM.
或
## Logging
Use NLog for logging.
這對於你的情況特別重要，因為你的系統就是：
.NET + NLog
Claude 就不會亂用別的 logging library。
4. 定義 AI 的限制
例如：
## Restrictions
- Do not modify files under /generated
- Do not change database schema
避免 AI 誤修改重要檔案。
CLAUDE.md 的範例
一個簡單但實用的 CLAUDE.md：
# Project Overview
This project is a .NET backend system.
Language: C#
Framework: .NET 6
## Architecture
Clean Architecture.
Layers:
- API
- Service
- Repository
- Domain
## Coding Rules
- Controllers should be thin
- Business logic must be in service layer
- Database access must go through repository
## Logging
Use NLog for all logging.
## Database
Database: SQL Server
ORM: Entity Framework
## Restrictions
Do not modify files in /generated.
這樣 Claude 就能快速理解整個專案。
CLAUDE.md 的優點
使用 CLAUDE.md 有幾個很明顯的優勢。
1. 減少 Prompt 長度
如果沒有 CLAUDE.md，你的 Prompt 可能會變成：
This project is a .NET project using Clean Architecture.
Use NLog for logging.
Database is SQL Server.
Repository pattern is used.
...
但有了 CLAUDE.md 之後：
Implement user login API.
Claude 會自動帶入專案背景。
2. AI 產生的程式碼更一致
沒有 CLAUDE.md 時：
AI 可能會：
- 一次用 Repository
- 一次直接 SQL
- 一次用不同 logging library
有 CLAUDE.md 後：
AI 會遵守 統一的開發規則。
3. 降低 Token 成本
因為不需要在每個 Prompt 重複專案資訊。
這對 長時間使用 AI Agent 非常重要。
4. 適合團隊協作
如果團隊都使用 Claude Code：
CLAUDE.md 可以成為 AI 的開發規範文件。
CLAUDE.md 的缺點
雖然 CLAUDE.md 很有用，但也有一些限制。
1. 需要人工維護
如果專案架構改變：
CLAUDE.md 也需要更新。
否則 AI 會依照 過期資訊生成程式碼。
2. 文件品質會影響 AI 表現
如果 CLAUDE.md：
- 太簡單
- 不夠清楚
- 缺乏架構說明
AI 的理解仍然可能錯誤。
3. 無法完全取代 Prompt
CLAUDE.md 提供的是：
背景知識
但具體任務仍然需要：
Create a user login API.
CLAUDE.md 的最佳實務
如果你想讓 Claude Code 發揮最大效果，可以遵循幾個原則。
1. 保持簡潔
不要寫成 5000 行文件。
只保留：
- 架構
- 規範
- 限制
2. 使用清楚的章節
建議結構：
Project Overview
Architecture
Coding Rules
Tools
Restrictions
3. 不要寫太多細節
AI 不需要知道：
- 每個 API 的細節
- 每個 class 的用途
只需要 規則。
CLAUDE.md vs README
很多人會問：
既然有 README，為什麼還需要 CLAUDE.md？
差別如下：
| 文件 | 目的 |
|---|---|
| README | 給人類開發者 |
| CLAUDE.md | 給 AI Agent |
README 通常包含：
- 安裝方式
- 使用方式
- 專案介紹
而 CLAUDE.md 只關心：
AI 如何在專案中工作
總結
CLAUDE.md 是 Claude Code 中非常重要的一個機制，它讓 AI 能夠理解專案的：
- 架構
- 規範
- 工具
- 限制
透過良好的 CLAUDE.md 設計，你可以讓 AI：
- 產生更一致的程式碼
- 減少 Prompt 長度
- 降低 Token 成本
- 提升開發效率
在 AI Agent 開發模式 越來越普及的今天，CLAUDE.md 很可能會成為未來專案的一種標準配置。
留言
張貼留言