免费

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 不知道这些，就会按默认假设来操作，然后出错。

禁止操作

这是被低估最多的部分。 明确告诉 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

第一条几乎所有项目都应该加。Claude Code 默认不会自动提交，但如果你不写，它在某些情况下可能会尝试。部署命令更要明确禁止——bin/kamal deploy 推错了，影响的是生产环境。

引用其他文件

CLAUDE.md 支持用 @ 引用其他文件：

详细部署配置见 @config/deploy.yml
数据库结构见 @db/schema.rb

Claude 会在需要时读取这些文件。适合把大块参考内容拆出去，保持 CLAUDE.md 简洁。db/schema.rb 是个特别好的引用目标——Rails 项目里它是数据库结构的单一来源，比让 Claude 猜模型字段准确得多。

常见误区

写太多：CLAUDE.md 占用 context 窗口。把整个 README 粘进去，Claude 处理实际代码的空间就少了。只写 Claude 从代码本身看不出来的东西。

规范写得太宽泛：「代码要写得好」没用。要具体：「controller 里不要直接写业务逻辑，放到 app/services/」。

忘记更新：从 Sprockets 换到 Propshaft、从 Sidekiq 换到 Solid Queue，这类迁移之后如果 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，远比一份堆满废话的强。