prototypekit

prototypekit

読み進めるだけでは決められないことがあります。このリデューサーは一部返金にも対応できるのか。このライブラリは想定負荷に対して十分高速なのか。この設定ページは実際にはどのような見た目にすべきなのか。prototypekit は、その疑問の答えを得ることだけを目的とするコードを書き、そのコードを捨てて答えを残します。

この逆転こそが、スキルのすべてです。プロトタイプは本番のものの下書きでも、先行作業でも、デモでもありません。プロトタイプは道具であり、道具は使い終わったら片付けます。以下のすべては、コードを使い捨てにし、答えを長く残すためにあります。

どんなときに使うか

「これをプロトタイプ化して」「これをスパイクして」「X を使い捨てで試して」「この状態モデルは持ちこたえられるか」「<難しいケース>にも耐えられるか」「十分速いか」「この2つは相互運用できるか」「この API はドキュメントが示唆する動作をするか」「アプリで3つの実装を試して」「/prototypekit」。画面の画像や、その選択肢の画像を作る場合は、インストールされていれば uikit mockup を使います。そうでなければ、利用可能な画像ツールで画像を描画します。

意図的に該当しないものが4つあります。

• ビルド工程ではありません。 ビルドスキルは、決定済みの意図をテストとビルドのゲートを通して本番コードにします。prototypekit は、実際に動くところを誰も見ていないために意図が未確定のときに実行され、本番のあらゆる基準を意図的に満たさないコードを書き、何もゲートにかけません。
• 調査工程ではありません。 調査は一次資料から答えを導き、決して構築はしません。prototypekit は構築によって答えを導き、何も引用しません。この2つは互いを補完します。調査で、参照資料では結論を出せない主張に行き当たったら、その主張をここで扱います。
• UI ビルダーではありません。 UI スキルは、プロジェクトのデザインシステムに準拠して、リリースする画面を構築します。prototypekit のモックは比較し、選び、削除するためのものです。また、準拠を意図的に崩します。すべてに準拠した3つのバリエーションは、同じアイデアのバリエーションが3つあるだけだからです。
• デモ生成ツールではありません。 依頼は多くの場合、別の形を装ってこのスキルに持ち込まれます。質問がなければ、プロトタイプもないを参照してください。

質問がなければ、プロトタイプもない

コードを1行でも書く前に、質問と、その答えによって可能になる判断を、それぞれ1文で述べてください。両方を書けないなら、まだプロトタイプ化するものはありません。

「デモを作って」「クライアント向けの概念実証を作って」「とにかく何か試して」という依頼は、柔らかい言い方をした本番作業です。理由と進め方を伝えて、一度だけ差し戻してください。これは使い捨てのものではなく、計画と本番開発を求めていると説明します。

ユーザーが再度依頼したら、変わるのは依頼内容であって、スキルではありません。 ユーザーは判断を下しました。2回も議論するのはあなたの役目ではありません。これは本番作業だとはっきり伝えたうえで、本番作業として進めてください。マーカーも、除外エントリーも、破棄もなしで、ディスク上に残します。その時点で prototypekit の役目は終わります。決してしてはならないのは、マークを付けて破棄するプロトタイプとしてデモを構築することです。そうすると、クライアントに見せるものを誰かに渡しておいて、それを削除することになります。

6つのルール

どちらのモードも、以下のルールに従います。

1. 初日から使い捨てにし、目印を付けます。 プロトタイプを作成する場所のすぐそばに配置し、プロジェクトのインポート、エイリアス、設定がそのまま機能するようにします。すべてのファイルに *.prototype.*、すべてのディレクトリに *.prototype/ という名前を付けます。この目印は見た目だけのものではありません。除外エントリーが一致するためのものであり、目印のないプロトタイプは、git add -A ひとつで main に入ってしまいます。
2. 実行を簡単にします。 プロジェクト独自のタスクランナーから実行するコマンドひとつ、またはダブルクリックするファイルひとつにします。ランナーを決めつけず、リポジトリ（package.json、Makefile、justfile、pyproject.toml、go.mod、Cargo.toml）から見つけ、ユーザーが実行するコマンドを伝えます。開発サーバーを自分で起動してはいけません。
3. 永続化しません。 状態はメモリ上に保持します。永続化は通常、頼るものではなく、検討対象です。本当にデータベースに関する問いである場合は、誰も間違えないよう PROTOTYPE_wipe_me のような名前を付けた使い捨てのものを使います。
4. 仕上げは省きます。 テスト、抽象化、実行に必要な範囲を超えるエラー処理は不要です。prototypekit は完了ゲートを決して実行しません。ゲートにかけるものはありません。
5. 状態を見えるようにします。 すべてのアクション（ロジック）またはバリアントの切り替え（UI）で、関連する状態全体を表示します。見えないプロトタイプは何も答えません。
6. 問いに答えたら止めます。 プロトタイプが完成したと感じるまで続けてはいけません。範囲ボックスが判断基準です。

