codebase-explorer

Codebase Explorer

なじみのないコードを理解するためのフィールドマニュアルです。ファイルの内容を要約するのではなく、システムの振る舞いをたどれるマップを作成します。

核となる原則

ファイルツリーは保管場所であり、理解そのものではありません。ディレクトリ構造には、チームが成果物をどのように整理したかが反映されています。ロジックの流れを追うことで、コードの存在理由とその動作が明らかになります。両者が食い違う場合は、ロジックの流れを信頼してください。

理解とは、「コードを読んだ」ということではありません。理解とは、「X が変わったときに何が起きるかを説明できる」ということです。

システム全体を理解することはできません。垂直スライスのポートフォリオを構築してください。入力から出力までの完全な経路をたどることで、範囲を限定した領域での振る舞いを予測できるようになります。

---

対象者

このスキルがもたらす価値は、対象者によって異なります。ユーザーの役割に合わせて、深さや語彙を調整してください。

対象者	必要としていること	重視する内容
コードを引き継ぐ開発者	どこから始めるか、何を安全に変更できるか	垂直スライス、共有運命グループ、暗黙の契約
テックリード／アーキテクト	リスクマップ、結合の分析、リファクタリングの対象	問題の兆候、共有運命グループ、基盤の制約
エンジニアリングマネージャー	変更コストの見積もり、チーム間の調整ニーズ	リスクプロファイル、共有運命グループ、不明点
プロダクトマネージャー	変更の難易度、ボトルネックの所在	リスクプロファイル（ビジネスの観点）、基盤の制約
セキュリティ監査担当者	攻撃対象領域、データフロー、信頼境界	I/O 境界マップ、暗黙の契約、データの系譜
新入社員のオンボーディング	システムの仕組みを捉えるためのメンタルモデル	パイプラインの流れ／アーキテクチャ図、雰囲気、垂直スライス
コンサルタント／契約業者	変更を行う前の迅速な状況把握	クイックアセスメントのテンプレート、類型の分類
デューデリジェンスのレビュー担当者	コード品質の指標、技術的負債の一覧	問題の兆候、アクティビティヒートマップ、不明点

ユーザーの役割が不明な場合は、開発者の視点を基本としつつ、リスクプロファイルと不明点のセクションを含めてください。これらは誰にとっても役立ちます。

---

このスキルが特に役立つ場面

このスキルは、次のような場面で最も大きな価値を発揮します。

• 引き継いだコードベース：ドキュメントが不十分、または存在しない場合
• マルチサービスアーキテクチャ：システム全体を把握している人がいない場合
• 書き換え前の評価：置き換える対象を決める前に、既存の仕組みを理解する場合
• インシデント対応：なじみのないシステムで、影響範囲を迅速に特定する場合
• オープンソースへの貢献：PR を提出する前にプロジェクトを理解する場合
• 買収後の評価：コード品質と技術的負債を評価する場合
• コンプライアンス／セキュリティ監査：データフローと信頼境界をマッピングする場合
• オンボーディング：新しいチームメンバーがたどれるメンタルモデルを提供する場合

---

ワークフロー

探索は 4 つのフェーズで進めます。次のフェーズに進む前に、各フェーズを完了してください。

フェーズ 0：アーキタイプの検出（最初の 2 分間）

ビジネスロジックを読む前に、コードベースのアーキタイプを特定します。アーキタイプによって、使用する垂直スライス戦略、優先して確認するコードの臭い、主な出力成果物が決まります。

検出方法：ルートディレクトリで特徴的なファイルを確認します。

シグナルとなるファイル	アーキタイプ
template.yaml / serverless.yml / statemachine/ / stepfunctions/	サーバーレスパイプライン
Dockerfile + ルートハンドラー（app.py、server.js、main.go）	バックエンド API
React/Vue/Svelte/Next を含む package.json + src/components/	フロントエンドアプリケーション
dags/ / pipeline/ / airflow.cfg / dbt_project.yml	データパイプライン
ライブラリ構造を持つ setup.py / pyproject.toml、メインエントリーポイントなし	ライブラリ / SDK
main.tf / *.tf / cdk.json / Lambda コードを含まない CloudFormation	Infrastructure as Code
CLI エントリーポイント（__main__.py、bin/、主要インターフェースとしての Makefile）	CLI ツール
train.py / model/ / ノートブック + ML ライブラリを含む requirements.txt	ML システム

複数のシグナルが該当する場合は、コードの大部分が存在する場所を基準に主要なアーキタイプを選びます。副次的なアーキタイプも記録してください。

出力：信頼度レベルを含むアーキタイプの分類。この分類を、その後のすべてのフェーズの前提とします。

---

フェーズ 1：概要の把握

