BuilderIO/visual-recap

ビジュアルレキャップ

/visual-recap は、diff から 構築されたビジュアルプランを作成します。これは、将来行う変更を説明するのではなく、行われた変更を、行単位のレビューよりも高い視点で説明します。同じプランデータモデルは双方向で機能します — スキーマ、API、ファイル、アーキテクチャの変更は、フォワードプランで使用されるものと同じ data-model、api-endpoint、file-tree、diagram ブロックになりますが、今回は既存の作業を要約します。レビュアーは、実際のコード行に注意を払う前に、変更の全体像を把握できます。

エージェントネイティブプランとして公開 — インライン化は禁止

成果物は常に、Plan MCP コネクターの create-visual-recap を使用して作成された、公開されたエージェントネイティブプランです。インラインチャットコンテンツ（Markdownの散文、ASCIIスケッチ、テーブル、コードフェンスで囲まれた「ワイヤーフレーム」、または「ここにレキャップがあります」という要約）では決してありません。レキャップの価値はすべて、ホストされ、インタラクティブで、注釈可能なプランにあります。インライン要約は劣化したレキャップではなく、レキャップが置き換えるものそのものです。plan（またはレガシーな agent-native-plans）ツールが見えない場合は、まずホストの tool_search を通じてそれらを発見してください。それでも見つからない場合は、即興でインラインレキャップを作成するのではなく、STOPしてユーザーにクライアント固有の再接続手順を伝えてください。公開前、またはコネクターや認証エラーが発生した場合は常に、このスキルディレクトリの references/connection.md を読んでください — これが、インライン化禁止ルール、コネクターの発見方法、およびクライアントごとの再接続手順に関する唯一の信頼できる情報源です。ローカルファイルプライバシーモード（下記）が唯一の例外です。

ローカルファイルプライバシーモード — references/local-files.md を参照

ユーザーがホスト型のPlanデータベースへの書き込みを希望しない場合（DB書き込みなし、Plan MCP公開なし、完全にローカル/オフライン/プライベートなレキャップ、または AGENT_NATIVE_PLANS_MODE=local-files）、スキーマのみの get-plan-blocks カタログルックアップを除き、ホスト型Planツールを一切呼び出さないでください。ローカルの recap collect-diff / scan / build-prompt --local-files ヘルパーを使用してdiffを読み取り、ローカルのMDXフォルダを作成し（kind: "recap" と localOnly: true を設定）、plan local check、plan local serve --kind recap、plan local verify --kind recap でプレビューします。ローカルファイルモードを使用する前に、このスキルディレクトリの references/local-files.md を読んでください — これが完全な契約の唯一の信頼できる情報源です。

使用するタイミング

PRまたはコミットが大規模、複数ファイル、またはスキーマ、APIコントラクト、アーキテクチャに影響を与え、レビュアーが生のdiffを読む前に変更が構造化ブロックにマッピングされているのを見ることでメリットが得られる場合に、レキャップを構築します。GitHub ActionはPR diffから自動的にレキャップを生成できます。エージェントはリクエストに応じて生成できます（「このPRをレキャップして」、「このブランチが何を変更したか見せて」）。小さな変更、単一ファイルの変更、または自明なdiffには使用しないでください — レキャップはレビューのオーバーヘッドであり、小さな変更はプレーンなdiffの方が速くレビューできます。

作業単位全体をレキャップする

/visual-recap が作業の完了後にチャットスレッドで呼び出された場合、デフォルトのスコープは最新のユーザーメッセージ、ツールアクション、フォローアップ修正だけでなく、現在の作業単位/スレッド全体です。会話全体にわたるスレッド所有の変更を収集します：最初の実装作業、後からのバグ修正、UIフォローアップ、テスト、チェンジセット、スキル/指示の更新、生成されたプラン/ソース成果物、およびレキャップを開くために必要なローカルインポート/リンク修正。

現在のdiffと会話コンテキストを使用して、スレッド所有の変更を、スレッドの開始前に存在していた無関係なダーティワークから分離します。無関係な既存の編集は除外します。スコープが本当に曖昧で推測できない場合は、公開する前に前提を述べるか、簡潔な質問をしてください。