手順

1. 問いを示し、範囲ボックスを描く

問いがなければ、プロトタイプもないに従って、問いと、その答えによって可能になる判断を記述します。

次に範囲ボックスを描きます。対象に含めるケースと、明示的に含めないケースを決めます。これはルール6を支える仕組みです。範囲が徐々に広がるうえ、それが前進のように感じられるため、範囲ボックスが必要です。動くスパイクができると、もう1つケースを追加し、その次はエラー処理、その次はコンポーネントの切り出しと続き、使い捨てのものが、誰も作ると決めていないアプリへといつの間にか変わってしまいます。範囲ボックスの外にあるケースは、新たな判断事項です。声に出して伝え、合意を得てください。黙って取り込んではいけません。

範囲ボックスはプロトタイプファイルのヘッダーコメントに記載します。ファイルを開き直すたびに目に入る場所であり、範囲が広がるのはまさにそのときだからです。必要だった前提もその横に記載します。誤りだと明示された前提なら修正できますが、黙ったままの前提は修正できません。

2. 分岐先を決める

• 状態モデル、リデューサー、フロー、バックエンドモジュール、実現可能性に関する問い → ロジックモード。
• ページ、画面、コンポーネント → UI モード。

どちらか曖昧で、ユーザーに確認できない場合は、周囲のコードから判断し、その前提をヘッダーに記載します。

3. 目印を付け、除外してから、書き始める

最初のファイルを作成する前に、リポジトリの追跡対象である .gitignore ではなく、プライベート除外ファイルに目印のパターンを登録します。追跡対象の ignore ファイルを編集すると、それ自体が未コミットの変更となり、コミットやレビューのツールに検出されます。そのため、何も残さないとうたいながら、スキルが差分を残すことになります。プライベート除外ファイルはローカルにのみ適用され、追跡対象のファイルには手を加えません。

git rev-parse --git-path info/exclude    # resolve the real path; never hardcode .git/info/exclude

パスを決めつけず、Git に問い合わせて取得します。リンクされたワークツリーでは .git はディレクトリではなくファイルであり、固定のパスは存在しないからです。*.prototype.* と *.prototype/ を追記するのは、それらがまだ記載されていない場合に限ります。ファイルのグロブだけではディレクトリに一致しないため、両方のパターンを登録します。追記した行を記録してください。 すでに登録されていたパターンは、それを登録した人のものです。破棄時に変更してはいけません。

プロトタイプの配置場所を伝えるのと同じ行で、設定したことも伝えます。これにより、コードを追加する前に保護策が整っていることをユーザーに知らせられます。

4. ロジックモード

第1の軸：コードはすでに存在しますか？

• 存在します。 実際のモジュールをインポートし、プロジェクト独自のランナーで実行します。表示方法は、使い捨ての開発用ルートでも、CLI ハーネスでも、スクリプトでも、プロジェクトで可能な方法を使います。これが、作業ツリー内で作業するメリットであり、実際のコードをテストできる唯一の方法です。すでにあるロジックを入力し直してはいけません。インポートしてください。インポートできないなら、プロトタイプでテストしているのは自分の入力作業です。
• これから作ります。 自己完結したファイルを1つ用意します。Web プロジェクトなら、ビルド手順もサーバーも不要な HTML にします。ダブルクリックで開けて、リポジトリを持っていない人にも添付ファイル1つで共有できます。それ以外なら、その言語で最も簡単に実行できる単一ファイルにします。

第2の軸：出力を見るのは誰ですか？

