map-the-landscape

全体像を把握する

網羅的なカタログではなく、役に立つメンタルモデルを構築します。詳細が理解しやすくなる構造を明らかにします。境界の内側にあるものと外側にあるもの、重要な関係性、価値やデータの流れ、このような全体像になっている理由、そして不確実性が残る部分を示します。

ズームを設定する

リクエストと利用可能なコンテキストから、以下を推定します。

• 対象： マッピングするトピック、分野、エコシステム、またはリポジトリ。
• モード： topic、repository、またはリポジトリをより広いエコシステムの中に位置付ける場合はhybrid。
• 読者： ユーザーの現在の知識と想定される用途。
• 判断： このマップがユーザーの理解や次の行動にどう役立つか。
• 深さ： snapshot、standard、またはdeep。
• 対象期間： デフォルトでは現在の状況。現状の説明に役立つ場合は歴史も加えます。

対象や意図するズーム範囲が本当に曖昧な場合に限り、確認の質問を最大1つします。それ以外の場合は、選んだ境界を示して進めます。ユーザーが簡単な概要または詳細な調査を求めない限り、深さはstandardにします。

エビデンスの扱い

調査論文のような読み心地にすることなく、マップを検証可能なものにします。

• 重要な記述には、リポジトリ内のファイルから直接確認した場合は確認済み、外部ソースに裏付けられている場合は出典あり、エビデンスから導き出した場合は推定、エビデンスが不十分な場合は不明というラベルを付けます。
• 現在の状況や変化の激しいトピックに関する主張は、権威あるソースを閲覧し、引用します。一次ドキュメント、仕様書、論文、リポジトリ、リリースノート、公式資料を優先します。
• リポジトリに関する主張は、要約に頼る前にコードとローカルのドキュメントを調べます。rg --files、マニフェスト、エントリーポイント、設定、テスト、最近の履歴を使って、そのシステム独自の用語を把握します。
• ディレクトリ名、依存関係の一覧、検索結果の抜粋、スター数、人気度を説明として提示しません。エビデンスを関係性やその影響に置き換えて説明します。
• 実装されているシステムと、明示された意図を区別します。READMEは約束を説明し、コードパスとテストは何が保証されているかを示します。

ワークフロー

1. マップの枠組みを定める

2〜3行で方向性を示します。

1. 1文のメンタルモデル：「Xは、___によって___と___をつなぐ___です。」
2. 境界：対象範囲内のもの、隣接するもの、明確に対象外とするもの。
3. 軸となる問い、または判断。

マップで答える必要がある、重要な問いを5〜9個列挙します。固定の分類に当てはめるのではなく、対象に合わせて調整します。

2. 必要最小限のエビデンスを集める

トピックの場合：

• 標準的な用語、主要なサブドメイン、重要な関係者や組織、中核となる成果物や標準、主なリソースや価値の流れを把握します。
• 現在の区分やデフォルトを説明できるだけの歴史を調べます。
• 競合する考え方、代替手段、補完要素、ボトルネック、インセンティブ、進行中の変化を探します。
• 新しいソースが例を増やすだけで、主要なノード、関係性、対立点が増えなくなったら、情報収集を終えます。

リポジトリの場合：

• リポジトリのガイダンス、ルートのREADME、マニフェスト、トップレベルのツリー、主要なエントリーポイント、設定、代表的なテストを読みます。
• 実行単位、責任の境界、永続状態、外部システム、公開インターフェース、ビルド／デプロイの経路を特定します。
• 代表的なユーザーまたはデータの流れを、エンドツーエンドで追跡します。すべてのディレクトリを読むより、実際の垂直な経路を優先します。
• アーキテクチャ、移行、未完了の変更の説明に役立つ場合に限り、最近の履歴を調べます。
• 重要なコンポーネントすべてに役割と関係性があり、少なくとも1つのエビデンスによる裏付けが得られたら、調査を終えます。

ハイブリッドの場合は、まずリポジトリをマッピングし、その周囲に重要な外部依存関係、標準、競合相手、ユーザーのみを配置します。

モード別の視点、エビデンスの対象、出力テンプレートにはreferences/map-lenses.mdを使います。この対象の構造を明らかにする視点だけを選びます。

3. 中心から外側に向かって構築する

次の順序でマップを構築します。

