複数のリポジトリをClaude Codeで並行開発するコツ — 3プロジェクトを同時に動かして学んだこと

「このコンポーネントの import 文が見つかりません」と Claude Code が指摘してきたとき、私は首を傾けました。確かにそのコンポーネントは存在します。なぜなら、20分前に書いたばかりだったからです。

しかし問題は、それを書いたのが別のリポジトリのセッションだったことでした。

複数のプロジェクトを同時に Claude Code で進めていると、こういった「ズレ」がじわじわと積み重なります。Claude Code が悪いわけではありません。私がコンテキストの境界を曖昧にしたまま使っていたことが原因でした。

アプリのバックエンド、フロントエンド、それから別のウェブサービス。3つを同時に動かし始めた頃から、意図せぬコンテキストの汚染、コストの管理しにくさ、セッションの再起動タイミングの迷いが増えていきました。この記事は、その3ヶ月で見つけた「効く設定」と「やめたこと」の記録です。

コンテキストが「汚染」されるとはどういう状態か

Claude Code は各セッション開始時に CLAUDE.md とカレントディレクトリを基点として動作します。別のターミナルウィンドウで別のリポジトリのセッションを開けば、それぞれが独立した文脈で動くはずです。

ただし、やってしまいがちなのが「参照先の混在」です。

たとえば、プロジェクトAで実装した関数の仕様を口頭で説明しながら、プロジェクトBのファイルを指示します。するとClaude Codeはその説明をプロジェクトBの文脈として解釈します。どちらのコードにも存在しない関数を参照し始めるのはそのためです。

対策はシンプルです。「プロジェクト間の情報を口頭で橋渡しするのをやめる」こと。参照が必要なら、ファイルを直接渡すか、後述する --add-dir フラグで参照を明示します。

また、長時間のセッションでは自動圧縮（compaction）が起きやすく、初期の前提が失われることがあります。Claude Code のセッション管理については別記事で詳しく解説していますが、複数プロジェクトを抱えているときほど、この問題が深刻になります。

CLAUDE.md をプロジェクトごとに書き分ける

複数プロジェクトを並行させるとき、最も効果があったのは各リポジトリの CLAUDE.md をしっかり書くことでした。単なるプロジェクト説明ではなく、「Claude Code にとっての仕事の文脈」を定義するドキュメントとして捉えると大きく変わります。

特に効果があったのは以下の3点です。

① 使ってはいけないパターンを明示する

## やってはいけないこと
- useEffect の依存配列に `data` を含めない（無限ループが起きる）
- /api/ エンドポイントをクライアントから直接呼ばない（middleware経由が必須）
- 型アサーションに `as any` を使わない（型定義ファイルを参照すること）

プロジェクト固有の地雷をここに書いておくと、セッションをまたいだ際の指示ミスが激減します。これはプロジェクトごとに異なるため、コピー&ペーストで使い回すのではなく、そのリポジトリに実際に起きた問題から書く点が肝心です。

② 現在の開発フェーズを書く

## 現在のフェーズ
- DBスキーマは確定前（マイグレーション不可）
- パフォーマンス最適化より動作確認を優先
- 認証機能は未実装（認証が必要な箇所はコメントで「TODO」を入れる）

「今はまだここまでしかできていない」という文脈が共有されていると、Claude Code の提案がスコープ外に出にくくなります。

③ よく参照するドキュメントのパスを書く

## 参照ドキュメント
- API仕様書: docs/api/specification.md
- 型定義: src/types/index.ts
- 環境変数一覧: .env.example
- デザインシステム: docs/design-system.md

毎回「このファイルを参照して」と伝えなくて済むようになります。最初は面倒に感じますが、3プロジェクトを並行させているときに CLAUDE.md の質の差が如実に出ました。

CLAUDE.md の詳細な設計パターンはこちらの記事も参考になります。

セッションを「終わらせる」習慣を持つ

最初は1つのセッションを長時間使い続けていましたが、やめました。長時間の会話は compaction が起きやすく、設計の前提を話した部分が圧縮されて失われることがあります。特に複数プロジェクトを並行しているときは、「どのプロジェクトのどのセッションがどこまで進んだか」が曖昧になりやすいです。

今は以下のルールを守っています。

