agile-proto

Name: agile-proto
Author: djalmajr

github.com/djalmajrデザイン・UI4135 回インストール5 週間前に更新

リポジトリ

agile-proto について

agile-protoは、ビルド工程なしでブラウザー上のプロトタイプを作り、実装前にフローや操作を検証するスキルです。シーン構成、HTM UIの利用、操作確認、任意のFigmaキャプチャを案内します。

主な機能

01ビルド不要のHTML、CSS、JavaScriptプロトタイプ
02シーン単位のルートと配置ガイド
03HTM UIとz-protoの利用手順
04操作検証チェックリスト
05任意のFigmaキャプチャ手順

活用シーン

01本実装前のプロダクトフロー検証
02アジャイル計画資料と並べたシーン管理
03依頼されたFigma引き継ぎ用の実行中シーンの準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/djalmajr/skills --skill agile-proto

インストール後、Claude Code で/agile-protoを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

templates/

index.css

index.html

index.js

templates/routes/

home.js

templates/scripts/

bootstrap.sh

詳細

静的ブラウザープロトタイピング

本番実装の前に、フローやインタラクションを検証できる、単体で動作するプロトタイプを作成します。ビルド不要で、ブラウザー標準の機能を使います。

「静的」とは配信アーキテクチャを指します。バックエンドや必須のビルドパイプラインがなく、HTML、CSS、JavaScriptをそのまま配信できます。プロトタイプには、現実的なクライアントサイドのインタラクションを含めてもかまいません。

プロトタイプがアジャイル施策に属する場合は、インテーク、ロードマップ、ビジネスルール、今後作成するエピックの成果物と並べて、planning/<initiative>/proto/ に配置します。{app}/client-proto/ を使用するのは、プロジェクトがすでにその規約に従っている場合に限ります。

補完スキル：htm-ui

/agile-proto はプロセス（書き込み先、シーン、z-proto、Figma キャプチャ、連携方法）を扱います。コンポーネント、トークン、importmap、API、UI の例は、htm-ui スキル（https://github.com/djalmajr/htm-ui）で扱います。このパッケージにそのスキルやサンプルカタログは含まれていません。

シーンの実装を始める前に、次の手順を実行してください。

ハーネスのスキルルート（.agents/skills/、.claude/skills/、.opencode/skills/ と、それぞれの ~/ 内の同等の場所）に htm-ui/SKILL.md があるか確認します。
存在する場合は、内容を読み、コンポーネントの選択、テーマ、API の検証に従ってください。
存在しない場合は、補完スキルがないことを伝えてください。このスキルが htm-ui の代わりになるかのように装ってはいけません。インストールを依頼してください。

bunx skills add djalmajr/htm-ui --skill htm-ui

マシンに複数のエージェントがある場合は、このパッケージのインストール時と同じ --agent フラグを使用してください。

スキルがインストールされていなくても、このセッションでプロトタイプの作成を止めてはいけません。ライブドキュメント https://djalmajr.github.io/htm-ui/ と CDN モジュールを使用してください。公式の例は、apps/docs と apps/todo です。コンポーネントカタログをプロトタイプにコピーしてはいけません。

プロジェクトルート

すべてのパスは、スキルリポジトリではなく、プロトタイプがあるリポジトリを起点に解決してください。アクティブなディレクトリが兄弟リポジトリにある場合は、明示的なプロジェクトルートを前置してください。対象が本当に曖昧な場合に限り、確認してください。

プロンプト

結果に大きな影響を与える選択肢については、ハーネスの構造化質問ツールを使用してください。

判断項目	推奨する選択肢
忠実度	スケッチ · ワイヤーフレーム · 高忠実度
Figma への引き継ぎ	いいえ · はい
既存のプロトタイプ	既存のものを拡張 · 新規作成
`htm-ui` スキルがない場合	今すぐインストール · CDN／ドキュメントのみで続行

ユーザーが中断せずに実行するよう明示的に依頼している場合は、未解決の選択肢を記録し、最も安全で取り消し可能な前提を採用して進めてください。

スタック

デバイスのプリセット、ズーム、フレーミング、キャプチャ操作には z-proto を使用します。
コンポーネントには HTM UI を使用します。公開されているオリジンを検証し、カタログをプロトタイプにコピーしてはいけません。
正式な HTM UI セマンティックトークンのマッピング（htm-ui スキル／THEMING.md を参照）を適用した Tailwind CSS v4 のブラウザーモードを使用します。
レンダリング、状態管理、シーンルーティングには Preact + htm + preact-iso を使用します。
アイコンには HTM UI の Icon コンポーネント経由で Iconify を使用します。

