メインコンテンツへ移動
AIチュートリアル

smywでコーディングAgentに先にプロトタイプを描かせてからコードを書く：インストール・レビュー・フィードバック完全ガイド

本チュートリアルでは、smywをインストールし、Claude CodeなどのコーディングAgentに開発へ着手する前に画面とフローのプロトタイプを生成させる方法を解説します。変更比較、インタラクティブなデモ、構造編集、注釈によるフィードバックを通じて、設計を繰り返し確認できます。

約18分で読了
smywでコーディングAgentに先にプロトタイプを描かせてからコードを書く：インストール・レビュー・フィードバック完全ガイド

smywとは

smyw、つまり「show me you want」は、Claude Code、DeepSeek Harnessなど、SKILL.mdに対応したAgentで使える、コーディングAgent向けのskillです。Agentがページ、インタラクションフロー、フロントエンドとバックエンドのインターフェースを変更する前に、まずコードを読み、構造化されたspecを作成し、その後オフラインで開ける単一ファイルHTMLプロトタイプを生成します。

このプロトタイプは最終的なビジュアルデザインではなく、モジュール構成、レイアウト位置、トリガー関係、機能変更を表現するための低忠実度ワイヤーフレームです。正式な実装では、引き続きプロジェクト既存のデザイン規約に従ってください。

キャンバス全体

解決する課題

従来のAgentによるコーディングフローでは、文章による要件から直接実装に入ることが多く、ページ構成、インタラクション方式、インターフェースの境界で認識のずれが生じやすくなります。smywは、要件とコードの間に視覚的な確認段階を追加します。

  1. ユーザーが機能要件を提示する。
  2. Agentがプロジェクトのコードを読み、spec.jsonを生成する。
  3. ビルドスクリプトがspecを検証し、preview.htmlを出力する。
  4. ユーザーがブラウザで案を確認、デモ、ドラッグ、注釈追加する。
  5. ユーザーがフィードバックをコピーして会話に戻す。
  6. Agentがフィードバックを反映し、次のプロトタイプを生成する。
  7. ユーザーが案を確認してから、Agentがコードを書き始める。

smywの目的はデザインツールを置き換えることではなく、実装前にユーザーとコーディングAgentが「何を変更するか、どこに配置するか、どうトリガーするか」について共通認識を持てるようにすることです。

主な機能

番号付きマーカーと変更前後の比較

プロトタイプは実際のページレイアウトに沿って画面全体を描画し、変更を色で区別します。黄色は変更、緑色は追加、赤色は削除を表します。最外層に変更があるモジュールだけに番号を付けるため、内部要素に大量の重複マーカーが表示されることはありません。

キャンバス上の番号または左側の変更一覧をクリックすると、キャンバスが該当領域にフォーカスし、右側に変更前後の部分ワイヤーフレーム、フィールドの差分、Agentの説明、コードコンポーネント、関連する関数またはインターフェースが表示されます。

変更の詳細

モジュール全体が新規追加の場合、詳細の「変更前」には、そのモジュールがもともと存在しなかったことが表示されます。内部のボタンやテキストには個別の番号が付きません。

ブロック全体の追加

コンポーネントの移動を正確に表現

コンポーネントがある位置から別の位置へ移動すると、元の位置には赤色の「移出」、新しい位置には緑色の「移入」が表示されます。2つの記録は相互に移動できるため、削除と無関係な追加の組み合わせではないことを確認できます。

移動

モーダル、メニュー、展開コンテンツ

モーダル、ドロワー、ドロップダウンメニュー、ポップオーバー、クリック後に展開されるコンテンツは、メイン画面の横にある独立したパネルに配置され、線でトリガーボタンと接続されます。1つのモーダルには複数のトリガー入口を関連付けることができ、削除されたモーダルは赤色の破線で表されます。

モーダルと接続線