ビジネスロジックを読む前に、システムの構造に関する 4 つの質問に答えます。それぞれについて、指定された出力成果物を作成してください。

Q1：外界との境界はどこにありますか？

I/O の境界、つまりシステムが外界と接する場所を図にします。

1. エントリーポイント（メイン関数、ルートハンドラー、イベントリスナー、エクスポートされた API）を特定します
2. 各エントリーポイントについて、最初の外部呼び出しを見つけます
3. 関数に印を付けます：○ 純粋（I/O なし） · ● 不純（外界に接触） · ◐ 混在
4. 境界を図にします：データの入力元と出力先

シグナル：fetch/axios/http → ネットワーク · fs/readFile → ファイルシステム · query/execute/find/save → データベース · Date.now()/Math.random() → 非決定性 · process.env/config.get → 環境への結合

出力：I/O 境界マップ

Q2：基盤となる制約は何ですか？

コードで実際にできることを制限する、メモリ、ペイロードサイズ、タイムアウト、レート制限などの厳しい上限を特定します。

1. 依存関係マニフェストでランタイムの制約を確認します
2. 設定ファイルを探し、上限を記録します：maxPayloadSize、timeout、poolSize、maxRetries
3. Web アプリの場合：初期ペイロードサイズとリクエスト数を測定します
4. メモリ使用パターンを検索します：ストリーム、ページネーション、カーソル、チャンク化。これらがない場合はコードの臭いです

シグナル：切りのよい値がハードコードされたタイムアウト（30000、60000） · リストエンドポイントでのページネーション欠如 · ユーザー指定パスの同期読み込み · 上限のない配列への蓄積

出力：準拠状況のメモを含む制約一覧

Q3：暗黙の契約は何ですか？

マジック値、つまり意味に名前を付けずにビジネス上の意味を表すリテラルを見つけます。

1. 条件式内の文字列リテラルを検索します：if (x === "some_string")
2. -1、0、1、2 以外の数値リテラルを検索します
3. それぞれについて、データの_意味_が変わった場合に問題が起きないか確認します
4. データベースや外部システムに特定の値が存在することを前提とするリテラルに印を付けます

区別：設定値（ポート、バッチサイズ）は調整用のパラメーターであり、マジック値ではありません。マジック値が表すのは_意味_です。ステータスコード、型識別子、文字列比較によるビジネスロジックなどが該当します。

出力：脆弱性の一覧

Q4: 注意がどこに向かっているか

git の履歴を使って、組織の記憶を把握します。詳細な分析に取りかかる前に、まず単一のプローブコマンドを実行してください。

ステップ 1 — プローブ: 最初に git log --oneline -1 を実行します。失敗した場合（孤立ブランチ、コミットなし）は、フォールバックのシグナルに進みます。

ステップ 2a — 履歴がある場合:

1. git log --oneline -100 — 最近の活動テーマ
2. git log --format='%H' --since='6 months ago' | wc -l — 活動速度
3. 重要なファイルについては、git log --oneline -10 <file> — 変更の新しさ
4. 12 か月以上コミットがないファイルを特定します

シグナル: 3 か月間に 50 件以上のコミット → 活発な領域 · 2 年以上変更なし → 凍結状態 · 最近の「fix」／「hotfix」／「revert」の集中 → 不安定 · 単一の作成者によるファイル → 知識のサイロ化

ステップ 2b — 履歴がない場合（孤立ブランチ、新規リポジトリ、抽出されたコード）:

1. git status を確認します — ステージ済みと未追跡のファイルから意図を把握できます
2. git remote -v を確認します — リモートの有無からデプロイの成熟度を把握できます
3. git branch -a を確認します — 孤立ブランチ、または main がない場合は、初回コミット前の状態です
4. ステージング内の削除されたファイル（AD プレフィックス）を探します — 置き換えられた以前のアーキテクチャが分かります
5. 重要なディレクトリに対して ls -lt を実行し、ファイルの変更時刻を確認します

出力: 活動ヒートマップ（git 履歴から）または成熟度評価（フォールバックのシグナルから）。どのシグナルソースを使用したかを明記してください。

---

フェーズ 2：垂直スライス（価値の経路）

システム全体を調査しないでください。システムの一端からもう一端まで、観測可能な単一の値を追跡します。完全な垂直スライスを 1 つ追跡するほうが、すべてを浅く調査するよりも価値があります。

スライスの戦略は、フェーズ 0 で検出したアーキタイプによって異なります。

---

戦略 A：フロントエンドアプリケーション — 表示される値を追跡する

ステップ 1 — 値を選ぶ: 見て分かる具体的なもの。「緑色のマーカー」「ヘッダーの数字 63」などです。

ステップ 2 — 上流を追跡する（描画 → ロジック）: その値を生成するコードを探します。必要なのは、_描画箇所_です。