フィードバック後に既存のレキャップを更新する場合、新しい修正に加えてスレッド/作業単位全体をカバーするようにレキャップを修正します。ユーザーが明示的にその狭いスコープを要求しない限り、広範なレキャップを最新のフィードバックのみの狭いレキャップに置き換えないでください。

レキャップ本文は簡潔に保つ

生成されたプラン本文に、定型のイントロ、免責事項、出典、または要約の散文ブロックを追加しないでください。特に、レキャップが補助であること、レビュアーがまだdiffをレビューする必要があること、変更されたファイル数、またはレキャップを生成したref/ワーキングツリーを伝えるための rich-text ブロックを作成しないでください。プランのタイトル、概要、および file-tree（ファイルごとの変更統計を保持します）は、すでにそのコンテキストを伝えています。

構造化ブロックが伝えない変更に関する具体的な何か（目的、実際の互換性リスク、diffで確認できる重要な決定、または根拠のあるレビューノート）をレビュアーに伝える場合にのみ、散文ブロックを追加してください。

レキャップは実質的でなければならない

簡潔であることと薄いことは同じではありません。レキャップは単一のワイヤーフレームと一文であってはなりません — それは、定型の散文が過剰に提供するのと同じくらい、レビュアーに十分な情報を提供しません。ビジュアル/構造的な見出し（ワイヤーフレーム、data-model、api-endpoint、diagram）に加えて、実質的なレキャップは実装の証拠も伝えます：

• 作成前の簡単なサーフェス/状態インベントリ：変更されたルート、コンポーネント、ポップオーバー/ダイアログ、ロール/アクセス状態、空/エラー状態、およびdiffで確認できる共有抽象化をリストします。最終的なレキャップは、意味のある各項目をブロックで表現するか、それが小さい、冗長、またはユーザーから見えないために意図的に省略する必要があります。
• 各エントリに change フラグが付いた変更ファイルの file-tree。これにより、レビュアーは一目で作業のフットプリントを確認できます。
• KEYとなる変更ファイルの分割された diff。これらは、単一の水平 tabs ブロック（デフォルトの向き、ファイルごとに1タブ）内の ## Key changes rich-text 見出しの下にグループ化され、各ファイルに1行の summary といくつかの annotations が付いています。これにより、レビュアーは高高度の全体像から直接、重要なコードにドロップダウンできます。垂直のサイドレールではなく水平のファイルタブを使用してください。これにより、選択されたファイルがサイドバイサイドのdiffを表示するのに十分な幅を確保できます。

diffの付録をスキップするのは、プレーンなdiffでより速くレビューできる本当に小さな変更（「使用するタイミング」を参照）のみです。レキャップする価値のある変更については、ファイルツリーとキー変更のdiffはプランに含める必要があります。

標準的な形状と予算

強力なレキャップは、上から下へ1つの骨格に従います：

1. UIに影響を与える見出し — diffがレンダリングされたUIを変更した場合は、最初にワイヤーフレーム。
2. 短い結果の説明（rich-text）：何が、なぜ変更されたのか、1〜3段落。
3. スキーマとコントラクトの変更のための data-model / api-endpoint ブロック。
4. change フラグが付いた変更ファイルの file-tree。
5. ## Key changes — diff / annotated-code の1つの水平 tabs ブロック。

レキャップをレビュー可能に保つ予算：

• 3〜8個のキーチェンジタブ。大規模な変更で3つ未満ではレビュアーに十分な情報を提供できません。8つを超えると要約ではなくなります。
• 各diff/注釈付きコードの抜粋は焦点を絞ったものにします — タブあたり約150行未満を推奨。長いファイルの残りは、ダンプする代わりに要約するかリンクします。
• タイトルは最大約70文字。概要は1〜3文。

これらの予算はコストの上限でもあります：徹底的であるという名目でこれらを超えないでください。また、最初のシーケンシャルパスの後で完全なdiffを再読み取りしないでください — そのパス中に取ったメモから作業してください。

良い例. 25ファイルの認証変更：ログイン画面のBefore/Afterワイヤーフレーム、2段落の説明、diff対応のセッションテーブルの data-model、新しいリフレッシュルートの api-endpoint、変更フラグ付きの file-tree、そして5つの焦点を絞ったタブ（それぞれに1行の summary と、重要なハンクに関するいくつかの注釈）がある ## Key changes。

