Claude Code の --add-dir で複数リポジトリを横断編集する実践パターン

フロントエンドのリポジトリとバックエンドのリポジトリをまたいだ API の型変更を、Claude Code に一発で任せたいと思ったことはありませんか。API のレスポンス形式が変わるたびに、バックエンドで型を直し、フロントエンドで受け取り側を直し、さらに E2E テストの期待値を直し...という手作業は、個人開発でも地味に時間を奪っていきます。

Claude Code には --add-dir という、起動後にも追加できる「作業対象ディレクトリ」を指定するフラグがあります。この機能を知っていると、monorepo 化していない複数のリポジトリを一時的にひとつの作業空間として扱えるようになります。ここでは私が実際に個人アプリ開発のなかで使っている --add-dir の実践パターンと、使う前に押さえておくべきセキュリティ上の注意点を整理します。

なぜ --add-dir が必要なのか

Claude Code は起動時に指定した作業ディレクトリ（カレントディレクトリ）の外には、基本的にアクセスできない設計になっています。ファイルの Read や Edit を安全に制限するためのこの挙動は、本番リポジトリを壊さないためにとても重要なガードです。

ただ実開発では、「フロントエンド frontend-app/ とバックエンド api-server/ が別リポジトリで、同じ API エンドポイントを扱っている」ような場面が頻繁にあります。こうした時に、毎回 Claude Code を別ディレクトリで起動し直していると、コンテキストが分断されて「なぜこのフィールドを追加しているのか」といった目的情報が毎回失われます。

--add-dir を使うと、セッション中にもうひとつのリポジトリを「追加作業対象」として登録でき、Claude は両方のファイルを同じ会話コンテキストで読み書きできるようになります。目的・制約・規約がひとつの会話に保持されるため、API 変更の整合性が取りやすくなるのが最大のメリットです。

基本の使い方

--add-dir の使い方は極めてシンプルです。起動時にフラグで指定するか、セッション中にスラッシュコマンドで追加します。

# 起動時に追加（カンマ区切りではなくスペース区切りで複数指定可）
cd ~/projects/frontend-app
claude --add-dir ~/projects/api-server
 
# セッション中に追加したい場合
# Claude Code のプロンプト内で以下を実行
/add-dir ~/projects/api-server

起動後に現在追加されているディレクトリを確認したい場合は /status を叩くと、プライマリディレクトリと追加ディレクトリの一覧が表示されます。ちなみに --add-dir は複数指定も可能で、マイクロサービス構成でサービスごとにリポジトリが分かれている場合でも対応できます。

# 3 つのリポジトリを同時に開く
claude \
  --add-dir ~/projects/api-server \
  --add-dir ~/projects/web-app \
  --add-dir ~/projects/mobile-app

ここで重要なのは、指定できるのは「ディレクトリ」であって「ファイル単体」ではないという点です。~/projects/api-server/src/types.ts のようにファイルを指定するとエラーになります。これは意図的な設計で、Claude がリポジトリ全体の構造を把握できるようにするための制約だと私は理解しています。

実践パターン 1: API 型定義の同期変更

もっとも頻繁に使うパターンが、バックエンドの型定義変更をフロントエンドに同期させるケースです。たとえばバックエンド（Hono）で User 型に timezone フィールドを追加する時を考えてみましょう。

cd ~/projects/api-server
claude --add-dir ~/projects/web-app

そのうえで、Claude にこう伝えます。

User 型に timezone: string フィールドを追加してください。
- api-server: src/types/user.ts の User 型を更新し、DB マイグレーションも追加
- web-app: 受け取り側の型定義を同期し、プロフィール編集画面に timezone 選択UIを追加
- 両リポジトリでテストが通ることを確認してください

Claude はまず api-server 側で型とマイグレーションを生成し、次に web-app 側で該当する型定義を更新します。同じ会話のなかで両リポジトリを触るので、フィールド名のタイポや型の不一致が起きにくいのが実感です。別セッションで分けてやると「バックエンドは timezone、フロントエンドは timeZone」のような微妙なズレが必ず発生しますが、--add-dir ならその心配がありません。

実践パターン 2: 共通ユーティリティの抽出とコピー

複数リポジトリに散らばった同じロジック（たとえば日付フォーマット関数）を共通化したいが、npm パッケージ化するほどのものでもない、というケースもよくあります。--add-dir は、このような軽量な横断リファクタリングにも向いています。

cd ~/projects/web-app
claude --add-dir ~/projects/mobile-app --add-dir ~/projects/admin-panel

Claude に、こう依頼します。

3 つのリポジトリすべてで使われている日付フォーマット関数を探してください。
重複実装を見つけたら、最も完成度の高いものを基準にして、
残りのリポジトリをそれに合わせてください。タイムゾーン処理も統一してください。