利用側の importmap：

https://cdn.jsdelivr.net/gh/djalmajr/htm-ui@main/packages/ui/

npm リリースが確認されるまでは、esm.sh/htm-ui を参照しないでください。HTM UI のソースモジュールを components/ui/ にコピーしてはいけません。

HTM UI から取得するもの（ライブ）

このスキル内に UI のコピーを固定しないでください。起動時に、HTM UI から次のものを取得します。

要素	ソース
コンポーネント	importmap `htm-ui/<module>.js`（CDN）
トークン	`packages/ui/theme.css` および `ui.css`（CDN）
Tailwind の `@theme` マッピング	HTM UI の `THEMING.md`。`templates/scripts/bootstrap.sh` が挿入します
プロダクトシェル／シーン	`htm-ui` スキルを使い、HTM UI のプリミティブを組み合わせて作成します

HTM UI の apps/docs にある AppShell をインポートしないでください。このファイルはドキュメント用の装飾（HTM UI のブランディングや GitHub のスター表示）であり、プロダクトのスターターではありません。

構成

このスキルのテンプレートは、プロトタイプの接続部分（z-proto、ルート、Figma）のみを提供します。UI とテーマは HTM UI が担います。

planning/<initiative>/proto/
├── index.html
├── index.css
├── index.js
└── routes/
    └── home.js

routes/ にシーンをファイルごとに追加し、SCENES に登録してください。製品にシェル（サイドバー、トップバー）が必要な場合は、htm-ui/sidebar.js などを組み合わせてください。ローカルのカタログをコピーしてはいけません。

初期設定

SKILL_DIR="<folder containing this SKILL.md>"
bash "$SKILL_DIR/templates/scripts/bootstrap.sh" planning/<initiative>/proto
cd planning/<initiative>/proto
bunx serve -s .

アプリケーションの規約については、次を参照してください。

bash "$SKILL_DIR/templates/scripts/bootstrap.sh" my-app/client-proto
cd my-app/client-proto
bunx serve -s .

このスクリプトは接続部分をコピーし、HTM UI の THEMING.md から @theme ブロックを挿入します。preact-iso のルートを直接再読み込みしたときに index.html が解決されるよう、SPA モードを使用してください。

シーンの実装

htm-ui スキル（インストールされていない場合はドキュメント／CDN）に従ってください。

既存のプロトタイプとプロジェクトのルールを確認します。
最新のドキュメントと実際のモジュールエクスポートを確認します。
カスタムマークアップを書く前に、既存のコンポーネントとバリアントを選択します。
ファイルごとにインポートします。

import { Button } from "htm-ui/button.js";
import { Card, CardContent, CardHeader, CardTitle } from "htm-ui/card.js";

複数行テンプレートでは、各コンポーネントの開始／終了式をそれぞれ独立した行に記述します。
約束したインタラクションは、適切な場合に観察可能かつ元に戻せるようにします。

ドキュメント：https://djalmajr.github.io/htm-ui/components/<slug>。ランタイム：https://cdn.jsdelivr.net/gh/djalmajr/htm-ui@main/packages/ui/<module>.js。React shadcn から API を推測してはいけません。

実装の引き継ぎ

ブラウザプロトタイプは、実装に関する自己記述型の証拠です。安定したシーン ID とルートからフローを特定でき、htm-ui/<module>.js のインポートからプリミティブを特定できます。インポートを重複して記載するためだけに、必須のカタログを別途追加してはいけません。

マッピングの不足は警告であり、自動的にブロッカーになるものではありません。

シーンのパターン

各シーンは専用ファイルに配置し、安定した id と path を指定して SCENES に登録します。スケルトンはシーンを直接描画します。製品にシェルが必要な場合は、HTM UI のプリミティブを組み合わせてください。

import { html } from "htm/preact";
import { useState } from "preact/hooks";
import { Button } from "htm-ui/button.js";

export function InvitePage() {
  const [sent, setSent] = useState(false);
  return html`
    <main class="flex h-full w-full flex-1 flex-col gap-4 overflow-y-auto p-6">
      <${Button} onClick=${() => setSent(true)}>
        Send invitation
      <//>
      <p aria-live="polite" class="text-sm text-muted-foreground">
        ${sent ? "Invitation sent." : "No invitation sent yet."}
      </p>
    </main>
  `;
}

