CLAUDE.mdの書き方：複数プロジェクトをClaude Codeで管理する実践構成

Claude Codeを使い始めて数ヶ月、手元のプロジェクトはいつの間にか15を超えていました。Webアプリ、モバイルアプリ、MCPサーバー、個人サイト、分析スクリプト——それぞれ技術スタックも規約も違います。

最初はプロジェクトごとにCLAUDE.mdを書いていましたが、同じ記述が各ファイルに散らかっていく非効率に気づきました。「ESModulesを使う」「anyは使わない」「Voltaでバージョン管理」——これを10個のリポジトリに書くのは明らかに間違いです。

試行錯誤を重ねて今は落ち着いた構成があります。グローバルCLAUDE.md → rules/分離 → プロジェクト別CLAUDE.md → AGENTS.md分離、という4層の設計です。この記事では、その全体像と実際に使っている10個のノウハウを紹介します。

1. グローバルCLAUDE.mdで開発哲学を統一する

プロジェクトごとにCLAUDE.mdを書くと、「シンプル第一」「根本原因を見つける」といった基本姿勢を毎回書くことになります。書き忘れたプロジェクトではエージェントの振る舞いがブレます。

~/.claude/CLAUDE.md にグローバルな開発哲学を書くと、全プロジェクトで自動的に読み込まれます。自分のグローバルCLAUDE.mdには4つの原則だけを置いています。

## Core Principles
- シンプル第一: 最もシンプルな解決策をまず試す。過剰設計しない
- 根本原因を見つける: 表面的な対処ではなく、根本原因を特定して修正する
- 影響を最小化する: 変更の影響範囲を最小限にとどめる
- "スタッフエンジニアはこれを承認するか？" という自問を習慣化する

最後の一行が効いています。エージェントに品質基準を意識させる効果があります。プロジェクト固有の事情はプロジェクト別CLAUDE.mdに委ねて、ここには普遍的な原則だけを置くのがポイントです。

2. ~/.claude/rules/ でトピック別にルールを分離する

グローバルCLAUDE.mdが肥大化し始めたら、~/.claude/rules/ ディレクトリにトピック別のMarkdownファイルを切り出します。グローバルCLAUDE.mdから @~/.claude/rules/code-quality.md のように @ import 記法で明示的に参照することで読み込まれます。

自分の現在の構成はこうなっています。

~/.claude/rules/
├── code-quality.md    # ESM, strict TS, 命名規則, テスト方針
├── tech-stack.md      # Node.js, Expo, Supabase, Vercel の共通設定
├── supabase-shared.md # 共有DBのスキーマ分離ルール
├── agent-delegation.md # サブエージェントの使い分け
└── learned-patterns.md # 対話で学んだパターンの蓄積

code-quality.md には「ES Modulesを使う」「anyは使わない」「テストはVitest」といった、どのプロジェクトでも適用したいルールを書きます。tech-stack.md にはVolta、EAS Build、Vercelデプロイの注意点など、技術スタック固有の知識を集約します。ファイルを分けることで、特定のルールを探すのも更新するのも楽になります。

3. 共有リソースの境界をルールで明示する

複数プロジェクトがひとつのSupabaseプロジェクトを共有していると、あるプロジェクトの作業中に別プロジェクトの設定を壊すリスクがあります。特にAuth設定やmigrationは危険です。

共有リソースの境界と注意事項を専用のルールファイルに書くと、エージェントが自動的に考慮してくれます。supabase-shared.md に書いている内容の例です。

## Schema Separation
- megulus: `public` スキーマを使用
- entrepreneur-diary: `diary` スキーマを使用
- powerspots: `powerspots` スキーマを使用

## Config Push の注意
`supabase config push` は auth 設定を含むため、一方のプロジェクトから
実行すると他方の設定を上書きするリスクがある。

これがあると、エージェントがmigrationを作るときにスキーマを間違えません。config push の前に確認を促してくれることもあります。共有リソースの「地雷」を事前にマップしておく感覚です。

4. プロジェクト別CLAUDE.mdは引き継ぎ資料の感覚で書く

プロジェクト別CLAUDE.mdに何を書けばいいか迷いがちです。書きすぎると冗長、書かなすぎるとエージェントがプロジェクトの文脈を理解できません。

「新しいチームメンバーに初日に渡す引き継ぎ資料」を書く感覚で作るとちょうどよいです。プロジェクトの全体像、技術スタック、開発・デプロイ手順、主要ドキュメントへのポインタがあれば十分です。自分のプロジェクト別CLAUDE.mdはこの構成にしています。

# プロジェクト名
一行の説明。

## クイックリファレンス
- デプロイ: コマンドと手順
- 本番URL
- 開発: ローカル起動コマンド

## 技術スタック
箇条書きで列挙

## 主要ドキュメント
- AGENTS.md … デプロイ詳細
- その他の重要ファイルへのリンク

「クイックリファレンス」を冒頭に置くのがポイントです。エージェントが最初に読む部分なので、頻繁に使う情報を上に持ってきます。詳細はAGENTS.mdや他のファイルに分離します。

5. Memoryで会話をまたいだコンテキストを蓄積する

Claude Codeの会話はセッションごとにリセットされます。前回の会話で決めたことや発見した事実が、次の会話では失われます。

Memory機能を活用すると、重要な決定事項や発見を次の会話でも参照できます。自分のプロジェクトのMemoryには、こんな情報が蓄積されています。

