Zoom Out：迷ったときにAIにまず地図を描かせる

最短だが、非常に有用

/zoom-out は、Matt の安定したエンジニアリングスキルセットの中で、おそらく最も短いものです。そのコアとなる指示は、次の一文に要約できます。

このコードブロックには慣れていません。抽象度を一段階上げ、関連するモジュールと呼び出し元のマップを、プロジェクトのドメイン言語で描いてください。

これはコードを書くためでも、リファクタリングするためでもありません。これは、非常に一般的な状態に対処するために使用されます。あなたも AI も特定のファイルに深く入り込んでしまったが、そのファイルが存在する理由を忘れ始めている状態です。

解決する失敗パターン

AI によるコーディングは、局所的な最適解に陥りやすいです。

1. ユーザーがファイルを指定する
2. AI がそのファイルを読み込む
3. AI がローカルコードに基づいて意図を推測する
4. 変更後、初めて上位の呼び出し元、ドメインルール、または ADR がその変更をサポートしていないことに気づく

人間も同様です。デバッグに時間を費やすと、特定の関数に集中しすぎて、システム内のその位置を忘れてしまうことがあります。

/zoom-out の役割は、このようなトンネルビジョンを断ち切ることです。エージェントに実装を一時停止させ、まず次のように回答させます。

• このコードブロックはどのドメイン概念に属しますか？
• 誰がそれを呼び出しますか？
• それは何を呼び出しますか？
• それの背後にある不変条件は何ですか？
• CONTEXT.md の用語とどのように対応しますか？
• 特定の ADR によって制約されていますか？

/improve-codebase-architecture との違い

/zoom-out と /improve-codebase-architecture はどちらもシステム全体を考慮しますが、目的は完全に異なります。

/zoom-out は「この部分について教えてください」という感じです。リファクタリング案を急いで提案したり、直接コードを変更したりするべきではありません。そのタスクは、認知負荷を軽減することです。

ドメイン用語を強調する理由

このスキルは、プロジェクトのドメイン用語集を使用することを明確に要求しています。理由は次のとおりです。ファイル名だけで説明すると、AI は次のようなものを出力しがちです。

OrderService は OrderRepository を呼び出し、OrderRepository は db client を呼び出します。

これは説明しているように聞こえますが、実際には説明していません。より有用なマップは次のようになります。

Checkout flow では、Order Draft はユーザーが支払う前の仮注文です。
Order Finalization は Draft を不変の Order に変換し、Inventory Reservation をトリガーします。
`OrderService.finalize()` はこの変換のシームであり、呼び出し元は主に Payment Callback と Admin Retry からです。

2番目の説明は、コードをビジネス言語に戻しています。「誰が誰を呼び出すか」を知るだけでなく、「なぜそれが存在するのか」も知ることができます。

いつ使用するのが適切か

次のシナリオで /zoom-out を積極的に呼び出すことをお勧めします。

• 見慣れないモジュールを引き継ぐ前
• バグを修正するが、関連する呼び出しチェーンがまだ不明確な場合
• AI が生成したコードをレビューしていて、正しいレベルで変更されたかどうか不明な場合
• PRD を書く準備をしていて、モジュールの境界を確認したい場合
• すでに 3 つのファイルを見たが、システム図が形成されていない場合
• /improve-codebase-architecture を実行する準備をしているが、候補領域がまだ不明確な場合

これは「始める前の 5 分間」として特に適しています。一部のバグはコードが難しいからではなく、最初からレベルを間違って見ているために発生します。

再利用可能な出力形式

元のスキルは非常に短いですが、使用時に AI にこの形式で出力させることをお勧めします。

## システムにおけるこのコードブロックの位置

## 主要なドメイン用語

## 主要モジュール

| モジュール | 責任 | 呼び出し元 | 呼び出される対象 |
|---|---|---|---|

## 主要なフロー

## 既知の制約 / ADR

## 確認すべきファイル

この形式は通常の解説よりも安定しており、後続の /to-prd や /diagnose のコンテキストに変換するのにも適しています。

プランニングモードとして使用しない

/zoom-out の危険性は、AI がマップを説明した後、そのまま「このように変更できます」と提案し始めることです。コードを理解したいだけであれば、明確に制限する必要があります。

実装案は提示せず、ファイルを変更せず、構造のみを説明してください。

その価値は、意思決定と理解を分離することにあります。理解が不十分な場合に提案を行うと、誤解をより美しく包装するだけになることがよくあります。

私の使用に関する推奨事項

/zoom-out は、他のスキルと組み合わせて使用するのに適しています。

• /zoom-out → /diagnose：まずシステムマップを確認し、次にフィードバックループを構築する
• /zoom-out → /grill-with-docs：まず既存のドメイン言語を理解し、次に新しい要件を厳しく問いただす
• /zoom-out → /to-prd：まずモジュールの位置を確認し、次に PRD を書く
• /zoom-out → /improve-codebase-architecture：まずマップを描き、次に浅い/深い問題を見つける

これは完全なプロセスではなく、単なるブレーキです。AI がローカルファイル内で変更を増やし始めたら、まず zoom out させることで、通常は後続のやり直し作業を 1 ラウンド節約できます。

参考資料

次の記事：Prototype：破棄可能なコードで設計上の質問に答える。