• 操作する人間です。 インタラクティブな形を作ります。すべての遷移を発生させられる自由操作用コントロールに加えて、質問の対象となる具体的な難しいケース、つまり誰も机上では推論できないケースをモデルに通すガイド付きウォークスルーを用意します。アクションのたびに状態全体を表示します。「これでしっくりくるか」は、開発者以外にしか答えられないことがよくあるため、開発者でない人でも操作できなければなりません。
• 数値またはログです。 たとえば、これで十分な速さが出るか、2つは相互運用できるか、この API はドキュメントから読み取れるとおりに動作するか、といった場合です。測定値と、その測定を行った条件を出力するスクリプトを書きます。条件のない数値は証拠になりません。

4つの組み合わせすべてで、同じゲート、同じスコープの範囲、同じ破棄方法を使います。変わるのはレンダリング先だけです。

5. UI モード

1つのルートに、構造の異なる3つのバリエーションを用意し、小さなフローティング切り替えメニューから URL の検索パラメーターで切り替えます。ルートが1つなら、開発サーバーを1回起動するだけですべてを確認でき、各バリエーションを共有用リンクで送れます。

違いを生み出すことが成果物であり、実際に失敗しやすい部分でもあります。各バリエーションは、構造上の軸（レイアウト、情報の階層、インタラクションモデル）で違いを出し、どの軸を採用したかを明示しなければなりません。 色、間隔、角丸を変えただけでは、配色違いにすぎず、バリエーションとは言えません。1つのアイデアのバリエーションを3つ用意しても、プロトタイプとしては失敗です。手間をかけても選択肢が何も増えていません。3つの軸を本当に区別できない場合に限り、3つ未満でも構いません。その場合は数合わせをせず、その理由を明記してください。

プロジェクトですでに使われているルーティングと命名規則に従い、モックを置くために新しいトップレベル構造を作ってはいけません。

UI スキルがインストールされている場合は、そのアンチスロップカタログとアクセシビリティの最低基準を取り入れます。ただし、今回の作業に限り、そのスキルのデザインシステムの優先順位は適用しないと明言してください。 その優先順位は一貫性を強制するためのものですが、一貫性はバリエーションの目的とは正反対です。そうしたスキルがインストールされていない場合（こちらが一般的です）は、上記の構造軸テストだけで十分です。

採用されたバリエーションは、出発点ではなく、証拠です。 それを実際に作り上げるのは、実ファイルを対象に、完全な一貫性を保ちながら、ゼロから取り組む別の作業です。

6. 判定を記述する

どこに記載する場合でも、4 行で記述します。

Question: <what we needed to know>
Built:    <what was made, and which cases it was driven through>
Showed:   <what actually happened>
Answer:   <the decision this unblocks, now settled>

スコープボックスから直接 Built を記述し、実行したケースと対象となる遷移を明記します。この具体性が、コードを残さずに回答を後からも役立つものにします。また、6 週間後に判断が再び議論される際にも必要な情報です。

質問が寄せられた場所に記載します。

• 計画ドキュメントの場合。 未解決の質問を取り消し、プロトタイプを引用して、決定済み事項のセクションに行を追加します。 回答済みの質問を「Open questions」に残してはいけません。後続でそれを読むすべてのものに、計画の状態を誤って伝えてしまいます。これは prototypekit が追跡対象ファイルに加える唯一の編集であり、意図的なものです。また、ユーザーが指定したファイルだけを編集します。新たな決定済み事項は重要な編集なので、計画に Grilled: の行がある場合は、同じ編集でその行を削除し、その旨を伝えます。計画には再度のグリルが必要です。
• イシューの場合。 コメントを残します。
• どちらでもない場合。 チャットで報告します。

プロトタイプが、尋ねられたものとは別の質問に答えた場合は、報告してそこで止めます。 判定では、尋ねられた質問はまだ未解決であることを示し、見つかったことをその横に報告します。実行中に新しい質問を追いかけるのは、スコープボックスが防ごうとしているまさにその逸脱であり、もっともらしい理由をまとっているだけです。ユーザーがそれを追いかけてほしいとは限りません。ただし、見つかったことが尋ねられた質問の前提を無効にする場合（状態モデルが成立せず、「成立するかどうか」を問うことに意味がない場合）は、それが回答であり、ひとつの回答として報告します。

7. 退避してから処分する