?route=<scene-id> のサポートを維持してください。Figma のキャプチャでは URL のハッシュを使用するため、テンプレートのルートブリッジは、クエリ文字列からシーンを選択する際に #figmacapture を保持する必要があります。

製品への忠実性

フォームにあらかじめ値を入力し、現実的なインラインのモックデータを使用します。
出荷される製品で表示されない限り、内部アーキテクチャ、テストに関するメモ、プロバイダー、ビジネスルールの説明を UI に表示してはいけません。
発見したドメインルールは、安定した ID を付けて planning/<initiative>/business/*.md に記録します。
基本例とバリアント例では、データ、設定、動作を明確に変えます。
製品のサーフェスにはセマンティックトークンと組み込みのコンポーネントバリアントを使用し、パレットの生のクラスは避けます。
標準の入力、セレクト、ボタンの高さを維持します。
領域が限定されたスクロール部分には ScrollArea を使用し、ドキュメントのスクロールが競合しないようにします。
オーバーレイの衝突処理をテストし、ドロップダウン／ポップオーバーのコンテンツがプロトタイプのフレームで切り取られないようにします。

インタラクションの検証

プロトタイプをページごとに検証します。レビュー担当者が動作しない例を見つけるまで放置してはいけません。

インタラクティブなシーンごとに、次を行います。

すべての主要アクションと副次アクションをクリックします。
入力とセレクトを編集し、状態が観察可能であることを確認します。
キーボードフォーカス、Enter／Space、Escape、Tab の順序をテストします。
メニューとオーバーレイが外側のクリックで閉じることをテストします。
狭い画面幅と広い画面幅のプリセットをテストします。
コンテンツのオーバーフローと内部スクロールをテストします。
コンソールエラーやモジュールの読み込み失敗がないことを確認します。
UI の文言と、実際に実装された動作を比較します。

ボタン、フォーム、トグル、メニュー、並べ替え可能なリスト、セグメント入力、オーバーレイは、静的なスクリーンショットだけでは十分に検証できません。

Figma エクスポート

まず HTML プロトタイプを構築して検証し、その後、実行中の画面をキャプチャします。主要な成果物として、手作業で近似画面を描き直さないでください。

index.html が https://mcp.figma.com/mcp/html-to-design/capture.js を読み込むことを確認します。
プロトタイプを localhost または HTTPS で配信します。
各シーンを ?route=<scene-id>#figmacapture=<captureId>&figmaselector=%23app で開きます。
ポーリング中は同じキャプチャ ID を再利用し、処理中に置き換えを生成しないでください。
キャプチャは専用の source-captures ページに配置し、ルート名を付けてレビューしやすいように並べます。
以前に手作業で作成した近似画面には、古いものであることを明記します。

手動で Figma デスクトップに貼り付ける場合は、<z-proto> に figma-key を設定し、そのキャプチャアクションを使用します。

ルール

プロトタイプにビルドツール、パッケージのインストール、JSX、TypeScript は必要ありません。
コンポーネントは htm-ui/<module>.js からのみインポートします。ローカルにコピーした UI カタログを作成しないでください。
<${Icon} icon="lucide:..." /> を使用します。lucide-react は追加しないでください。
ファイルごとにシーンを 1 つだけ配置し、SCENES に登録します。
シェルは htm-ui/ のプリミティブ（htm-ui スキル）で構成します。apps/docs やローカルカタログをコピーしないでください。
モックデータはシーン内に置きます。バックエンドは追加しないでください。
各シーンに、明示的なスクロール領域を 1 つだけ設定します。
生の色ではなく、セマンティックなテーマトークンを使用します。
インタラクションの検証を完了条件に含めます。
Figma への引き継ぎが依頼された場合は、実行中のプロトタイプをキャプチャします。
このパッケージ内で HTM UI の公式サンプルを複製しないでください。htm-ui スキルまたはドキュメントを参照してください。

チェックリスト

次のステップ

プロトタイプの検証後：

UI 中心の取り組み → /agile-epic（または、画面が限定的な場合は /agile-story）。シーン ID を Prototype refs の下に記載します。
任意：プロトタイプのルートを最初のカタログとして /ux-flows new（または discover）を実行し、その後、配信中のプロトタイプまたは後の本番アプリを対象に /ux-persona を実行します。
ユーザーがゲートを免除しない限り、未検証のプロトタイプから本番実装に進まないでください。

Markdown 対応

ログインしてコメント

基本情報

作者: djalmajr
リポジトリ: djalmajr/skills
カテゴリ: デザイン・UI
インストール数: 135
GitHub スター: 4

問題を報告