zoom-out

zoom-out

実装や詳細な説明に踏み込む前に、なじみのないコード領域の全体像を把握します。

判断ツリー

ユーザーは何を求めていますか？

• 「全体を俯瞰して」「一段上のレイヤーから見て」「関連モジュールと呼び出し元をマップして」「これは誰が呼び出しているの？」など、同様の把握を求める表現がある このスキルを使用します。推奨事項を提示する前に、コードのコンテキストマップを作成します。

• 特定のシンボル、ファイル、ルート、ジョブ、テーブル、コマンド、イベント、コンポーネントが指定されている 直接の呼び出し元、直接の呼び出し先、エントリーポイント、境界をまたぐ箇所を追跡します。候補マップによって既知の情報を超える根拠が得られる場合は、インベントリヘルパーを使用します。

• 機能やサブシステムが指定されているものの、具体的なエントリーポイントが明らかでない まず、ルート、コマンド、ジョブ、公開エクスポート、UI 画面、ハンドラー、テスト、マイグレーション、パッケージマニフェストから、有力なエントリーポイントを探します。

• ユーザーが「これはどう動くの？」と尋ね、単なる概要ではなく解説を求めている その領域になじみがなければ、まずマップを作成してから、最終的な解説には {{ skill:eli12 }} を使用します。

• ユーザーがバグ修正や実装を求めているが、編集対象が不明確 最初に短い俯瞰を行い、関連箇所がわかったら通常のコーディングモードに戻ります。

• ユーザーが必要としているのは、テキスト検索、文字列の出現回数、またはファイル名の検索だけ アーキテクチャマップを作成せず、{{ skill:ripgrep }} を直接使用します。

• ユーザーが永続的なリポジトリの意図やプロダクトの目的に関するドキュメントを求めている このスキルは適していません。コードの構造をマップするものであり、人間の意図を記録するものではありません。

クイックリファレンス

必要なこと	実行内容
シンボルやパス周辺の候補インベントリ（任意）	python3 scripts/zoom_out_inventory.py --repo <repo> --target "<symbol-or-path>" --json
人が読みやすいインベントリ	python3 scripts/zoom_out_inventory.py --repo <repo> --target "<symbol-or-path>"
発見方法の全体	references/discovery.md を読む
呼び出し元と呼び出し先の追跡ルール	references/caller-mapping.md を読む
最終回答の形式	references/output-contract.md を読むか、templates/zoom-out-map.md をコピーする
見落としやすいエッジケース	references/gotchas.md を読む
スキルパッケージの検証	スキルディレクトリで python3 scripts/validate.py . を実行する
ローカルのパッケージ化とプローブテストの実行	スキルディレクトリで python3 scripts/test_skill.py . を実行する

デフォルトのワークフロー

1. 対象を具体的に言い換えます。シンボル、パス、ルート、機能、ジョブ、パッケージ、またはサブシステムを明確にします。
2. リポジトリのルートと、ユーザーが指定したスコープ境界を特定します。対象が指定されておらず、文脈からも推測できない場合は、簡潔な質問を一つします。
3. 候補の調査によって有用な根拠が増える場合は、scripts/zoom_out_inventory.py を使用します。既知のパスや絞り込んだ検索で十分な場合もあります。ヘルパーの出力は手がかりであり、証明ではありません。
4. 得られた根拠に基づいて検索します。正確な識別子、ファイル名の一部、ルートのセグメント、テスト名、設定キー、テーブル名、キュー名、イベント名、API パスなどを使います。次に読むべき有用なファイルがわかっている場合は、対象を直接読みます。
5. 中心となる箇所を特定します。動作の定義、調整、公開を説明するのに必要なファイルを把握します。ファイル数の上限は設けません。
6. 一つ上の層と一つ下の層を追跡します。
   • 上流：呼び出し元、ルート、コマンド、ジョブ、イベント購読者、テスト、UI 画面、公開エクスポート。
   • 下流：サービス、データアクセス、アダプター、外部 API、キュー、ストア、機能フラグ、設定。
