zoom-out

zoom-out 概要

zoom-out の用途

zoom-out skill は、コードに関する狭い質問から一歩引いて、その周辺にある大きなシステム全体を説明するための skill です。局所的な修正にすぐ飛びつくのではなく、関連モジュール、呼び出し元、ドメイン用語を整理したいときに zoom-out skill を使います。

コード理解で特に向いている場面

これは、問題が構文ではなくアーキテクチャ上の文脈にある Code Editing ワークフローで最も力を発揮します。repo に初めて入るとき、見慣れないサブシステムを扱うとき、あるいは編集前に1つのファイルが全体の中でどう位置づくかを把握したいときに役立ちます。

何が違うのか

zoom-out は、単なる「このコードを要約して」という prompt ではありません。より高いレベルの構造とプロジェクト固有の語彙を引き出すよう促すため、生の読み飛ばしでは見落としやすい依存関係、境界線、実際に挙動を支配している関数を捉えるのに向いています。

zoom-out skill の使い方

インストールして起動する

mattpocock/skills repo に対して zoom-out install の流れを使い、そのうえで agent がすでにコードを見ている task の中で skill を呼び出します。重要なのは、直接パッチを当てることではなく、文脈を広げるよう依頼することです。

対象を狭く絞って渡す

よい zoom-out usage は、ファイル、フォルダ、機能、bug、関数といった具体的な対象から始まります。入力では、何を起点に広げたいのか、どこまで見えているのか、どんな出力形式が欲しいのかを明確にすると効果的です。たとえば: “Zoom out from src/payments/stripe.ts and show the related modules, entry points, and likely callers before I edit anything.”

まず読むべきファイルを確認する

まずは skills/engineering/zoom-out の SKILL.md を読みます。この skill は意図的に小さく、単体で完結するよう作られているためです。rules/、resources/、補助 script のような付随要素はなく、主な仕事は自分の repo の中でこの instruction をうまく適用することになります。

編集前の下調べとして使う

実践的な流れは、サブシステムを特定し、より広いマップを依頼し、返ってきた module graph と domain term を確認してから、編集範囲を決める、という順番です。この手順にすると推測が減り、一見ローカルに見えても周辺の code path を壊してしまう変更を避けやすくなります。

zoom-out skill FAQ

通常の prompt ではなく zoom-out を使うべきなのはいつ？

まだ codebase に対する自分の mental model を信頼できないときに zoom-out を使います。すでに module の境界を理解していて、必要なのが小さな変換だけなら、通常の prompt で十分なことが多いです。

zoom-out は初心者に向いていますか？

はい、特に repo を学び始めたばかりなら有用です。zoom-out guide は「この line をどう変えるか」より先に「私は system のどこにいるのか？」に答えることを目的にしています。そのため、最終実装そのものよりも、移動や把握の面で初心者向きです。

repo 検索や file の読み込みの代わりになりますか？

いいえ。repo 検索や file inspection と組み合わせて使うのが最適です。code 自体の evidence の代わりではなく、見つけた情報を整理するための方法だと考えてください。

zoom-out が向かないのはどんなとき？

作業が純粋に機械的で、範囲が極めて狭く、すでに十分理解できているなら使わなくてよいです。1つの file だけの編集、依存関係が明白な refactor、関連 module をすべて名前で指定済みの prompt では、効果が小さくなります。

zoom-out skill の改善方法

必要な map を具体的に求める

zoom-out for Code Editing で最も良い入力は、欲しい抽象度をはっきり指定したものです: “show callers,” “list upstream entry points,” “name the module boundaries,” “explain the domain vocabulary.” こうした制約があると、“explain this area” のような曖昧な依頼より、ずっと質の高い文脈 map が得られます。

何の判断材料として使うかを伝える

この skill は、文脈が何のために必要なのかを伝えると精度が上がります。たとえば “I need to add validation without breaking the checkout flow” と書けば、広い概観だけでなく、関連する edge、tests、横断的な依存関係まで出す理由が model に伝わります。

広く見てから具体化する

強い zoom-out skill の workflow は、まず広く把握し、その map が明確になってから絞り込むことです。最初の回答で重要な caller が抜けていたり、実装詳細に寄りすぎていたりしたら、task 全体を言い直すのではなく、その抜けを中心に2回目を依頼します。

よくある2つの失敗パターンに注意する

ありがちな問題は、広すぎる要約と、domain term の命名不足です。これらは、対象 file、隣接する feature area、repo 内で使われている語彙を与えることで防げます。そうすることで、model の出力をプロジェクトの実際の構造に結び付けやすくなります。