Claude は各リポジトリの utils/date.ts や lib/format.ts を grep で探し、実装の差分を把握したうえで統一案を出してきます。ここで私が気に入っているのは、Claude が「どれを基準にするべきか」の判断理由を説明してくれることです。単純に行数が多いほうを残すのではなく、テストカバレッジやエラーハンドリングの充実度で選んでくれるので、レビューの納得感が高いです。

実践パターン 3: ドキュメント駆動でリポジトリを整える

個人開発ではドキュメントの整備が後回しになりがちですが、--add-dir を使うとドキュメントリポジトリを起点にしたコード修正ができます。

cd ~/projects/docs-site
claude --add-dir ~/projects/api-server

docs-site/api-reference.md に記載されている API 仕様と、
api-server/src/routes/ の実装が一致しているかチェックしてください。
ドキュメント側に誤りがあれば修正案を出し、
実装側にバグや仕様漏れがあれば issue として整理してください。

このパターンは地味ですが、仕様書とコードの乖離を自動で検出できるので、数ヶ月放置していたプロジェクトの棚卸しにも使えます。私は四半期に一度、個人開発アプリの API ドキュメントと実装の差分をこの方法で確認しています。

セキュリティと安全性の考慮

--add-dir は便利ですが、複数リポジトリへの書き込み権限を同時に渡すことになるため、いくつか気をつけるポイントがあります。

書き込みが発生するリポジトリは最小限にする

読み取りだけで済む場合（たとえば参照用のサンプルコードリポジトリ）は、そのリポジトリを読み取り専用でクローンしておくのが安全です。Claude Code 側で書き込みを防ぐフラグはないので、ディレクトリパーミッションや git の core.filemode で物理的に書き込みできない状態にしておくと事故を防げます。

Git のクリーンな状態で開始する

両方のリポジトリを開く前に、それぞれ git status でクリーンな状態にしておきましょう。複数リポジトリの変更が混在すると、どちらの変更を commit すべきか混乱しやすくなります。理想は、各リポジトリで新しいブランチを切ってから Claude Code を起動することです。

cd ~/projects/api-server && git checkout -b feature/add-timezone
cd ~/projects/web-app && git checkout -b feature/add-timezone
cd ~/projects/api-server
claude --add-dir ~/projects/web-app

commit はリポジトリ単位で別々に

Claude に「両方のリポジトリをコミットしてください」と伝えると、各リポジトリで個別に git commit が実行されます。この時、コミットメッセージを「なぜこの変更が同時に必要なのか」を含めて書いてもらうように依頼すると、後日の git log 追跡が楽になります。

コミットメッセージには、両リポジトリが同じ timezone フィールド追加の
一環であることを明記してください。関連する PR 番号も記載してください。

--add-dir が向かないケース

万能ではないので、向かないケースも明記しておきます。

• リポジトリが 4 つ以上: コンテキストウィンドウを消費しすぎて、かえって精度が落ちます。この場合は monorepo 化するか、サブエージェントで並列処理するほうが現実的です
• 完全に独立したサービス: API も共有しておらず、コード規約もバラバラなリポジトリを混ぜても、Claude が混乱するだけです
• セキュリティ境界が異なる: 顧客データを扱うリポジトリと、OSS にするつもりのリポジトリを同時に開くのは避けたほうが無難です。意図しないファイルをコピーしてしまうリスクがあります

私の経験則では、2〜3 リポジトリまで、かつ同じプロダクトの構成要素であることが --add-dir を使う判断基準です。

関連する機能との使い分け

Claude Code には似た用途のフラグがいくつかあるので、使い分けを整理しておきます。

• --add-dir: 複数リポジトリを横断編集する時。会話コンテキストは共有
• Worktree: 同一リポジトリで複数ブランチを並行して触る時。独立したワーキングコピー
• Subagent: 独立したタスクを並列実行する時。会話コンテキストは分離

「複数のリポジトリを、ひとつの目的のために同時に触る」というのが --add-dir の核心です。並列性ではなく、一貫性を保つための機能として捉えると使いどころが見えてきます。

まずやってみるなら

初めて試す時は、自分のアクティブな個人開発プロジェクトで、フロントエンドとバックエンドが別リポジトリになっているペアを選んでみてください。そのうえで、「エンドポイントのパラメータを 1 つ追加する」くらいの小さな変更を --add-dir で試すと、手応えがつかめます。5 分もあれば終わる変更ですが、両リポジトリで型がピタッと合う感覚は、慣れると手放せなくなります。

Claude Code のワークフローをさらに深めたい場合は、Claude Code worktree で複数ブランチを並行開発する実践ガイド や Claude Code の Subagent でタスクを並列処理する設計パターン も合わせて読んでおくと、状況に応じた使い分けができるようになります。