Free

CLAUDE.md 完全ガイド：Claude Code にプロジェクトを本当に理解させる

コマンド・アーキテクチャ・禁止操作・ファイル参照まで、Rails 実プロジェクトを例に CLAUDE.md の書き方を実践的に解説。

Claude Code を開くたびに、ゼロからスタートする——前回の会話も覚えていないし、プロジェクトが何をするものかも知らない。テストコマンドが rspec なのか pytest なのかも、絶対に触れてはいけない操作があることも知らない。

CLAUDE.md はこの問題を解決する。Claude に書き渡す永続的な説明書であり、会話のたびに自動で読み込まれる。きちんと書かれた CLAUDE.md があれば、Claude はすぐに仕事モードに入れる——余計な質問もなく、初歩的なミスもない。

どこに置くか

Claude Code は階層型の CLAUDE.md システムをサポートしており、3 つのレベルがある：

  • ~/.claude/CLAUDE.md：グローバル設定。すべてのプロジェクトに適用される。「git を自動コミットしない」「日本語で答える」などの共通設定を置く。
  • プロジェクトルートの CLAUDE.md：プロジェクト単位の設定。最もよく使われる。
  • サブディレクトリの CLAUDE.md：そのディレクトリのファイルを扱うときだけ読み込まれる。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)

バージョン番号を明記することが重要だ。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 は知る：テストは rails test ではなく bundle exec rspec；デプロイは Capistrano や Fly.io ではなく Kamal；リンターは Rails Omakase プリセットで設定された RuboCop。これを書かないと 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.

この 3 点で Claude は理解する：ビジネスロジックをコントローラに詰め込まない；権限チェックは app/policies/ の対応ポリシーを参照する；非同期処理は 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.

この 3 点はすべて「書かないと必ずはまる」情報だ：マルチデータベースではマイグレーションのターゲットを明示しなければならない；Lexxy はベータ版 gem で、標準の ActionText と挙動が異なる；Propshaft は Sprockets と動作が違う。知らずにいると 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

1 番目の項目はほぼすべてのプロジェクトに必要だ。デプロイコマンドはさらに重要——bin/kamal deploy を誤って実行すれば、本番環境に直撃する。

他のファイルを参照する

CLAUDE.md は @ 参照で他のファイルを引き込める：

デプロイ設定の詳細: @config/deploy.yml
データベーススキーマ: @db/schema.rb

Claude は必要に応じてこれらのファイルを読む。db/schema.rb は Rails プロジェクトでのデータベース構造の唯一の真実のソースであり、Claude がモデルのフィールドを推測するよりはるかに正確だ。

よくある間違い

書きすぎ：CLAUDE.md はコンテキストウィンドウを消費する。README をまるごと貼り付ければ、Claude が実際のコードを扱う余地が減る。Claude がコードベースを読んでも導き出せないことだけを書く。

曖昧なガイドライン：「良いコードを書く」は役に立たない。具体的に：「ビジネスロジックを直接コントローラに書かない——app/services/ に委譲する」。

更新を忘れる：Sprockets から Propshaft に移行した後、CLAUDE.md が追いつかなければ Claude は古い前提で動く。CLAUDE.md の更新をリファクタリングのチェックリストに組み込む。

コードサンプルを書く：サンプルはコンテキストを食い、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 の役割分担]
[ドメインモデルを機能別にグループ化]

## Important Notes

[直感に反する設定、gem の特殊な挙動]

## Do Not

- Do NOT run git commit automatically
[その他のハイリスク操作]

このテンプレートから始めて、プロジェクトの実態に合わせて埋めていく。網羅する必要はない——5 つの的確な情報が書かれた CLAUDE.md は、冗長な内容で膨らんだものより何倍も価値がある。