悪い例. 要約や注釈のない、1つの巨大なセグメント化されていないdiffダンプ。または、40ファイルの変更に対する3ブロックのまばらなレキャップ（1つのワイヤーフレーム、1文、1つのファイルリスト）で、レビュアーを結局生のdiffに戻らせる。

UIへの影響にはワイヤーフレームが必要

diffがレンダリングされたUI、レイアウト、密度、視覚状態、インタラクションアフォーダンス、ナビゲーション、コントロール、メニュー、ダイアログ、またはデザイントークンを変更する場合、レキャップは1つ以上のワイヤーフレームを含める必要があります。散文やファイルのdiffは、何が視覚的に変更されたかを示す代わりにはなりません。

ワイヤーフレームを選択する前に、diffからUIカバレッジパスを作成します：

• 変更が現れるエントリサーフェスを特定します。例：ページヘッダー、リスト行、ツールバー、ルートシェル、メニュートリガー。
• 開くか変更されるインタラクションサーフェスを特定します。例：ポップオーバー、ダイアログ、タブ、シート、ドロップダウン、インラインエディター、トースト。
• 結果として生じる宛先または永続的な状態を特定します。例：公開ページ、読み取り専用ビュー、空の状態、エラー状態、ローディング状態、権限拒否状態、保存/共有状態。
• 権限が変更される場合は、アクセスまたはロールのバリアントを特定します。所有者/管理者/編集者 vs 閲覧者/非管理者の違いは視覚的な動作であり、コンパクトなマトリックス、ペアのワイヤーフレーム、または明確にラベル付けされた状態シーケンスが必要です。

UIヘビーなPRの場合、エントリサーフェスの単一のBefore/Afterだけでは不十分です。変更されたエントリポイント、主要な変更されたインタラクションサーフェス、および結果/宛先の状態を示してください。diffがタブ、ロールベースのコントロール、公開/非公開の可視性、招待/管理フロー、破壊的コントロール、または空/エラーブランチを追加する場合は、さらに多くの状態を追加します。

レビューを明確にする最小の視覚的サーフェスを選択します：

• レビュアーが直接比較からメリットを得られる場合（コントロールの削除/追加、状態の変更、レイアウト密度、順序付け、ナビゲーション、または可視のコンポーネント置換など）は、Before / After ワイヤーフレームペアを使用します。references/wireframe.md は、そのペアをどのようにレイアウトするか（列 vs. ジオメトリによる垂直スタック）を定義しています。
• 変更が純粋に追加的である場合、または「Before」状態がレビュー価値を追加せずに不在を示すだけの場合は、Afterのみのワイヤーフレームを使用します。
• UIの変更がフロー依存、レスポンシブ、またはステートフルである場合は、2つ以上のワイヤーフレームを使用します。単一のBefore/Afterペアを強制する代わりに、意味のある状態を順番に表示します。
• メニュー、ポップオーバー、ダイアログ、トースト、パネルなどの小さなサーフェスの場合は、対応する surface（popover、panel など）を使用し、焦点を絞ったサブサーフェスを表示します。配置が変更の一部でない限り、ページ全体を再描画しないでください。

各ワイヤーフレームを、変更されたUI動作、コンポーネント名、ファイルパス、およびdiffで確認できるラベル/状態に基づいて配置します。正確なピクセルがキャプチャではなく推測された場合は、ワイヤーフレームのキャプションまたは簡潔な注釈にその旨を記載します。ローカル/手動のレキャップの場合、ワイヤーフレームを保持するプランソースをインポートまたは更新して、レンダリングされたレキャップがUIビジュアルを利用可能にして開くようにします。

ワイヤーフレームの品質 — references/wireframe.md を参照

UIレキャップ/プランのワイヤーフレームは、厳格な品質基準を満たす必要があります — 全幅のクローム、固定された下部バー、実際の製品コンテンツ、Before/Afterの比較可能性、正しい surface プリセット、hexではなく --wf-* トークン、<html>/<style>/フォントタグなし。ワイヤーフレーム / <Screen> / WireframeBlock を作成する前に、このスキルディレクトリの references/wireframe.md を読んでください — これは、HTMLワイヤーフレームの品質に関する唯一の信頼できる情報源であり、/visual-plan と /visual-recap で共有されています。記憶からワイヤーフレームを作成しないでください。