ステップ 3 — データを追跡する（ロジック → 状態）: 代入をさかのぼって追います。必要なのは、_判断箇所_です。

ステップ 4 — ソースを追跡する（状態 → 入力）: API、データベース、ユーザー入力など、データの発生元を探します。必要なのは、_境界_です。

ステップ 5 — 記録する: エントリーポイント、判断箇所、描画箇所、経路上の副作用を伴う呼び出し。

---

戦略 B：パイプライン — ステージを通るレコードを追跡する

パイプラインには「描画箇所」がありません。データは流れながら変換されます。自然なスライスは、取り込みから最終出力まで 1 つのエンティティを追跡することです。

ステップ 1 — エンティティを選ぶ: パイプラインが処理する具体的なデータオブジェクト。「arXiv 論文 1 件」「顧客の注文 1 件」などです。

ステップ 2 — 前方を追跡する（取り込み → 出力）: 各ステージで、次の点に答えます。

• このステージが読み取るフィールドは何ですか？
• このステージが追加、変更、削除するフィールドは何ですか？
• どのような外部呼び出しが発生しますか？
• 結果が格納される保存場所はどこですか？
• 次のステージとの間にどのような暗黙の契約がありますか？

ステップ 3 — スキーマの変化をマッピングする: 各ステージで、エンティティの形状はどのように変化しますか？これがパイプラインの実際のアーキテクチャです。

ステップ 4 — ステージ間の契約を特定する: 引き継ぎごとに、次の点を確認します。

• シリアライズ形式（JSON、JSONL、Parquet）
• 保存場所の規約（ハードコードか設定か）
• 次のステージが存在を前提とするフィールド
• 境界で検証が行われるかどうか

ステップ 5 — 記録する: データリネージマップを作成します：ステージ → 変換 → 出力場所 → 次のステージ。各境界に契約の種類を記します。

これは、パイプラインのコードベースにおける主要な成果物です。

---

戦略 C：バックエンド API — リクエストを追跡する

ステップ 1 — リクエストを選ぶ: 複数のレイヤーに関わる具体的なエンドポイントを選びます。

ステップ 2 — 内側へ追跡する: ルート → ミドルウェア → ハンドラー → サービス → 永続化。

ステップ 3 — レスポンスを追跡する: 返却するデータはどのように整形されますか？エラーはどこで捕捉されますか？

ステップ 4 — 記録する: ルート → ミドルウェアチェーン → ハンドラー → サービス呼び出し → データアクセス → レスポンスの整形。

---

戦略 D：ライブラリ／SDK — 公開 API をたどる

ステップ 1 — エクスポートされた関数を選ぶ：最もよく使われている公開 API を選びます（README またはテストを確認します）。

ステップ 2 — 内部へたどる：公開インターフェース → 内部モジュール → コアロジック。

ステップ 3 — 抽象化レイヤーを把握する：ライブラリはどこで複雑さを隠しているでしょうか？

ステップ 4 — 記録する：公開 API → 内部ディスパッチ → コアロジック → エッジケースへの対応。

---

戦略 E：Infrastructure as Code — リソースの依存関係をたどる

ステップ 1 — 中核となるリソースを選ぶ：他のリソースが最も多く依存しているものを選びます。

ステップ 2 — 依存するリソースをたどる：これを変更すると何が壊れるでしょうか？ Ref、!GetAtt、depends_on をたどります。

ステップ 3 — 影響範囲を特定する：何をまとめてデプロイする必要があるでしょうか？

ステップ 4 — 記録する：リソース → 依存するリソース → 影響範囲 → デプロイ順序。

---

全般的なガイダンス

この作業を 3～5 個の対象について繰り返します。通常、これによってシステムの真のアーキテクチャが明らかになります。

高度な手法（トレースの合流への対処、デッドコードの認識）については、references/advanced-techniques.md を参照してください。

---

フェーズ 3：問題の兆候の検出

アーキテクチャ上の問題の兆候、つまり構造的な問題を示すパターンを確認します。検出されたアーキタイプに当てはまるものを優先してください。

シグナル、リスク、検証手順を含む全項目については、references/smell-catalog.md を参照してください。

共通する問題の兆候（アーキタイプにかかわらず確認します）：

問題の兆候	シグナル	リスク
隠れたスキーマ	条件分岐で文字列と値を照合している	データ移行に対する脆弱性
サイレントオーバーフロー	サイズ制限なしで反復処理している	スケール時の障害
God Object	1000 行以上のファイル、20 個以上のメソッドを持つクラス	理解の困難化
孤立したエラー	空の catch ブロック、ログだけ記録して放置	サイレント障害
時限爆弾	ハードコードされた年、固定日付の比較	予測可能な将来の障害

