複数プロジェクトで横断的に活用する

このレッスンで学ぶこと

個人のグローバルCLAUDE.md（~/.claude/CLAUDE.md）の使い方
チーム間で共有するCLAUDE.mdテンプレートの設計方針
グローバル→プロジェクト→ローカルの設定継承の仕組み
モノレポでの階層的なCLAUDE.md運用パターン
複数リポジトリを横断する作業のワークフロー

前提条件

Lesson 4 でプロジェクトCLAUDE.mdの基本を理解していること
複数のプロジェクト・リポジトリを並行して扱う業務があること

1つのプロジェクトの外に出ると見えてくる課題

入門コースのLesson 4では、プロジェクトルートに置く CLAUDE.md を学びました。これは1つのプロジェクトに閉じた話です。しかし実際の開発では、複数のプロジェクトを掛け持ちしたり、1つのリポジトリの中に複数のサブプロジェクトが同居していたりすることが珍しくありません。

このレッスンでは「プロジェクトをまたいでClaude Codeをどう設定し、どう運用するか」に焦点を当てます。

個人のグローバルCLAUDE.mdを活用する

~/.claude/CLAUDE.md は、ホームディレクトリ配下に置く個人専用のCLAUDE.mdです。どのプロジェクトでClaude Codeを起動しても読み込まれるため、「プロジェクトを問わず常に守ってほしい個人的な好み」を書く場所として使えます。

# ~/.claude/CLAUDE.md の例
 
# 個人的な作業スタイル
- パッケージマネージャーはnpmではなくpnpmを優先する（プロジェクトの指定がある場合はそちらに従う）
- 大きな変更を加える前は、必ず変更計画を箇条書きで提示してから着手する
- コミット前に必ず差分の内容を一度要約して確認を求める
 
# よく使うエイリアス的な指示
- 「テスト書いて」と言われたら、まず既存のテストファイルのスタイルを確認してから合わせる

プロジェクトCLAUDE.mdとの役割分担を意識する

グローバルCLAUDE.mdには「自分がどのプロジェクトでも一貫して大事にしたいこと」だけを書きます。プロジェクト固有のビルドコマンドやコーディング規約は、あくまでプロジェクトのCLAUDE.mdに書きましょう。両方に同じような内容を書いてしまうと、矛盾が生じたときにどちらが優先されるか分かりにくくなります。

個人の好みだけでなく、複数プロジェクトに共通する「定型作業の手順」をグローバルCLAUDE.mdから別ファイルとして読み込ませることもできます。

# ~/.claude/CLAUDE.md
# 個人ワークフロー
- gitの操作手順は @~/.claude/my-git-workflow.md を参照

チーム間で共有するCLAUDE.mdテンプレートの設計

チームや組織が複数のリポジトリを運用している場合、リポジトリごとにCLAUDE.mdの書き方がバラバラだと、メンバーがプロジェクトを移動するたびに「このプロジェクトはどんなルールだったか」を再学習するコストが発生します。これを避けるには、CLAUDE.mdの「型」をテンプレート化しておくのが効果的です。

テンプレートに含めるべきセクション

セクション	内容	プロジェクトごとの可変性
プロジェクト概要	1〜2行の説明	完全に固有
ビルド・テストコマンド	npm run build等	固有だが書式は統一
コードスタイル	言語・フレームワーク・命名規則	チーム標準＋プロジェクト固有の例外
Git運用	コミットメッセージ・ブランチ戦略	チーム標準をそのまま継承することが多い
禁止事項	セキュリティ・品質に関するルール	チーム標準をそのまま継承することが多い

「Git運用」「禁止事項」のようにチーム全体で統一したいセクションは、雛形をそのままコピーして使うようにし、「ビルド・テストコマンド」のようにプロジェクトごとに変わる部分だけを書き換える運用にすると、ばらつきを抑えられます。

テンプレートはリポジトリ化して配布する

CLAUDE.mdテンプレートを専用のリポジトリやSnippet集として管理し、新規プロジェクト作成時にコピーする運用にすると、チーム全体でフォーマットが揃います。/init を実行する前にテンプレートを配置しておけば、Claudeはテンプレートの構造を尊重しつつ、プロジェクト固有の情報を埋めてくれます。

プロジェクトごとの設定継承の仕組み

CLAUDE.mdは複数の場所に配置でき、Claude Codeは起動時にディレクトリツリーを上に向かって探索し、見つかったファイルをすべて連結してコンテキストに読み込みます。

~/.claude/CLAUDE.md           ← 個人全体（最も広いスコープ）
  ↓
./CLAUDE.md                   ← プロジェクト共有（チーム）
  ↓
./CLAUDE.local.md             ← 個人×プロジェクト（最も狭いスコープ）

読み込み順序は「広いスコープから狭いスコープへ」となっており、起動したディレクトリに近い指示ほど後にコンテキストへ現れます。内容は上書きではなく連結されるため、グローバルとプロジェクトの両方の指示が同時に有効になります。矛盾する指示がある場合は、Claudeがどちらか一方を任意に選んでしまう可能性があるため、内容が重複・矛盾しないように整理しておくことが大切です。

優先度は「強制」ではない