標準の WireframeBlock / <Screen> フォーマットを使用して、Planビューアがサーフェスフレーム、テーマ、およびスケッチ/クリーントグルを所有できるようにします。HTMLワイヤーフレームは、配置の精度が重要な場合、特にポップオーバー、メニュー、ダイアログ、および密度の高いフォームに適しています。HTMLワイヤーフレームの場合、renderMode は設定しないか wireframe のままにします。デザイン専用の編集可能なモックアップが明示的に要求されている場合を除きます。renderMode="design" はスケッチ風のラフオーバーレイを無効にするためです。

ブラウザツールが利用可能な場合は、PlanビューアでUIに影響を与えるレキャップをレンダリングし、共有する前に現在のテーマで視覚的に検査します。ラベル、注釈、ツールバー、またはワイヤーフレームのコンテンツが別の要素と重なっている場合は、MDXを修正し、リンクを報告する前に再インポートします。これを1回のレンダリングと検査のパスと、最大1回の修正と再レンダリングに制限します。ユーザーが明示的に要求しない限り、それ以上繰り返さないでください。テキストマッチのスクリーンショットだけでは不十分です。キャプチャされた画像を視覚的に検査してください。ブラウザが利用できない場合（ヘッドレスCIエージェントなど）、そのことをレキャップの引継ぎ情報に記載します。

トップキャンバスレキャップ — ../visual-plan/references/canvas.md を参照

レキャップにトップキャンバス、ストーリーボード、またはフロービューが含まれる場合は、canvas.mdx を作成する前に ../visual-plan/references/canvas.md を読んでください。レキャップキャンバスのアートボードは、優れたドキュメント本文のワイヤーフレームと同じHTMLワイヤーフレームパスを使用する必要があります：意味論的なHTMLフラグメントを持つ <Screen surface="..." html={...} />。キャンバスの <Screen> タグ内で、<FrameScreen>、<Card>、<Row>、<Title>、<Btn> などの新しいキットツリーの子を作成しないでください。これらのコンポーネントは、古いプラン用のレガシー互換マークアップです。新しいキャンバスストーリーボードでは、インライン本文のワイヤーフレームが良く見えても、窮屈または重なったレイアウトを生成する可能性があります。キャンバスのモックアップが同じ画面を下にスクロールした場合よりも見栄えが悪い場合は、レガシーキットパスを使用したと想定し、HTML画面に置き換えてください。

レキャップを開いて報告する

ローカルファイルプライバシーモードでは、最初に plan local check を実行し、次に npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open から、または <plan-dir>/.plan-url からローカルブリッジURLを報告します。これはホスト型Plan UIを開きますが、このマシン上のlocalhostブリッジから読み取るため、マシン間で共有できません。Planアプリ自体が同じ PLAN_LOCAL_DIR でローカルに実行されている場合、/local-plans/<slug> ルートも有効です。ホスト型データベースURLをでっち上げたり、絶対的なPlanリンクを取得するためだけに公開したりしないでください。

レキャップを作成した後、実際にプランを保持しているデータベースのオリジン上の絶対URLで、レビュアーをレンダリングされたプランにリンクします。そのオリジンとは、レキャップを作成したPlan MCPサーバーです — たまたま実行されているdevサーバーではありません。作成ツールは正しいリンクを返します。それを報告してください。プライマリリンクをローカルの plan.mdx ファイル、ローカルミラーフォルダ、または /plans/<id> のような相対パスにすることは絶対にしないでください。

レキャップがプライベートリポジトリのPRに投稿される場合、プランはプライベートである必要があります。ag（ワークスペース内の他の全員）への可視性は、

[翻訳はここで中断されました。原文の続きが必要です。]

プランを作成する際に accessLevel: "workspace" を設定します。公開リポジトリの場合は accessLevel: "public" を使用します。必要に応じて、リンクを報告する前に plan visibility を実行してアクセスレベルを確認します。