Monorepo & Bun Workspaces Troubleshooting

このドキュメントは、Bun workspacesを使用したモノレポ構成における一般的な問題とその解決策を記録します。

問題1: 依存関係のインストール場所の混乱

症状

ワークスペース（例：next-app）でbun installを実行すると、依存関係が正しくインストールされない
ルートでbun installを実行しても、ワークスペースの依存関係が解決されない
bun run lintなどのコマンドが「コマンドが見つかりません」と表示される

根本原因

このプロジェクトはBun workspacesを使用したモノレポ構成です：

ルートパッケージ (/blueperiod/package.json): 共有のdevDependenciesを管理
ワークスペース (/blueperiod/next-app/package.json): アプリケーション固有の依存関係を管理

依存関係のインストールは常にプロジェクトルートで行う必要があります。

解決策

依存関係のインストール:

# 常にプロジェクトルートで実行
cd /blueperiod
bun install

Lintの実行:

# ルートで実行（ワークスペース固有のlint設定を参照）
cd /blueperiod
bun run lint

ワークスペース固有のコマンド:

# next-appワークスペースでコマンドを実行する場合
cd /blueperiod/next-app
bun run dev

実際の事例

2025-12-11: OriginalLanguageBadgeコンポーネント実装時に、next-appディレクトリでbun run lintを実行したところ、ESLintプラグインの解決に失敗
原因: ルートで定義されたESLint設定がワークスペースから正しく参照されていない
解決: ルートでbun run lintを実行することで問題が解消

問題2: ルートパッケージのdependenciesとdevDependenciesの混在

症状

ルートのpackage.jsonにdependenciesセクションにライブラリが追加されている
ワークスペースで同じライブラリを別バージョンで使用している場合、競合が発生
依存関係の解決が複雑化し、ビルドエラーが発生

根本原因

モノレポ構成では、原則として：

ルートのdependencies: ワークスペース間で共有されるランタイム依存関係のみ
ルートのdevDependencies: 開発ツール（ESLint, Prettier, TypeScriptなど）
ワークスペースのdependencies: 各アプリケーション固有の依存関係

解決策

依存関係の配置ルール:
- 開発ツール: ルートのdevDependencies
- アプリケーション固有のライブラリ: ワークスペースのdependencies
- 複数ワークスペースで共有するライブラリ: ルートのdependencies（慎重に検討）

現在の状態の確認:

# ルートの依存関係を確認
cat /blueperiod/package.json | grep -A 20 "dependencies"

# next-appの依存関係を確認
cat /blueperiod/next-app/package.json | grep -A 20 "dependencies"

依存関係の移動: ルートのdependenciesにあるライブラリが本当に必要なものか確認し、不要な場合はワークスペースに移動する。

実際の事例

ルートのpackage.jsonにframer-motionとreact-useがdependenciesとして追加されている
これらはnext-appワークスペースでのみ使用されている可能性が高い
推奨: これらの依存関係をnext-app/package.jsonに移動し、ルートから削除することを検討

問題3: AIエージェントの無限ループ

症状

AIエージェントがgit statusやgit diffを繰り返し実行
パッケージマネージャーが大規模な変更を繰り返し提案
同じ問題で10分以上悩み続ける

根本原因

モノレポの複雑さを理解していない
問題解決のための明確なエスカレーションパスがない
自己判断で無限に試行錯誤を繰り返す

解決策

時間制限の設定:
- 同じ問題で10分以上悩んでいる場合は、直ちに人間に相談
- 同じコマンドを5回以上繰り返している場合は、直ちに人間に相談

エスカレーションパス:

問題発生 → doc/system/troubleshooting/を確認 → 解決策なし → 人間に相談

禁止事項:
- 無限にgit statusやgit diffを実行しない
- パッケージマネージャーの提案を盲目的に受け入れない
- 自己判断で大規模な変更を行わない

実際の事例

2025-12-12: feat-publish-global-phase5_to_phase6のDiff分析中に、AIエージェントが依存関係の更新で無限ループに陥る危険性が観測
対策: doc/document_maintenance.mdに「AIエージェントの無限ループ防止ガイドライン」を追加

ベストプラクティス

1. 依存関係管理

新しいライブラリを追加する前に、既存のワークスペースで使用されていないか確認
ルートに依存関係を追加する場合は、複数ワークスペースで共有されることを確認
定期的に依存関係を整理し、重複を排除

2. コマンド実行

開発サーバーの起動: cd /blueperiod/next-app && bun run dev
Lintの実行: cd /blueperiod && bun run lint
依存関係のインストール: cd /blueperiod && bun install

3. トラブルシューティング

問題が発生したら、まずこのドキュメントを確認
既知の問題がない場合は、doc/system/troubleshooting/ディレクトリを検索
それでも解決しない場合は、直ちに人間に相談

参考リンク

作成日: 2025-12-12 最終更新: 2026-03-04 (npm → Bun移行に伴う更新) 関連レポート: 2025-12-11_report_fix_status_and_add_language_badge.md

Monorepo & Bun Workspaces Troubleshooting

On this page