多階層メニューは隣接するパネルにさらに分割されます。元の位置で展開されるコンテンツは、ページ内に紫色の破線スロットを残し、展開後に表示される位置を示します。ページ遷移と状態切り替えの接続線はデフォルトで非表示ですが、関連要素を選択すると確認でき、「すべての接続線」ですべて表示することもできます。

二次メニューと展開コンテンツ

クリック可能なデモモード

右上の「▶ デモ」をクリックすると、プロトタイプは変更枠を非表示にし、1画面で実際の操作をシミュレートします。メニューの展開、ドロワーのスライド表示、モーダルの表示、ボタン状態の変更、ページ遷移などをデモできます。

デモモード

操作できない領域をクリックすると、現在クリック可能なすべての位置が青い枠で点滅し、左側にも実行可能な操作が一覧表示されます。デモでは、戻る、最初から開始、「変更前」と「変更後」の切り替えに対応しています。

クリック可能な領域の案内

直接編集とフィードバックの集約

  • 構造を編集：コンポーネントをドラッグして順序やコンテナの所属を調整し、テキスト、種類、幅、配置を変更します。
  • 形態を変換：インラインモジュールをモーダル、ドロップダウンメニュー、ドロワー、ポップオーバーに変換すると、システムがトリガーボタンと接続線を生成します。
  • 元に戻す・やり直す：CtrlまたはCommandとZで操作を取り消せます。
  • 要素に注釈：指定した要素に、位置、インタラクション、コンポーネントの種類、スタイル、文言、機能不足などのカテゴリで意見を追加します。
  • 意見のレベル：注釈には「必須修正」「提案」「疑問」のいずれかを設定できます。
  • 全体フィードバック：スタイルに関する意見、参考方針を記録し、Agentがあらかじめ提示した確認事項に回答します。
  • パッチを返送：構造変更はIDで位置を特定するパッチとしてフィードバック末尾に付加されるため、案全体を返送する必要はありません。

インストール前の準備

smywプロトタイプのビルドに必要なのはNode.js 18以上だけです。プロジェクト自体にサーバーは不要で、実行時の依存関係もありません。まずNode.jsのバージョンを確認します。

node --version

リポジトリのエンドツーエンドテストを実行したり、スクリーンショットを再生成したりする場合は、Google Chromeもインストールする必要があります。デフォルト以外のインストールパスは、CHROME環境変数で指定できます。

smyw skillをインストール

ステップ1：リポジトリをクローン

git clone https://github.com/nishuzumi/show-me-you-want-skill.git
cd show-me-you-want-skill

ステップ2：Agentが読み取れる場所にskillを配置

Claude Codeユーザーはグローバルシンボリックリンクを作成して、すべてのプロジェクトでsmywを使えるようにできます。

ln -s "$PWD/skills/smyw" ~/.claude/skills/smyw

Agentが共通のskillsディレクトリを読み取る場合は、次の場所にリンクすることもできます。

ln -s "$PWD/skills/smyw" ~/.agents/skills/smyw

特定のプロジェクトだけで有効にする場合は、そのプロジェクトのローカルskillディレクトリにコピーします。

cp -r skills/smyw <あなたのプロジェクト>/.claude/skills/smyw

インストールが完了したら、画面やインターフェースを変更する要件をAgentに伝えるか、直接「まずプロトタイプを作って見せてください。」と伝えます。

まずリポジトリのサンプルを実行

リポジトリには生成済みのHTMLサンプルが2つ用意されています。サーバーを起動する必要はなく、ブラウザで直接開けます。

  • skills/smyw/examples/helpdesk-ai/preview.html：AIによる返信提案を追加したカスタマーサービスワークベンチの、完全な1画面サンプル。
  • skills/smyw/examples/task-tags/preview.html

サンプルのspecを変更した後は、次のコマンドでプレビューを再生成できます。

node skills/smyw/scripts/build.mjs skills/smyw/examples/helpdesk-ai/spec.json

ビルド結果は純粋なフロントエンドの単一ファイルで、オフラインで開いてレビューできます。

