未知のコードベースを探索する

誰にも説明されていないプロジェクトを引き継いだ時、OpenCode はあなたのツアーガイドになります。インポートグラフを読み、エントリーポイントを特定し、1 時間以内に行動可能なマップを生成します。

このレシピを使う場面

新しいチームに加わった、あるいは未メンテナンスのリポジトリを引き継ぐ。
コードベースが大きすぎて、すべてのファイルを読むのは現実的でない。
自信を持って変更を加えたいが、まだ境界がどこにあるか分かっていない。

前提条件

OpenCode がインストールされ、プロジェクトルートを指している。
実行可能なビルドまたはテストコマンドがある。
リポジトリ全体への読み取り権限がある（暗号化サブモジュールは不可）。

手順

全体像をつかむ

OpenCode に、プロジェクトの構成、技術スタック、エントリーポイントを数段落で要約してもらいます。

プロジェクトルートを読み、以下を要約してください: 言語とフレームワーク、ディレクトリ構造、主なエントリーポイント、ビルド/実行コマンド。特異な点を強調してください。
アーキテクチャをマッピングする

モジュール、それぞれの責務、相互の通信方法を 1 ページにまとめたアーキテクチャマップを依頼します。

モジュールマップを作成してください: どのディレクトリがどの関心事を持ち、どのトップレベルファイルがどこからインポートしているかを示してください。依存関係の方向（UI → service → data）があれば示してください。
エントリーポイントを特定する

リクエスト、ジョブ、コマンドがシステムに入る場所を特定します。ここがほとんどのバグと機能追加が行われる場所です。

すべてのエントリーポイントを列挙してください: HTTP ルート、CLI コマンド、cron ジョブ、メッセージハンドラ、スケジュールされたタスク。各々について、ファイルパスと 1 行の説明を付けてください。
代表的なリクエストをトレースする

1 つのエンドツーエンドのフローを選び、順を追って進みます。これは直感を構築する最速の方法です。

HTTP ルートからサービス層、データベースまで、単一のユーザーリクエストをトレースしてください。呼び出しチェーンを示し、各層の責務を説明してください。
ナビゲーションガイドを書く

発見を、あなたとチームメイトが参照できる CODEBASE_MAP.md にするよう OpenCode に依頼します。

リポジトリルートに CODEBASE_MAP.md を書いてください: 1) 1 段落のプロジェクト要約、2) モジュールマップ、3) エントリーポイントリスト、4) トレース済みのサンプルフロー 1 つ、5) 観察された規約（命名、エラーハンドリング、ロギング）。
小さな変更を加えて検証する

小さくて実際の変更（タイポ修正、ログメッセージの改善）を行い、ビルド、リンタ、テストが通ることを確認します。
```
npm run build && npm test
```

重要なプロンプト

このリポジトリは初めてです。プロジェクトルート全体を読み、以下を生成してください: (1) 1 段落のプロジェクト要約、(2) 依存方向を含むモジュールマップ、(3) ファイルパス付きのすべてのエントリーポイント、(4) 層を通してトレースした 1 つのエンドツーエンドのリクエストフロー、(5) 命名、エラー、ロギングについて観察される規約。リポジトリルートに CODEBASE_MAP.md として出力してください。

検証

CODEBASE_MAP.md がコミットされ、チームで共有されている。
トレース済みのサンプルフローを手動で追跡すると、現実に一致している。
小さな意図的な変更がビルドとテストでグリーンになる。

よくある落とし穴

マップを盲信する: マップは仮説として扱い、根拠として扱わない。リファクタリング前に検証する。
エントリーポイントをスキップする: ほとんどのバグは境界に存在します。図よりもリストの方が有用。
古い規約: 古い部分のコードは、チームがすでに廃止したパターンに従っている可能性がある。各エリアの最新ファイルの日付をメモする。

次のステップ

refactor-codebase — next.explore.to-refactor

未知のコードベースを探索する

このレシピを使う場面

前提条件

手順

重要なプロンプト

検証

よくある落とし穴

関連ドキュメント

関連レシピ

関連ドキュメント

次のステップ