## ブログ記事のソース
- WordPress移行: `source: "wordpress"`
- note移行: `source: "note"` — ファイル名が `note-nxxxxxx.md` のハッシュ形式
- 新規: `source: "original"`

## SEO改善 (2026-03-09実施)
- `/blog/tech/` 404 → `/blog/category/tech/` リダイレクト追加
- 高インプレッション記事4件の draft解除

「なぜこのslug形式なのか」「なぜこのリダイレクトがあるのか」といった文脈が、会話をまたいで保持されます。新しい会話でブログ記事を扱うとき、エージェントはこのMemoryを参照して適切な判断ができます。

6. サブエージェントでコンテキストウィンドウを節約する

大規模なコードベースの調査や、複数ファイルの横断的な変更で、コンテキストウィンドウが圧迫されます。長い会話の後半ではエージェントの精度が落ちることがあります。

独立したタスクはサブエージェントに委任します。サブエージェントは独自のコンテキストウィンドウを持つため、メインの会話のコンテキストを消費しません。グローバルCLAUDE.mdに以下のルールを書いています。

## Workflow
- サブエージェントを使ってコンテキスト圧迫を防ぐ
- メインセッションは監視・指示出し・レビューに徹する

「全ファイルのimport文をES Modulesに変換して」のような大量の機械的変更は、エージェントが自動的にサブエージェントを活用する判断をします。メインの会話ではアーキテクチャの議論に集中できます。

7. Planモードで複雑なタスクの手戻りを防ぐ

3ステップ以上の複雑なタスクで、エージェントがいきなりコードを書き始めて方向を間違えると、大きな手戻りが発生します。

複雑なタスクはPlanモードで開始します。エージェントに実行計画を立てさせ、承認してから実装に入ります。グローバルCLAUDE.mdに以下を書いています。

## Workflow
- 複雑なタスク（3ステップ以上）は Plan モードで開始する
- 途中でうまくいかなくなったら、無理に進めずすぐに立ち止まって再計画する

「途中で立ち止まって再計画する」の一文が重要です。計画通りに進まないとき、エージェントが無理やり元の計画に固執して泥沼にはまるケースを防げます。Plan → 実行 → 問題発生 → 再Plan、というサイクルを回します。

8. AGENTS.mdにデプロイ手順を分離する

CLAUDE.mdにデプロイ手順を書くと、日常的な開発タスクでもデプロイ情報がコンテキストに入ります。情報が多すぎるとエージェントの注意が分散します。

デプロイ手順やCI/CD関連の情報はAGENTS.mdに分離します。CLAUDE.mdからはポインタだけ残します。

## クイックリファレンス
- デプロイ: `git push origin master` → Vercel が自動デプロイ（詳細は AGENTS.md）

AGENTS.mdにはVercelの制限事項、--archive=tgz オプションの必要性、手動デプロイの手順などを詳しく書きます。デプロイ関連のタスクのときだけ、エージェントがAGENTS.mdを参照します。

9. Voltaでランタイムバージョンを固定する

プロジェクトによってNode.jsのバージョンが異なります。手動で切り替える必要があると、エージェントが間違ったバージョンで実行するリスクがあります。

Voltaを使ってプロジェクト単位でNode.jsバージョンを固定します。package.json に volta フィールドを書くだけで、そのディレクトリに入ると自動でバージョンが切り替わります。tech-stack.md に以下を書いています。

- Runtime: Node.js (Volta でバージョン管理)

各プロジェクトの package.json には以下が入っています。

{
  "volta": {
    "node": "22.14.0"
  }
}

エージェントがグローバルのNode.jsバージョンに依存したりすることがなくなります。新しいプロジェクトを作るときもVoltaの設定を入れる習慣がつきます。

10. git worktreeで並行作業する

ひとつのブランチで作業中に、別の急ぎのタスクが入ることがあります。stashして切り替えて、終わったら戻して——という手順は煩雑で、エージェントとの会話も中断されます。

git worktreeを使うと、同じリポジトリの別ブランチを別ディレクトリにチェックアウトできます。Claude Codeの複数セッションをそれぞれ別のworktreeで開けば、並行作業が可能になります。

# リポジトリ外に作成するのが推奨（エディタの検索に混入しない）
git worktree add ~/worktrees/myproject/feat/new-feature -b feat/new-feature
# ここで別のClaude Codeセッションを開いて作業

mainブランチでの作業を中断せずに、機能ブランチの作業を並行して進められます。作業が終わったら git worktree remove で片付けます。

自分はこの記事を書いている今もworktreeを使っています。masterブランチの作業ディレクトリとは別に、記事執筆用のブランチをworktreeとして切り出しています。ブランチの切り替えコストがゼロになります。

10個のノウハウに共通するテーマをまとめると、「分離」「蓄積」「境界」の3つです。

分離 は、ルールをファイル分割し、デプロイ手順を分離し、worktreeで作業を分離することです。蓄積 は、Memoryで知識を蓄積し、CLAUDE.mdで哲学を蓄積することです。境界 は、共有リソースの境界を明示し、コンテキストウィンドウの使い方を制御することです。

プロジェクトが増えるほど「エージェントへの指示体系」の設計が重要になります。ルールを書くのは面倒に思えますが、一度整備すれば全プロジェクトで効いてきます。