CLAUDE.mdの読み込み順序は「コンテキストに現れる順番」であり、設定ファイルの上書きのような厳密な優先度ではありません。具体的で簡潔な指示ほど従われやすいという特性を理解した上で、各スコープの内容を設計しましょう。

モノレポでの階層的なCLAUDE.md運用

フロントエンド・バックエンド・インフラなど複数のサブプロジェクトが1つのリポジトリに同居するモノレポでは、ルート直下のCLAUDE.mdだけでは情報が粗すぎたり、逆に詰め込みすぎたりしがちです。サブディレクトリごとにCLAUDE.mdを配置する階層運用が有効です。

monorepo/
├── CLAUDE.md                  # リポジトリ全体の共通ルール
├── apps/
│   ├── web/
│   │   └── CLAUDE.md           # フロントエンド固有の規約
│   └── api/
│       └── CLAUDE.md           # バックエンド固有の規約
└── packages/
    └── shared/
        └── CLAUDE.md           # 共有ライブラリ固有の規約

ルートのCLAUDE.mdには、リポジトリ全体で共通するルール（コミット規約、禁止事項など）だけを書きます。サブディレクトリのCLAUDE.mdは、Claudeがそのディレクトリ内のファイルを実際に読み書きするタイミングでオンデマンドに読み込まれる仕組みになっているため、「フロントエンドの作業をしているときだけ apps/web/CLAUDE.md の内容が効いてくる」という動作になります。

# monorepo/CLAUDE.md（ルート）
# リポジトリ構成
- apps/web: フロントエンド（Next.js）
- apps/api: バックエンド（Node.js + Express）
- packages/shared: 両者で共有する型定義・ユーティリティ
 
# 共通ルール
- コミットメッセージは日本語で記述する
- mainブランチへの直接コミット禁止

# monorepo/apps/web/CLAUDE.md
# フロントエンド固有の規約
- コンポーネントはsrc/components/に配置し、PascalCaseで命名する
- スタイリングはTailwind CSSを使用する
- 状態管理ライブラリの新規導入は要相談

他チームの規約に埋もれないようにする

大規模なモノレポでは、自分が触らないディレクトリのCLAUDE.mdまで読み込まれてコンテキストを圧迫することがあります。関係のない祖先ディレクトリのCLAUDE.mdを除外したい場合は、設定ファイルで除外パターンを指定できる仕組みが用意されています。詳しくは設定ドキュメントを参照してください。

複数リポジトリを横断する作業のワークフロー

マイクロサービス構成などで、1つの機能追加が複数のリポジトリにまたがることもあります。この場合、Claude Codeのセッションは基本的に1つの作業ディレクトリに紐づくため、リポジトリごとにセッションを分けて作業し、変更内容を人間が橋渡しする進め方が現実的です。

影響範囲を整理する

最初のリポジトリで、変更が他のリポジトリにどう影響するかをClaudeに整理させます。

このAPIのレスポンス形式を変更すると、フロントエンド側の
型定義やパース処理にどんな影響が出るか整理して

変更内容をサマリーとして書き出させる

この変更内容を、別リポジトリの担当者に伝えるための
サマリーとして3行程度でまとめて

このサマリーを、次のリポジトリで作業する際のプロンプトの冒頭に貼り付けると、文脈を引き継げます。

別リポジトリでセッションを開始し、文脈を渡す

cd ../frontend-repo
claude

バックエンド側で以下の変更を行いました。
（ここに手順2で作成したサマリーを貼り付け）
この変更に合わせて、フロントエンド側の型定義とAPI呼び出し部分を
更新してください。

両リポジトリの変更をそれぞれPRにする

各リポジトリで独立してPRを作成し、PR説明文に「関連PR: ◯◯リポジトリの#123」のように相互参照を残しておくと、レビュアーが変更の全体像を追いやすくなります。

複数リポジトリの同時編集はworktreeや並列セッションも検討する

関連リポジトリをローカルにまとめて配置している場合、--add-dir フラグで作業ディレクトリ外のファイルを参照させたり、リポジトリごとに別ターミナルでセッションを並行させたりする方法もあります。プロジェクトの構成や規模に応じて使い分けましょう。

まとめ

このレッスンでは、複数プロジェクトを横断してClaude Codeを活用する方法を学びました。

グローバルCLAUDE.md: ~/.claude/CLAUDE.md に「プロジェクトを問わない個人の好み」を書く
チーム共有テンプレート: ビルドコマンド等の可変部分と、Git運用・禁止事項等の標準部分を分けて設計する
設定継承: グローバル→プロジェクト→ローカルの順でコンテキストに連結され、内容は上書きではなく加算される
モノレポでの階層運用: ルートに共通ルール、サブディレクトリに固有規約を配置し、オンデマンドで読み込ませる
複数リポジトリ横断: リポジトリごとにセッションを分け、サマリーで文脈を橋渡しする

次のステップ

ここまでで、実践コースの前半として「デバッグ」「Git操作」「プロジェクト横断」という日常業務に直結するワークフローを学びました。次のレッスンでは、Claude Codeへの指示そのものの質を上げる「プロンプト設計の実践テクニック」を扱います。

Lesson 8: プロンプト設計の実践テクニックに進みましょう。