• 1タスク（1機能 or 1バグ修正）= 1セッションを原則とする
• セッション開始時に「今日このセッションでやること」を1文で宣言する
• 翌日の作業は必ず新しいセッションから始める

最後のルールは最初「コンテキストが消えてもったいない」と感じましたが、実際には前日の作業内容を CLAUDE.md か commit message として残しておけば、次のセッションでも再現できます。むしろ余計なコンテキストがない分、指示が通りやすくなりました。

セッション終了前に「今日やったことの要点を3行で」とClaude Codeに聞いて、それをそのまま CLAUDE.md の「前回の作業」セクションにコピーする習慣も効果的です。

--add-dir で関連リポジトリを参照する

バックエンドとフロントエンドを分けて管理しているとき、「フロントエンドの型定義に合わせてAPIのレスポンス形式を変えたい」という作業が頻繁に発生します。このとき --add-dir フラグが便利です。

# フロントエンドの型定義を参照しながら、バックエンドの作業をする
cd backend/
claude --add-dir ../frontend/src/types

Claude Code は ../frontend/src/types を読み取り可能な状態でセッションを開始します。ファイルを手動でコピーする必要がなく、常に最新の型定義を参照できます。

ただし、注意点があります。--add-dir で追加したディレクトリはコンテキストを消費します。不要なディレクトリを大量に追加すると、コンテキスト上限に早く達します。私の経験では、参照先のディレクトリは1〜2個にとどめるのが現実的です。

なお、追加できるのはローカルのディレクトリのみです。GitHubのURLや外部サービスのドキュメントは直接指定できません。その場合は一度ローカルにクローンするか、必要な箇所だけをコピーしてからセッションで渡す方法になります。

コストをプロジェクト別に把握する

複数プロジェクトを動かし始めると、「どのプロジェクトがどれくらいのAPI費用を使っているか」が見えなくなります。Claude Code にはプロジェクト別のコスト表示機能がないため（2026年5月時点）、私は簡単な記録をつけています。

セッション終了時に /cost コマンドを打って、コストを記録するだけです。

# 簡単なログの例（メモアプリやスプレッドシートで管理）
2026-05-05 backendリポジトリ（認証機能実装）: $1.23
2026-05-05 frontendリポジトリ（UIコンポーネント修正）: $0.48
2026-05-05 サービスXリポジトリ（バグ調査）: $0.31

特に驚いたのは、「ちょっと確認するだけ」と思って始めたセッションが、実は CLAUDE.md の読み込みとファイル探索だけで$0.30〜0.50かかっていたことです。

コスト削減に効果があったのは .claudeignore の活用でした。

# .claudeignore の例
node_modules/
dist/
.next/
coverage/
*.log
*.map

Claude Code が自動で探索するファイルを絞り込むことで、1セッションあたりのコストが体感で20〜30%下がりました。コンテキストウィンドウの管理については別の記事で詳しく解説しています。

3ヶ月続けてわかった「やってよかった」設定

最後に、実際に長期間続けて効果があったことをまとめます。

CLAUDE.md に「今やっていないこと」セクションを設ける

「認証機能はまだ未実装」「パフォーマンスチューニングは後回し」など、スコープ外を明示することで余計な提案が減ります。Claude Code は親切なので、文脈がなければ「ついでにここも直しましょうか」と提案してきます。それが今必要かどうかを都度判断する手間を省けます。

セッション開始のテンプレートを用意する

各プロジェクトの README に、セッション開始時のテンプレートを書いておきます。

## Claude Code セッション開始テンプレート
「今日は[機能名]を実装したい。
関連ファイルは src/[パス] にある。
現在の課題は[具体的な問題]。
[その他の制約や前提]」

これをコピー&ペーストしてから始めると、毎回ゼロからコンテキストを伝える時間が大幅に短縮されます。

git commit の粒度を小さくする

1コミット = 1論点を意識するようにしました。大きな変更を一度にコミットすると、セッション再開時に「どこまで終わったか」の確認コストが増えます。「動いたらコミット」の習慣が、結果として Claude Code との作業をスムーズにしています。

複数プロジェクトの並行開発は、Claude Code を使えば確実に効率が上がります。ただし、その恩恵を最大化するためには、コンテキスト管理の意識が欠かせません。特に最初の1週間でプロジェクトごとの CLAUDE.md を丁寧に書くことをおすすめします。その投資は必ず回収できます。