パイプライン固有の問題の兆候（データパイプライン／サーバーレスパイプラインでは優先します）：

問題の兆候	シグナル	リスク
重複の不一致	複数のステージに同じ設定値がある	気づかないうちに不整合が生じる
暗黙的なステージ間契約	境界でスキーマを検証せずに dict にアクセスしている	上流の変更による予期しない破損
スキーマとしてのパス規約	ストレージパスが各ステージにハードコードされている	名前の変更に全ステージの特定が必要
検証なしの組み立て	最終ステージが完全性を確認せずに N 個の入力を組み立てる	不完全な出力が完全なものとして公開される
共有ユーティリティの単一障害点（SPOF）	50％以上のステージが 1 つの関数をインポートしている	1 つのバグでパイプライン全体が停止する

---

フェーズ 4：リスクプロファイルと不明点

ここで、探索結果を実行可能な判断材料にまとめます。読者が意思決定できる形にしてください。

リスクプロファイル — 曖昧にせず、具体的に記述します。

• 「複雑」ではなく、「User モデルの変更には、マイグレーション + API の更新 + フロントエンドの更新が必要です。」
• 「リスクが高い」ではなく、「この関数には 8 つの呼び出し元があり、テストがありません。ここでバグが発生すると、すべての論文のスコアリングが壊れます。」

不明点 — 調査しなかった内容とその理由を明記します。明示されていない前提は誤った認識につながります。

検証の手がかり — リスクの高い領域ごとに、最初に何をテストするかを記します。検証手順については、references/advanced-techniques.md を参照してください。

---

成果物

テンプレートの全文については、references/documentation-templates.md を参照してください。アーキタイプと対象読者に応じて選んでください。

適切なテンプレートを選ぶ

状況	テンプレート
アーキタイプを問わない詳細な調査	詳細調査レポート
パイプライン型の詳細な調査	パイプライン調査レポート
時間が限られている、または対象範囲が狭い	簡易評価
単一の値を追跡する	バーティカルスライス記録
パイプラインのデータフロー	データリネージマップ
対象を絞った健全性チェック	問題レポート
技術者以外のステークホルダー向け説明	ステークホルダー向け概要

出力の原則

リストではなく、マップを作成します。 コードは同じ運命をたどる単位、つまり一緒に障害が起きる、一緒に変更される、または同じ外部リソースに依存するコンポーネントごとにまとめます。

説明ではなく、意思決定を促します。 各セクションは、どこを確認するか、何を変更するか、何を避けるか、誰と調整するかを読者が判断するのに役立つ内容にします。

対象読者に適した言葉を使います。 技術者向けにはファイルパスや関数名を使います。PM やマネージャー向けには、ビジネスへの影響に置き換えます。「このコンポーネントは脆弱です」ではなく、「スコアリングアルゴリズムを変更するには、関連付けられていない 2 つのファイルを更新する必要があります。一方だけ更新してもう一方を忘れると、ニュースレターの品質が気付かれないまま低下します」と説明します。

---

クイックリファレンス

フェーズ 0：アーキタイプ → 戦略の対応付け

アーキタイプ	スライス戦略	主な成果物
フロントエンドアプリケーション	A：画面に表示される値を追跡	描画箇所の追跡
データ／サーバーレスパイプライン	B：レコードを各段階で追跡	データリネージマップ
バックエンド API	C：リクエストを追跡	リクエストライフサイクルの追跡
ライブラリ／SDK	D：公開 API を追跡	抽象化レイヤーマップ
Infrastructure as Code	E：リソースの依存関係を追跡	影響範囲マップ
CLI ツール	D（適用）：コマンドを追跡	コマンド実行の追跡
ML システム	B（適用）：トレーニングデータを追跡	データとモデルのリネージマップ

オリエンテーションチェックリスト

質問	出力
これは何ですか？（フェーズ 0）	アーキタイプの分類
問題はどこにありますか？	I/O 境界マップ
基盤となる制約は何ですか？	制約の一覧
暗黙の契約は何ですか？	脆弱性の一覧
注意がどこに向けられていますか？	アクティビティヒートマップ、または成熟度評価

値をたどる手順（アーキタイプ別）

フロントエンド（A）：値を選ぶ → 描画箇所を特定する → 判断ポイントを確認する → 入力境界を確認する → 記録する

パイプライン（B）：エンティティを選ぶ → 各段階を追跡する → スキーマの変遷をマッピングする → 契約を特定する → データリネージマップを作成する

バックエンド API（C）：リクエストを選ぶ → 内側へ追跡する → レスポンスを追跡する → 記録する

ライブラリ（D）：公開 API を選ぶ → 内側へ追跡する → 抽象化をマッピングする → 記録する

IaC（E）：リソースを選ぶ → 依存先を追跡する → 影響範囲を特定する → 記録する