7. ディレクトリだけでなく、役割ごとにファイルを分類します。
8. 観察した事実と推論を区別します。呼び出し元への経路がテキスト検索に基づく場合は、実行時の接続を検証するまではその旨を明記します。
9. 簡潔なマップを提示します。見つかったファイルをすべて列挙する必要はありません。
10. 編集を予定しているユーザー向けに、次に読むべき最小限のリスト、または実装対象を提示して締めくくります。

出力仕様

必要な場合は、以下のセクションを使用してください。情報が冗長になるセクションは省略してください。

• 対象 - マッピング対象となるシンボル、ファイル、ルート、機能、またはサブシステム。
• 1 レイヤーのマップ - 関連モジュールを責務ごとに分類したマップ。
• 呼び出し元の経路 - ユーザー操作、ジョブ、コマンド、テスト、またはパブリック API から対象に実行が到達する経路。
• 呼び出し先と依存関係 - 対象が呼び出す、永続化する、公開する、インポートする、または委譲するもの。
• 境界 - またぐ所有権、パッケージ、プロセス、ネットワーク、永続化、またはフレームワークの境界。
• 根拠 - 使用したファイルパス、シンボル、検索クエリ、コマンド。
• 不明点 - 動的ディスパッチ、生成コード、フレームワークの登録、または不足しているランタイムの根拠。
• 次に読むファイル - 次に調べるファイルを、最短の順序で列挙します。

読み方ガイド

状況	読むもの
トレースを始める前に適切なエントリーポイントを見つけたい	references/discovery.md
呼び出し元、呼び出し先、境界に該当するものを判断したい	references/caller-mapping.md
根拠と不確実性のラベルを含む、一貫した最終マップを作成したい	references/output-contract.md
結果がノイズを含む、不足している、動的、またはフレームワークに依存している	references/gotchas.md

注意点

1. ディレクトリツリーはアーキテクチャマップではありません。フォルダーだけでなく、責務と実行経路を示してください。
2. テキスト上の一致は手がかりであり、検証済みの呼び出し元ではありません。経路を実際のものとして提示する前に、インポート、登録、ルート、テスト、またはランタイムの配線を確認してください。
3. 動的なシステムでは、設定、デコレーター、依存性注入コンテナー、生成コード、キュー、規約、フレームワーク登録の中に呼び出し経路が隠れていることがあります。
4. 有用な調査範囲は、通常、上流と下流にそれぞれ 1 レイヤーです。すべての依存関係が現れるまで範囲を広げると、マップの有用性が低下します。
5. 不確実性を曖昧にしないでください。根拠のない確信に満ちた図より、「呼び出し元の可能性あり、未検証」と正確に示す方が適切です。

ヘルパースクリプト

• scripts/zoom_out_inventory.py は、候補となる中心ファイル、呼び出し元候補、インポートエッジ、ディレクトリクラスター、マニフェスト、推奨する読み物の初回インベントリを作成します。
• scripts/validate.py は、構造、フロントマター、相互参照、必須ディレクトリ、評価項目、Python 構文をチェックします。
• scripts/test_skill.py は、検証、評価項目のカバレッジチェック、相互参照チェック、およびインベントリスクリプトを一時リポジトリで検証するテストを実行します。

検証に関する注記

このパッケージを保守する際は、--help でコマンド構文を確認し、scripts/test_skill.py を実行してください。このスクリプトは一時的なコードベースを構築し、インベントリヘルパーが対象との一致、呼び出し元候補、インポートエッジ、推奨する読み物を返すことを確認します。これらはパッケージ保守のためのチェックであり、ズームアウトを実行するたびに必要な前提条件ではありません。

ガイダンスが役に立たなくなった場合

ヘルパーや同梱のトレースに関する前提が実際の配線を見落としている場合は、リポジトリの登録内容と、インストール済みフレームワークの公式ドキュメントまたは一次ソースを確認してください。ランタイムの根拠を入手できない場合は、未検証のエッジを明示してください。見落とした経路、ソース／バージョン、小さな反例を添えて、標準スキルの修正を提案してください。インストール済みのコピーを黙って編集したり、観察されたアプリケーションの動作を一般的なフレームワークの説明で置き換えたりしないでください。