要件からプロトタイプを作る基本的な使い方

ステップ1：Agentに要件を説明

ビジネス目標と制約をできるだけ説明します。ただし、すべての画面の詳細を事前に決める必要はありません。例えば次のように伝えます。

カスタマーサービスチケットの詳細にAIによる返信提案を追加してください。まず既存のページとインターフェースを読み、すぐにコードを書かないでください。smywでプロトタイプを生成し、ドロワーの入口、返信の置き換えフロー、関係するインターフェースを確認させてください。

ステップ2：生成されたspecとプレビューを確認

Agentは、次のようなディレクトリに構造化された案を保存します。

.smyw/<日付>-<名前>/spec.json

続いてbuild.mjsで検証し、preview.htmlを生成します。プレビューを開いたら、次の順番で確認できます。

  1. まず「全体表示」でキャンバス全体をビューポートに収める。
  2. 黄色、緑色、赤色の変更枠が要件に合っているか確認する。
  3. 変更一覧を順にクリックし、変更前後の比較とフィールドの変化を確認する。
  4. 関連するコンポーネント、関数、インターフェースが既存コードと対応しているか確認する。
  5. 「フローの変更」と「バックエンドの変更」を開き、レイヤーをまたぐ影響を確認する。
  6. デモモードに入り、メニュー、モーダル、ドロワー、状態ボタンを実際にクリックする。

ステップ3：案を編集して注釈を追加

構造が期待どおりでない場合は、「案を編集」に切り替えてコンポーネントを直接ドラッグするか、インラインコンテンツをモーダルに変換します。直接編集に適さない意見については、要素を選択して注釈を追加し、カテゴリと優先度を設定します。

フィードバックは次の3種類に明確に分けることをおすすめします。

  • 必須修正：実装前に必ず対応する問題。
  • 提案：Agentが採用するか評価できますが、採用しない場合は理由を説明する必要があります。
  • 疑問：まず回答と確認を行い、その後どのように調整するかを決めます。

ステップ4：フィードバックをコピーしてAgentに返す

「フィードバック」ページを開き、全体的なスタイルの意見を補足し、確認待ちの質問に回答してから、「フィードバックをコピー」をクリックします。生成されたMarkdownをAgentとの会話に貼り付けます。

Agentは通常、フィードバックをfeedback-v<N>.mdとして保存し、次のコマンドを実行します。

node skills/smyw/scripts/apply-feedback.mjs .smyw/<dir>/feedback-v1.md .smyw/<dir>/spec.json
node skills/smyw/scripts/build.mjs .smyw/<dir>/spec.json

apply-feedback.mjsは古いspecをバックアップし、フィードバック内のパッチを適用してバージョン番号を増やします。フィードバックのバージョンと現在のspecが一致しない場合、より新しい案が上書きされるのを防ぐため、スクリプトは適用を拒否します。

ステップ5：確認してからコーディングを開始

次のバージョンのプロトタイプを確認し、すべての「必須修正」が反映され、「疑問」に回答されていることを確認します。他に問題がなければ、「案を確認しました。作業を開始できます」をクリックし、Agentに正式な実装段階へ進んでもらいます。

specの基本構造を理解する

smywは1つのツリーで変更前後の画面を同時に記述します。各ノードはchangeで変更を示し、インタラクションと状態はon、hidden、statesで記述します。

{
  "id": "reply",
  "type": "form",
  "label": "顧客への返信",
  "component": "<ReplyBox>",
  "change": "modified",
  "before": { "label": "返信" },
  "children": [
    {
      "id": "reply-quick",
      "type": "select",
      "text": "クイック返信",
      "change": "removed"
    },
    {
      "id": "reply-polish",
      "type": "button",
      "label": "AI 文章校正",
      "change": "added",
      "fn": "openDraftDrawer({ mode: \"polish\" })",
      "on": [
        { "action": "open", "target": "ai-drawer" }
      ]
    }
  ]
}

