monorepo-navigator について
monorepo-navigatorは、複数パッケージのリポジトリを管理するチーム向けのエンジニアリングスキルです。影響分析、対象を絞ったビルドとテスト、最適化、移行、公開、Claude Codeのワークスペース設定を扱います。
主な機能
- 01パッケージ横断の影響分析
- 02対象を絞ったビルドとテスト
- 03依存関係の図示
- 04キャッシュとインクリメンタルビルドの指針
- 05モノレポ移行と公開ワークフロー
- 06Claude Codeのワークスペース設定
活用シーン
- 01共有コードの変更が影響するパッケージの特定
- 02影響を受けるパッケージだけのビルドとテスト
- 03複数リポジトリからの移行計画
- 04パッケージ公開とバージョン管理の調整
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/monorepo-navigatorを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/monorepo-patterns.mdmonorepo-tooling-reference.mdscripts/monorepo_analyzer.py詳細
モノレポナビゲーター
Tier: POWERFUL
Category: エンジニアリング
Domain: モノレポアーキテクチャ / ビルドシステム
概要
モノレポの調査、管理、最適化を行います。Turborepo、Nx、pnpm ワークスペース、Lerna をカバーします。パッケージをまたいだ影響分析、影響を受けるパッケージだけを対象とした選択的なビルド／テスト、リモートキャッシュ、依存関係グラフの可視化、複数リポジトリからモノレポへの体系的な移行を実現します。ワークスペースを認識した開発のための Claude Code 設定も含まれています。
主な機能
- パッケージをまたいだ影響分析 — 共有パッケージの変更によって、どのアプリが壊れるかを特定します
- 選択的なコマンド実行 — 影響を受けるパッケージだけを対象にテスト／ビルドを実行します（すべては実行しません）
- 依存関係グラフ — パッケージ間の関係を Mermaid 図として可視化します
- ビルドの最適化 — リモートキャッシュ、インクリメンタルビルド、並列実行
- 移行 — 履歴を一切失わず、複数リポジトリからモノレポへ段階的に移行します
- 公開 — バージョン管理、プレリリースチャネル、npm 公開ワークフローに Changesets を使用します
- Claude Code の設定 — パッケージごとの手順を含む、ワークスペースを認識した CLAUDE.md
使用する場面
次のような場合に使用します：
- 複数のパッケージ／アプリでコード（UI コンポーネント、ユーティリティ、型、API クライアント）を共有している
- 何かを変更するたびにすべてを再ビルドするため、ビルド時間が長い
- 複数のリポジトリから単一のリポジトリに移行する
- バージョンを連携させながら、パッケージを npm に公開する必要がある
- 複数のパッケージにまたがってチームで作業しており、ツールを統一する必要がある
次のような場合は使用を避けてください：
- 共有パッケージのない単一アプリのプロジェクト
- チームやプロジェクトの境界が完全に分離されている（複数リポジトリのままで問題ない）
- 共有コードが最小限で、コピー＆ペーストの手間を許容できる
ツールの選択
| ツール | 最適な用途 | 主な機能 |
|---|---|---|
| Turborepo | JS/TS モノレポ、シンプルなパイプライン設定 | クラス最高のリモートキャッシュ、最小限の設定 |
| Nx | 大規模企業、プラグインエコシステム | プロジェクトグラフ、コード生成、影響を受けた範囲に対するコマンド |
| pnpm workspaces | ワークスペースプロトコル、ディスク効率 | ローカルパッケージ参照に workspace:* を使用 |
| Lerna | npm 公開、バージョン管理 | 一括公開、Conventional Commits |
| Changesets | 最新のバージョン管理（Lerna より推奨） | 変更履歴の生成、プレリリースチャネル |
最新のセットアップの多くでは、pnpm workspaces + Turborepo + Changesets を使用します。
Turborepo
→ 詳細は references/monorepo-tooling-reference.md を参照してください
ワークスペースアナライザー
python3 scripts/monorepo_analyzer.py /path/to/monorepo
python3 scripts/monorepo_analyzer.py /path/to/monorepo --json
一般的なアーキテクチャと CI のパターンについては、references/monorepo-patterns.md も参照してください。
よくある落とし穴
| 落とし穴 | 対処法 |
|---|---|
すべての PR で --filter を付けずに turbo run build を実行する | CI では常に --filter=...[origin/main] を使用します |
workspace:* 参照によって公開に失敗する | pnpm changeset publish を使用します。workspace:* は実際のバージョンに自動で置き換えられます |
| 無関係なファイルの変更時に、すべてのパッケージが再ビルドされる | turbo.json の inputs を調整し、ドキュメントや設定ファイルをキャッシュキーから除外します |
| 共有 tsconfig によって、1 つのパッケージがすべての型チェックを失敗させる | extends を適切に使用します。各パッケージはルートを継承しつつ、rootDir／outDir を上書きします |
| 移行時に git の履歴が失われる | マージ前に git filter-repo --to-subdirectory-filter を使用します。手動でファイルを移動しないでください |
| CI でリモートキャッシュが機能しない | TURBO_TOKEN と TURBO_TEAM の環境変数を確認し、turbo run build --summarize で検証します |
| CLAUDE.md が汎用的すぎて、Claude が誤ったパッケージを変更する | パッケージごとの CLAUDE.md に「X の作業時は apps/X 内のファイルだけを変更する」という明示的なルールを追加します |
ベストプラクティス
- ルートの CLAUDE.md で全体像を示す — 各パッケージ、その目的、依存関係のルールをすべて記載します
- 各パッケージの CLAUDE.md でルールを定義する — 許可されること、禁止されること、テストコマンドを記載します
- コマンドには必ず --filter を指定する — 変更のたびにすべてを実行すると、モノレポにする意味がなくなります
- リモートキャッシュは必須です — なければ、モノレポの CI はマルチリポジトリの CI より遅くなります
- 手動でバージョンを管理せず、Changesets を使う — モノレポで package.json のバージョンを手動で編集してはいけません
- 共通設定はルートに置き、各パッケージで拡張する — tsconfig.base.json、.eslintrc.base.js、jest.base.config.js
- 共通パッケージの変更をマージする前に影響を分析する — 影響範囲のチェックを実行し、影響範囲を共有します
- packages/types は純粋な TypeScript に保つ — 実行時コードや依存関係を含めず、ビルドと型チェックを高速にします
コメント
Markdown 対応