Claude Code の CLAUDE.md でプロジェクト文脈を共有する

概要

Claude Code は、ターミナル・IDE・Web から使えるコーディング支援エージェントです。導入して最初に効果が高い一手が CLAUDE.md の整備です。これはプロジェクトのルートなどに置くだけで、エージェントがセッション開始時に自動で読み込む「常駐コンテキスト」ファイルです。

チャットのたびに「このプロジェクトは○○で、テストは△△で……」と説明し直すのは非効率です。CLAUDE.md に前提を書いておけば、エージェントはその文脈を踏まえて回答・実装します。本記事では、基本・階層マージ・書き方・運用の勘所までをハンズオン形式でまとめます。

環境

• Claude Code（CLI / IDE 拡張 / デスクトップ / Web いずれでも同じ考え方）
• 対象プロジェクトは任意（サンプルは架空の Web アプリ）

発生した問題

CLAUDE.md を使う前は、次のような文脈の欠落が繰り返されがちです。

• プロジェクト固有のディレクトリ構成を無視した提案が来る
• テストフレームワークやリンターの流儀を守らない
• コミット・ブランチ命名の規約が毎回守られない
• 「本番 DB には直接触らない」といった安全上の約束を都度伝える必要がある

人間なら暗黙に共有している「このプロジェクトのお作法」が、エージェントに渡っていない状態です。

原因

エージェントは各セッションで、原則としてリポジトリをゼロから探索します。規約・制約・優先順位といった判断基準は、コードを読むだけでは復元しきれません。この「毎回失われる暗黙知」を明示的なファイルとして固定するのが CLAUDE.md の役割です。

対応方法

1. まず雛形を作る

プロジェクト直下で初期化コマンドを実行すると、コードベースを走査して下書きを生成できます。

# プロジェクトのルートで
claude
# 対話内で
/init

生成物は叩き台です。ここから「毎回伝えたい前提」に絞って人間が削り込みます。

2. 配置場所と読み込みの階層

CLAUDE.md は複数階層で使え、より近い（プロジェクト側の）指示が優先されます。

配置場所	役割	共有範囲
ホーム配下（ユーザー全体）	自分の作業スタイル全般	全プロジェクト
プロジェクトのルート	そのプロジェクトの前提・規約	チーム共有（コミット対象）
サブディレクトリ	領域固有の細かい約束	その配下だけ

チーム共有はコミットし、個人的な好みはユーザー全体側に置く使い分けが基本です。

3. 「効く」書き方の原則

• 抽象論ではなく、具体的なコマンド・パス・手順を書く
• 「やること」と同じ重みで「やってはいけないこと」を書く
• テストランナー等、迷いやすい分岐を先回りで潰す
• 常駐コストなので、長さより密度を優先する

4. インポートで分割する

ルールが増えたら、CLAUDE.md を肥大化させず別ファイルへ分割し、参照で取り込みます。

.
├── CLAUDE.md                    # 入口。全体方針と各ルールへの参照
└── .claude/
    └── rules/
        ├── git-operation.md     # Git 操作の安全ルール
        ├── testing.md           # テストの流儀
        └── security.md          # 秘密情報の取り扱い

実装例

架空の予約管理 Web アプリを例にした CLAUDE.md です。

# プロジェクト概要

架空の予約管理 Web アプリ。バックエンドは Laravel、フロントは React + TypeScript。

## ディレクトリ構成
- `app/` — Laravel アプリ本体
- `resources/js/` — React フロントエンド
- `tests/` — Pest によるテスト

## コマンド
- 依存インストール: `composer install && npm install`
- テスト: `./vendor/bin/pest`（PHPUnit は使わない）
- 静的解析: `./vendor/bin/phpstan analyse`
- フロントのビルド: `npm run build`

## コーディング規約
- コミットは Conventional Commits（`feat:` `fix:` `chore:` など）
- ブランチ名は `feature/xxx` / `fix/xxx`
- PR を作る前に必ず Pest と phpstan を通す

## やってはいけないこと
- 本番 DB に対する直接の更新・削除は提案しない
- `.env` の中身を出力・コミットしない
- API キー・接続情報を含むコードを生成しない
- 破壊的な Git 操作（`reset --hard` / `push --force` 等）は事前確認なしに実行しない

肝は、エージェントが独断で走ると困ることを 禁止事項として先に固定 しておく点です。特に本番環境や秘密情報まわりのガードレールは、事故防止の意味で価値があります。

確認方法

1. Claude Code を起動し、規約に反する指示をわざと出す（例:「PHPUnit でテストを書いて」）
2. エージェントが CLAUDE.md の記載（Pest を使う）に沿って軌道修正するか見る
3. コマンド系を頼み、書いたコマンドをそのまま使うか確認する

期待どおりに参照されない場合は、指示が長すぎて埋もれている / 抽象的すぎる / 配置階層が想定と違う、を疑います。

注意点

• 常時読み込まれる前提なので、恒久的な情報に絞る。一時的な作業指示はチャットで渡す
• チーム共有分はコミット、個人の好みはユーザー全体側へ置きリポジトリを汚さない
• 秘密情報（.env の値・キー・接続情報）は CLAUDE.md にも書かない。「触れさせない」設計にする
• 一度書いて終わりにせず、誤解した箇所を見つけたら追記していく運用資産と捉える

まとめ

• CLAUDE.md は毎セッション失われる暗黙知を固定する常駐コンテキスト
• /init で雛形を作り、判断に直結する箇条書きへ削り込む
• 階層マージでチーム共有分と個人設定を分ける
• 「やってはいけないこと」を明記して事故を防ぐ
• 肥大化したら参照インポートで分割する

小さく始めて、エージェントの挙動を見ながら育てていくのがおすすめです。