まず退避を提案し、文字どおりのコマンドを添えたひとつの依頼にします。 このスキルの前提は、回答には意味があり、コードには意味がないということなので、退避はデフォルトで行いません。

git diff --cached --name-only    # record the staged set first
git checkout -b prototype-<slug> && git add -f <files> && git commit -m "prototype: <question>" -- <files> && git checkout -

-- の後にあるパスのリストにより、コミット対象をプロトタイプのファイルに限定します。そのため、ユーザーがすでにステージした作業はステージ済みのまま残り、退避対象にはなりません。退避後、もう一度 git diff --cached --name-only を実行し、記録した一覧と一致することを確認します。チェックアウトによって退避したファイルが作業ツリーから取り除かれるため、下記の削除を行う時点でファイルはなくなっています。

次に、ファイルごとに確認して削除します。 このセッションで作成したファイルをすべて列挙し、ひとつずつ個別に確認します。これは形式だけの手順ではありません。除外されたファイルは未追跡なので、git では復元できず、その削除は通常の削除とは違って取り消せません。このセッションで作成していないファイルには絶対に触れません。

除外エントリーを削除するのは、プロトタイプのファイルがすべてなくなった場合に限ります。また、追記したと記録した行だけを削除します。ユーザーが残すファイルは、絶対パスとともに報告し、その除外行は残します。そうすることで、残ったファイルを誤ってコミット可能な状態にせず、ローカル専用のまま見つけられるようにします。

8. 引き継ぐ

このセクションは手順を示す文体で書きます。1 文につき 1 つの指示とし、能動態、現在形、比喩なしで記述します。

変更内容。 作成したファイル、削除したファイルとユーザーが残すことにしたファイル、削除した除外行と残した除外行、退避を行ったかどうか、Grilled: の行を削除したかどうかを報告します。

記載場所。 判定を記載した場所をパスで示します（計画ファイルと追加した行、イシュー、またはチャット）。まだディスク上に残っているものがあれば、その絶対パスも示します。

次の手順。 次の行動をひとつ選びます。

• 回答によって計画上の決定が確定した場合 → 計画スキルまたはグリルスキルで計画に反映します。それらがない場合は、計画を直接編集します。
• UI のバリエーションが選ばれた場合 → UI スキルで実装します。それがない場合は、要件に完全に準拠する形で一から実装します。モックが正式採用されることはありません。そのため、マーカーだけを取り除いたプロトタイプのコピーは作りません。
• 元に戻しにくいトレードオフが決着した場合 → ドメインスキルまたは意思決定スキルを使って ADR に記録します。それらがない場合は、手作業で ADR を作成します。

実際にインストールされている場合に限り、関連するスキルの名前を挙げ、必ず通常の代替手順も示します。

注意事項

• 決して無人で実行しません。 成果物は人間の判断を得るためのものなので、誰も見ていない状態でプロトタイプを実行すると、ファイルが削除され、誰にも読まれない回答が生まれます。自律型パイプラインには組み込まないでください。ファイルごとの削除確認により、これは単なる推奨ではなく、構造上の制約になります。
• 決して昇格しません。 検証済みの判断を実際のコードに反映するには、実ファイルを対象にした新たなビルドを行い、独自の入力とゲートを設けます。プロトタイプの名前を変更するだけでは済ませません。
• ユーザーが判定の保存先として指定したプランまたはイシューを除き、追跡対象のファイルには一切触れません。除外エントリーは設計上、ローカル限定です。
• （明示的に提示された退避を除き）コミットせず、プッシュせず、PR を作成せず、イシューを登録せず、サーバーを起動しません。
• 一時ファイルの管理ツールではありません。 このセッションで作成したものだけを削除し、それ以外には手を付けません。
• ツール。 allowed-tools ではウェブ検索とフェッチを利用できません。これは、リサーチ用スキルでシェルの利用を制限するのと同じです。prototypekit は構築によって回答し、何も引用しません。ドキュメントで解決できる質問だと判明した場合は、リサーチの仕事です。不足しているツールにより、このフィールドを尊重するホストでは境界が保たれます。
• ファイルシステムやシェルを利用できない場合（ブラウザベースのエージェントなど）は、プロトタイプを保存先のパスとともにコードフェンス付きブロックで出力し、除外と削除の手順を完全に省略して、判定を本文中に示してください。何も書き込まれていなければ、削除の問題は自ずと解決します。