Monorepo トラブルシューティング

このドキュメントは、BluePeriodのマルチプロジェクトモノレポ構成における一般的な問題とその解決策を記録します。

構成の前提

BluePeriodはBun workspacesを使用しないマルチプロジェクトモノレポ構成です。各サブプロジェクトが独立したパッケージとして管理されています。

各ディレクトリで bun install を実行する必要があります。ルートの bun install はルートのdevDependencies（ESLint, TypeScript等）のみを対象とします。

問題1: 依存関係がインストールされていない

症状

• bun next でモジュールが見つからないエラー
• bun lint や bun check がコマンド不明で失敗

解決策

作業するサブプロジェクトのディレクトリで bun install を実行してください。

# next-appの依存関係をインストール
cd next-app && bun install

# fumadocsの依存関係をインストール
cd fumadocs && bun install

問題2: ルートの bun lint がOOMでクラッシュ

症状

• FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

根本原因

ルートの bun lint はモノレポ全体（node_modules/ を含む全サブプロジェクト）をスキャンするため、Node.jsのデフォルトヒープサイズ（約4GB）を超過します。

解決策

各サブプロジェクト単位でLintを実行してください。

# 個別実行
bun next:check    # next-appのみ
bun fuma:check    # fumadocsのみ
bun astro:check   # astroのみ

# 全サブプロジェクト一括
bun all:check

問題3: bun build がエントリポイントエラーになる

症状

• error: Missing entrypoints. What would you like to bundle?

根本原因

bun build はBunの組み込みバンドラコマンドを優先的に呼び出します。npmスクリプトの build を実行するには bun run build を使用する必要があります。

解決策

# 誤り: Bunバンドラが起動する
bun build

# 正しい: npmスクリプトを実行
bun run build

ルートの集約スクリプト（bun next:build 等）はすでに bun run build を使用するよう修正済みです。

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

症状

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

解決策

1. 同じ問題で 10分以上 悩んでいる場合は、直ちに人間に相談
2. 同じコマンドを 5回以上 繰り返している場合は、直ちに人間に相談
3. エスカレーションパス: 問題発生 → troubleshooting/ を確認 → 解決策なし → 人間に相談

ベストプラクティス

依存関係管理

• 各サブプロジェクトのディレクトリで bun install を実行
• 新しいライブラリの追加も対象ディレクトリで bun add <package>
• ルートの package.json には devDependencies のみを配置

コマンド実行

• 開発サーバー: bun next, bun fuma, bun astro
• 品質チェック: bun all:check または個別の bun next:check 等
• ビルド: bun all:build または個別の bun next:build 等
• デプロイ: bun all:prod または個別の bun next:prod 等

作成日: 2025-12-12 最終更新: 2026-04-30 (Bun workspaces非使用の実態に合わせて全面改訂)