免費

CLAUDE.md 完整指南：讓 Claude Code 真正理解你的專案

手把手教你寫好 CLAUDE.md——從命令到架構、從禁止操作到檔案引用，以 Rails 實戰專案為例。

每次打開 Claude Code，它都是從零開始的——不記得上次對話，不知道你的專案是什麼，不知道測試指令是 rspec 還是 pytest，也不知道哪些操作絕對不能碰。

CLAUDE.md 解決這個問題。它是你寫給 Claude 的持久化說明書，每次對話開始前自動載入。寫好一份 CLAUDE.md，Claude 上來就能進入狀態，不問廢話，不犯低級錯誤。

放在哪裡

Claude Code 支援多層 CLAUDE.md，按位置分三級：

  • ~/.claude/CLAUDE.md：全域設定，對所有專案生效。放通用偏好，比如「不要自動提交 git」「回覆用繁體中文」。
  • 專案根目錄 CLAUDE.md：專案級設定，最常用。
  • 子目錄 CLAUDE.md：只在 Claude 處理該目錄時載入。適合給 frontend/、api/、infra/ 各自寫獨立說明。

多個 CLAUDE.md 疊加生效，層級越深越具體，下層可以覆蓋上層。

寫什麼

專案概覽

一段話說清楚專案是什麼、用什麼技術：

## Project Overview

**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.

- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)

注意版本號是寫進去的。Claude 知道是 Rails 8，就不會給你推薦 Rails 6 時代的寫法；知道有 4 個資料庫，寫遷移時就不會踩坑。

開發指令

這是 CLAUDE.md 裡最直接產生價值的部分。指令不寫清楚，Claude 只能靠猜——而它會猜錯。

## Development Commands

### Running the Application
bin/dev                  # Start Rails server (port 3000) + Tailwind watcher
bin/rails server         # Start Rails server only

### Testing
bundle exec rspec                                      # Run all tests
bundle exec rspec spec/models                          # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42         # Run test at line 42

### Linting & Security
bin/rubocop              # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a           # Auto-correct offenses
bin/brakeman             # Security vulnerability scan

### Deployment (Kamal)
bin/kamal deploy         # Deploy to production
bin/kamal app logs       # View application logs
bin/kamal app console    # Remote Rails console

這份指令清單讓 Claude 知道：測試用 bundle exec rspec 而不是 rails test，部署用 Kamal 而不是 Capistrano 或 Fly.io，linter 是 RuboCop 且已設定 Rails Omakase preset。這些細節不寫，Claude 全靠猜。

架構說明

架構說明的目的是記錄從程式碼裡看不出來的決策。程式碼結構 Claude 能自己讀，但為什麼這麼組織，它不知道。

## Key Architectural Patterns

**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.

**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.

**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.

這三條資訊讓 Claude 在加新功能時知道：業務邏輯不要堆在 controller 裡、權限檢查去 app/policies/ 找對應的 policy、需要非同步的操作用 Solid Queue 起一個 job。

領域模型按功能分組列出來也很有價值：

## Core Domain Models

**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)

這比讓 Claude 自己去掃描 app/models/ 目錄效率高，而且帶了業務語義（比如 400 分才是 VIP，這從程式碼裡不容易一眼看出來）。

非顯而易見的設定

這類資訊是最容易被忽視、但往往最關鍵的：

## Important Configuration

**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.

**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false

**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.

這三條全都是「不寫就踩坑」的資訊：多資料庫意味著遷移要明確指定目標庫；Lexxy 是 beta gem，行為跟標準 ActionText 有出入；用了 Propshaft 而不是 Sprockets，assets 處理方式不同。

禁止操作

這是被低估最多的部分。 明確告訴 Claude 什麼不能做，比反覆糾正它高效得多。

## Do Not

- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction

第一條幾乎所有專案都應該加。部署指令更要明確禁止——bin/kamal deploy 推錯了，影響的是正式環境。

引用其他檔案

CLAUDE.md 支援用 @ 引用其他檔案：

詳細部署設定見 @config/deploy.yml
資料庫結構見 @db/schema.rb

Claude 會在需要時讀取這些檔案。db/schema.rb 是 Rails 專案裡資料庫結構的單一來源，比讓 Claude 猜模型欄位準確得多。

常見誤區

寫太多：CLAUDE.md 佔用 context 視窗。只寫 Claude 從程式碼本身看不出來的東西。

規範寫得太籠統：「程式碼要寫得好」沒用。要具體：「controller 裡不要直接寫業務邏輯，放到 app/services/」。

忘記更新：從 Sprockets 換到 Propshaft 之後如果 CLAUDE.md 沒跟上，Claude 會按舊的理解操作。把更新 CLAUDE.md 納入重大重構的 checklist。

寫程式碼範例：程式碼範例佔空間，Claude 看真實程式碼比看範例更準確。用 @ 引用真實檔案。

起手模板（Rails 專案）

# [專案名]

[一句話描述]

- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL

## Development Commands

bin/dev              # Start server
bundle exec rspec    # Run tests
bin/rubocop          # Lint
bin/kamal deploy     # Deploy (ask before running)

## Architecture

[Services / Jobs / Policies 的分工]
[Domain models 按功能分組]

## Important Notes

[非顯而易見的設定、第三方 gem 的特殊行為]

## Do Not

- Do NOT run git commit automatically
[其他高風險操作]

從這個模板出發，按專案實際情況填充。不需要面面俱到，把最重要的幾條寫清楚就夠了——一份有 5 條關鍵資訊的 CLAUDE.md，遠比一份堆滿廢話的強。