1. 中心: 中核となる仕事、課題、または不変条件。
2. 内側のシステム: その仕事を直接遂行する要素。
3. 支援レイヤー: インフラ、ツール、ガバナンス、およびそれを可能にする組織。
4. 外側のエコシステム: ユーザー、生産者、競合、補完要素、規制当局、および外部システム。
5. 力学: システムを動かすインセンティブ、制約、ボトルネック、フィードバックループ、およびトレンド。

主要なノードごとに、次の点を示します。

• その役割。
• 接続先。
• その接続を通じて何がやり取りされるか。
• その接続が重要な理由。

同じ役割を持つノードは統合します。孤立した事実は省きます。重要な関係が明確になった時点でマップは完成です。すべての名詞が登場するまで続ける必要はありません。

4. フローと時間をたどる

少なくとも1つのエンドツーエンドのフローを説明します。

• トピックモード：価値、資金、情報、権限、供給、または注目。
• リポジトリモード：リクエスト、イベント、データ、制御、ビルド、またはデプロイ。

次に、短い変遷を加えます。

• 以前は何が存在していましたか？
• 何が構造を変えましたか？
• どのようなレガシー制約が残っていますか？
• 現在、何が変わりつつありますか？

歴史は、現在の境界、慣習、トレードオフ、または対立を説明する場合に限って含めます。

5. 全体像をストレステストする

統合する前に、下書きに異議を唱えます。

• 重要な視点が抜けていませんか？
• コンポーネントについて、入力元と出力先との関係を示さずに説明していませんか？
• 表明された目標を、実装済みの動作と取り違えていませんか？
• ソース名が異なるだけで、同じ基盤的な役割を隠していませんか？
• 人気のある例を、カテゴリ全体と取り違えていませんか？
• どの主張が誤りだと、マップが最も大きく変わりますか？
• 選んだ境界によって、何が見えなくなりましたか？

意見の相違や不明点は、無理に整合させず明示します。証拠から複数の妥当なマップが導かれる場合は、代替案を示し、何を確認すれば区別できるかを説明します。

6. 全体像を説明する

まず最もシンプルで役に立つモデルを示し、その後、段階的に詳細を明らかにします。基本的には次の順序にします。

1. 1分でわかる全体像
2. 境界と用語
3. Mermaid 図を使ったランドスケープマップ（複雑なシステムの場合）
4. 各要素のつながり
5. 最も重要なフロー
6. ここに至った経緯と変化
7. 対立点、トレードオフ、死角
8. 次に調べること、学ぶこと
9. 証拠と不明点

文章を中心にし、図は補助として使います。対象そのものより理解しにくくなるような、過度に密な図は作りません。「公開する」「呼び出す」「資金を提供する」「保存する」「統治する」「競合する」など、わかりやすい関係ラベルを使います。

最後に、優先順位を付けた理解への道筋を示します。

• 最初に調べるべき3つの概念、ファイル、またはソース。
• たどるべき代表的なフローを1つ。
• 避けるべきよくある誤解を1つ。
• 調査する価値のある未解決の問いを1つ。

ユーザーが保存を求めない限り、マップはチャットで返します。保存する場合は、ユーザー指定のパスを使うか、既定の docs/landscape/<subject>.md に保存します。

深さの調整

• スナップショット: 1分でわかる全体像、5～8個のノード、1つのフロー、次のステップを3つ。
• 標準: レイヤー化したマップ、8～15個のノード、歴史、対立点、証拠、学習への道筋。
• 詳細: 複数のマップまたはズームレベル、競合するモデル、より多くのソース検証、および有用な場合は保存した成果物。

投資判断に使える調査、網羅的な比較、または幅広いソースの照合に基づく意思決定が必要な場合は、専用の詳細調査ワークフローに切り替えます。このスキルの役割は、全体像の把握と統合にとどめます。

障害への対処

• リポジトリが大きすぎる場合は、まず1つの垂直フローとその周辺の境界をマッピングし、次に確認する詳細レベルを特定します。
• コードにアクセスできない場合は、ドキュメントのマップと実装のマップを明確に分け、未検証の項目を列挙します。
• 最新のウェブ情報にアクセスできない場合は、利用可能な一次情報を使い、時間の経過で変わり得る不明点を明示して、網羅性を主張しないようにします。
• 対象の範囲が広すぎる場合は、浅い百科事典のような内容を作るのではなく、有用な境界を選んで明示します。
• ユーザーが複数の対象を指し得る不慣れな用語を挙げた場合は、調査を始める前にどの対象を指すのか確認します。