explain-codebase

コードベースの説明

ユーザーが必要とする詳細さで、現在の動作を説明します。システムが実際に行うことに沿って説明し、注釈付きコードや設計への批判、根拠のない過去の経緯で説明を置き換えないでください。

境界

• このスキルは読み取り専用です。コードやドキュメントを編集しないでください。
• 評価する前に、観察された動作を説明してください。依頼で問題点や改善点も求められている場合は、まず自己完結した説明を終えてから、audit-code-complexity、blast-radius-audit、test-quality-audit などの読み取り専用監査スキルを使い、その結果は説明と分けてください。
• 失敗する経路、誤った経路、遅い経路も、読み取り専用の説明対象になり得ます。報告された問題の原因調査や修正を求められた場合は、単に経路の説明を求められた場合とは異なり、diagnosing-bugs を使ってください。調査のみ、かつ編集禁止という境界を守ってください。原因の特定を求められても、修正が許可されたことにはなりません。
• 歴史的な背景を述べるのは、ADR、イシュー、コミット、ドキュメント、またはその他の信頼できる記録で裏付けられる場合に限ります。それ以外の場合は、現在の目的と推測した理由を区別してください。
• 軽微な曖昧さは、妥当な解釈を明示してそのまま進めてください。解釈の違いによって説明内容が大きく変わる場合にのみ、確認してください。

システムをたどる

1. 詳細度を選びます。 ユーザーが必要としているのが、関数の処理の説明、機能の処理フロー、サブシステムの概要のいずれかを見極めます。プロジェクトの用語集と関連する ADR が存在する場合は、ファイル名にかかわらず読みます。ただし、記載内容は現在のコードと照らし合わせて確認してください。
2. 実際の入口を見つけます。 呼び出し元、ルート、イベント、ジョブ、コマンド、ユーザー操作、公開関数など、起点から調査を始めます。リポジトリ検索と実行時の配線を使い、ファイル名から開始点を推測しないでください。
3. 実行の流れを追います。 起点から出力、状態変更、副作用、外部呼び出しがどのように生じるかを説明するために必要な呼び出しとイベントハンドラーを読みます。経路がインターフェースをまたぐ箇所では、先に進む前に、実行時にどのアダプター、実装、設定、フラグ、登録が実際に選ばれるかを確認してください。ソースコード上にあり得る経路と、説明対象のシナリオで実際に使われる経路を区別します。以下を追跡してください。
   • 各ステップを担うモジュールと関数
   • 各ステップに入るデータ、出るデータ、変化するデータ
   • 重要な分岐、検証、エラー、再試行、非同期の受け渡し
   • 状態の所有者、永続化、キャッシュ、キュー、外部依存関係
   • 別のモジュールやシステムへ責任が引き継がれる箇所
4. 証拠の不足を解消します。 呼び出し元、実装、テスト、設定、配線を使い、重要な接続関係を確認します。引き継ぎを確認できない場合は、推測せず、不明な点と不足している証拠を示してください。

本当に広範なサブシステムの場合は、入口とルーティング、データと状態、外部への作用など、独立した範囲に分けて調査します。委任が可能な場合は、それらの範囲を並行して調査し、その後、コードに照らして重複点や矛盾点を整理します。範囲の狭い質問は、ひと続きで調査してください。

依頼された経路を起点から作用まで曖昧さなく説明でき、重要なデータの変化と責任の引き継ぎを把握し、残る不確実性を明示できた時点で調査を終えます。リポジトリ全体を網羅的に列挙しないでください。

結果の説明

求められた詳細度で、最初に答えを示します。動作の説明に役立つセクションだけを使用してください。

• 概要： コードパスまたはサブシステムが何を行い、どこから始まりどこで終わるのか
• フロー： 重要なデータ変換や判断を含む、実行時の順序に沿った処理経路
• 主要な概念： フローを追うために必要な型、モジュール、ドメイン用語のみ
• 実装箇所： エントリーポイントと実装ファイルを必要最小限で示したマップ
• 注意点と不明点： 意外な動作、実行時の選択、落とし穴、未解決の証拠不足

読者が根拠を確認できるよう、正確なファイル名とシンボルを参照してください。コードの羅列よりも文章を優先してください。複数のモジュールにまたがる関係を視覚的に示すと理解しやすくなる場合に限り、簡潔なフロー図、シーケンス図、または状態図を使用してください。

観察された事実、根拠のある理由付け、推論は、明確に区別してください。説明を読めば、代表的な入力に対して何が起きるかをエンジニアが予測でき、変更やデバッグに着手する場所もわかるようにしてください。ただし、説明自体で変更や診断を提案しないでください。