この例では、返信フォームのタイトルが「返信」から「顧客への返信」に変更され、既存のクイック返信が削除され、AI ドロワーを開くボタンが追加されています。component はコードコンポーネントに対応し、fn は関連する動作または API のプレースホルダーを示します。

フィールドの詳細については spec-format.md を、Agent の実行ルールについては SKILL.md を参照してください。

応用テクニック

画面、フロー、バックエンドを同時に確認する

ページレイアウトだけをレビューしないでください。API やデータの変更を伴う機能では、プロセスのスイムレーンとバックエンドの変更も確認してください。スイムレーンでは、ユーザー、フロントエンド、バックエンド、データベース、外部サービスごとに変更前後を比較できます。各ステップの移動先から、対応する画面要素に戻ることもできます。

ツールバーでコードへの影響を把握する

  • 「ƒ 関数」を開くと、要素の背後にある動作または API のプレースホルダーを確認できます。
  • 「コンポーネント」を開くと、モジュールに対応するコードコンポーネントを確認できます。
  • 「未変更部分を薄く表示」を開くと、今回の要件の影響範囲に集中できます。
  • 完全なトリガー関係を確認する必要がある場合は、「すべての接続線」を開いてください。

デモモードで状態変化を検証する

デモモードは画面遷移の確認だけでなく、状態の連動を検証するのにも適しています。たとえば、「返信ボックスに置き換える」ボタンを押すと、下書きを返信ボックスに入力してドロワーを閉じることができます。注釈には、その時点で表示していたページ、開いていた内容、クリック履歴が自動的に記録されるため、Agent による問題の再現に役立ちます。

ID を安定させる

フィードバック内の構造変更はノード ID で特定されるため、複数回のイテレーションでは既存ノードの ID をできるだけ維持してください。要素自体が削除された場合や意味が完全に変わった場合を除き、ID を不用意に変更しないでください。

ビルド検証を重視する

build.mjs は、重複 ID、変更ノードに before がないこと、「（変更なし）」で実際のモジュールを代用していること、ポップアップにトリガーがないことなど、よくある問題を検査します。エラーが発生した場合は、まず spec を修正してから、生成結果をレビューしてください。

狭いウィンドウとサンドボックスの制限に対応する

Agent のサイドプレビューなどの狭いウィンドウでは、変更一覧が「☰ 変更」ボタンに収まり、詳細はキャンバス上に表示されます。制限されたサンドボックスでは、ブラウザーによって進捗の保存や自動コピーが禁止される場合があります。コピーに失敗した場合、ページがフィードバック内容を自動的に選択するので、Ctrl または Command を押しながら C を押してください。

プロジェクトの開発とテスト

smyw 自体を変更する必要がある場合は、エンドツーエンドテストを実行するか、README のスクリーンショットを再生成できます。

node tests/e2e.mjs
node tests/readme-shots.mjs

テストには Node.js 18 以上と Google Chrome が必要です。Chrome がデフォルトのパスにない場合は、次のように指定できます。

CHROME=/path/to/chrome node tests/e2e.mjs

このプロジェクトは MIT ライセンスを採用しています。

まとめ

smyw は、コーディング Agent のワークフローを「要件を理解したらすぐにコードを書く」から、「まずコードを読み、spec を生成し、操作可能なプロトタイプを提示し、構造化されたフィードバックを収集してから実装を開始する」へと変えます。特に、ページレイアウト、ポップアップ、状態の切り替え、複数ページのフロー、フロントエンドとバックエンドの API に関わる要件に適しています。

まずはリポジトリのサンプルから試し、Agent が skill を読み取れることを確認してから、実際のプロジェクトで利用してください。変更マーカー、デモモード、直接編集、注釈、バージョン管理されたフィードバックを活用することで、要件の理解におけるずれを大幅に減らし、確認済みの方針に基づいて正式なコーディングを始められます。