prototype

プロトタイプ

プロトタイプとは、問いに答える実験的なコードです。問いによって形が決まります。仕様を詰めている最中も含め、ユーザーが範囲を定めた実験を依頼または承認した場合にのみ進めてください。継続的なイテレーションでは実装を直接進化させますが、デフォルトでプロトタイプが必要になるわけではありません。

共有プロジェクト文書とそのルールについては、project-documents.md を参照してください。未解決の提案は、合意済みの動作とは分けて記録してください。問い、判定、根拠、残っている受け入れ条件を、適切に機能の草案または仕様、および作業状況に記録してください。完了した合意は変更履歴に記録し、プロトタイプのコードには依然として本番環境での検証が必要であることを明記してください。

分岐を選ぶ

ユーザーのプロンプトや周辺のコードをもとに、またはユーザーが対応可能であれば質問して、どの問いに答えるのかを特定してください。

• 「このロジック／状態モデルは適切でしょうか？」 → logic.md。単一の共有可能な HTML ファイルを作成してください（自由に操作できるボタンと、タブ切り替え式のガイド付きウォークスルーを備えます）。紙上では考えるのが難しいケースをステートマシンに実行させ、開発者でない人でも操作できるようにしてください。
• 「これはどのような見た目にすべきでしょうか？」 → ui.md。単一のルート上に、まったく異なる UI のバリエーションを複数生成し、URL の検索パラメーターと画面下部のフローティングバーで切り替えられるようにしてください。

アプリケーション全体を作る依頼は、プロトタイプではありません。実験で答えるべき単一の問いを尋ね、範囲を絞ってください。ユーザーがアプリケーションそのものを求めている場合は、アプリケーションを作るのはプロトタイプの役割ではないと伝え、そこで終了してください。

2 つの分岐で成果物は大きく異なるため、選択を誤るとプロトタイプ全体が無駄になります。問いが本当に曖昧で、ユーザーに連絡できない場合は、周辺のコードにより合致する分岐をデフォルトで選び（バックエンドモジュール → ロジック、ページまたはコンポーネント → UI）、プロトタイプの先頭にその前提を明記してください。

両方に適用されるルール

1. 初日から実験として扱い、その旨を明確に示します。 実験をアプリケーションの動作および本番環境への提供から切り離してください。必要に応じて関連するモジュールやページの近くに配置し、プロトタイプであることが明確にわかる名前を付けてください。実験用 UI ルートでは、プロジェクトのルーティング規約に従ってください。
2. 簡単に実行できるようにします。 UI プロトタイプは、プロジェクトのタスクランナーから 1 つのコマンドで起動できるようにします：pnpm <name>、python <path>、bun <path> など。ロジックのデモは、ユーザーがダブルクリックして開ける単一の HTML ファイルにします。いずれの場合も、起動方法を考える必要がないようにしてください。
3. デフォルトでは永続化しません。 状態はメモリ内に保持します。永続化はプロトタイプで依存するものではなく、検証する対象です。問いにデータベースが明示的に含まれる場合は、検証用 DB または「PROTOTYPE, wipe me」という名前が明確なローカルファイルを使用してください。
4. 仕上げにこだわりすぎないでください。 テストは不要です。プロトタイプを 実行可能 にするために必要な範囲を超えるエラー処理も、抽象化も不要です。目的は素早く学ぶことです。
5. 状態を見えるようにします。 各アクションの後（ロジック）またはバリエーションを切り替えるたび（UI）に、関連する状態全体を出力または描画し、何が変わったかをユーザーが確認できるようにしてください。
6. 完了したら記録します。 実験を一次資料として保存し、関連する作業記録にコンテキストへの参照を記載してください。選択されなかった実験は本番環境の外に保管してください。有用性が検証されたコードは、必須の作り直しなしで統合してもかまいません。ただし、承認された受け入れと、テスト、エラー処理、外観や操作性の判断が必要な場合の受け入れを含む、アプリケーションの本番向けチェックを完了した後に限ります。統合したコードからは実験用のコントロールやラベルを削除してください。実験の成功だけでは、本番環境への準備が整ったとは判断できません。