Troubleshooting Guide

このディレクトリには、開発中に遭遇した技術的な問題とその解決策を記録します。

目的

• 知見の集約: 同じ問題に再び遭遇したときに、迅速に解決できるようにする
• チーム共有: 新しいメンバーが同様の問題を避けられるようにする
• パターンの発見: 繰り返し発生する問題から、システム設計の改善点を見つける

ドキュメント一覧

React関連

• react-state-management.md - Reactの状態管理に関する問題
  • propsの変更が内部stateに反映されない問題
  • useEffectの適切な使用方法

Next.js関連

• nextjs-caching.md - Next.jsのキャッシュとレンダリングに関する問題
  • 検索パラメータが変更されてもページが更新されない問題
  • 動的レンダリングの設定方法
• nextjs-15-async-params.md - Next.js 15の非同期paramsに関する問題
  • paramsやsearchParamsがundefinedになる問題
  • APIルートでの404エラーの解決策

Monorepo関連

• monorepo-bun-workspaces.md - Bun workspacesを使用したモノレポ構成に関する問題
  • 依存関係のインストール場所の混乱
  • ルートパッケージのdependenciesとdevDependenciesの混在
  • AIエージェントの無限ループ防止

ドキュメントの構造

各トラブルシューティングドキュメントは、以下の構造に従います:

# [技術領域] Troubleshooting

## 問題N: [問題の簡潔な説明]

### 症状
- ユーザーが観察できる現象
- エラーメッセージ
- 期待される動作との違い

### 根本原因
- なぜこの問題が発生するのか
- 技術的な背景

### 解決策
- 推奨される解決方法
- 代替案
- コード例

### 実際の事例
- プロジェクト内で発生した具体的なケース
- どのように解決したか

### ベストプラクティス
- 同様の問題を避けるための推奨事項

### 参考リンク
- 公式ドキュメント
- 関連記事

新しいトラブルシューティングドキュメントの追加

新しい技術的な問題を発見した場合:

1. 既存のドキュメントを確認: 同じカテゴリのドキュメントが既に存在するか確認
2. 適切なファイル名を選択: [技術領域]-[問題カテゴリ].md の形式
3. 上記の構造に従って記述: 症状・原因・解決策を明確に
4. このREADMEを更新: 新しいドキュメントへのリンクを追加

作業報告書との関係

• 作業報告書 (/doc/log/reports/): 時系列での開発記録
• トラブルシューティング (/doc/system/troubleshooting/): 技術的な問題の体系的な記録

作業報告書からトラブルシューティングドキュメントへリンクを張ることで、相互参照を可能にします。

メンテナンス

• 新しい解決策が見つかった場合は、既存のドキュメントを更新
• 古くなった情報は、アーカイブまたは削除
• 定期的にレビューして、情報の正確性を保つ

作成日: 2025-11-27
最終更新: 2025-11-27