shape-idea

アイデアの具体化

このスキルには、project-knowledge、add-stack-context、 explain-visually、build-prototype が必要です。最初の質問をする前に、 それぞれがインストールされていることを確認してください。いずれかが 不足している場合は、作業を中断し、インストールコマンド npx skills@latest add toy-crane/skills --skill <name> を示して報告してください。 プロジェクトでパッケージマネージャーのランナーが固定されている場合は、 それを使用してください。

合意形成と実装を切り分ける

具体化では決定事項を確定し、実装ではそれを適用します。元に戻す予定の編集で あっても、プロダクトのソース、設定、依存関係は変更しないでください。 1 行でも変更すると、合意形成と実装が混在し、レビューされていないコードが 残ります。

書き込みを許可するのは、仕様フォルダー、用語集、決定契約、ルートの DESIGN.md と、画面に関する決定の記録によって更新されるその読み取り経路、 およびベンダーのエージェントコンテキストのみです。実験、ベンチマーク、 プレビューはすべて、作業ツリーの外にあるスクラッチディレクトリーで 実行してください。実験で質問に答えられない場合は、仮定とそのリスクを 記録してください。コードがユーザーの意向や決定に矛盾する場合は、その 矛盾を明らかにしてください。コードは修正しないでください。

作業開始時と、spec.md に書き込む直前に、作業ツリーを確認してください。 このセッションで許可対象外のパスに加えた変更は元に戻し、学んだことだけを 残してください。セッション開始前からある未コミットの作業には手を加えないで ください。

プロジェクトの実情に基づいて決定する

最初の質問をする前に、具体化する問題と方向性、およびそれらに関係する用語と 選択肢を添えて project-knowledge を呼び出してください。このスキルは、 それらの用語について確認済みの定義、適用される決定契約、書き込みを行う 各 GLOSSARY.md エントリーまたは docs/decisions/<subject>.md ファイルの パスを返します。セッションを通じてそれらを適用し、具体化の過程で解決した 用語や確定した決定は、それぞれ同じ方法でこのスキルに戻してください。

作業単位を確定する前に、ルートに PRODUCT.md が存在する場合は読みます。 これをアプリ全体の現在の前提として扱い、選択した作業に関係するプロダクトの 制約のみを適用し、その前提を変更しなければならない不一致があれば明らかに してください。ファイル全体を作業単位の仕様に作成、編集、コピーしては いけません。PRODUCT.md がなくても、具体化は妨げられません。

ユーザーに質問する前に、入手可能な証拠から答えられることを解決してください。

サードパーティのパッケージやツールについて結論を出す際は、実際の挙動に 関する証拠を根拠にしてください。具体的には、そのパッケージやツールの ソース、ドキュメント、リリース、メンテナーの声明を確認し、それを前提に したり回避策を講じたりする前に、スクラッチコピーでこのプロジェクトの バージョンに照らして検証してください。確認した内容、十分でなかった点、 判断を見直す契機となる上流の変更を記録してください。

決定によってフレームワークまたはホステッドサービスを選択した場合は、 そのテクノロジー 1 つと、それを選択した決定、およびその根拠となる プロジェクトの証拠を添えて add-stack-context を呼び出してください。 スタック全体ではなく、そのテクノロジーだけを監査するようにします。 このスキルは、そのテクノロジーの調査、ソースの受け入れ、インストール、 ベンダードキュメントへのライブのルーティングを担当し、テクノロジーに 関する評価結果と、インストールしたスキルのパス、および追加・変更した エージェント指示の行を返します。それらを受け取ってから具体化を再開し、 評価結果を仕様に記録してください。

一度に提示する決定事項は1つだけにします

ユーザーが修正できる具体的な候補を、判断に必要な範囲で最も軽い形式で提示します。

• 不一致が起きにくい、または容易に検出できる場合は、低コストで元に戻せる選択を行います。それを上書き可能な仮定として明示し、プロジェクトの決定事項として扱わないでください。
• 誤った場合の修正コストが高い分岐では、1つの事実、値、または選択肢について、質問を正確に1つだけします。推奨する回答と簡潔な理由を添えて、回答を待ちます。
• 提案する決定がユーザーだけが知り得る情報に依存する場合は、その情報を示し、該当するかどうかを尋ねます。自分で確認できる条件は確認してください。
• 見たり試したりして判断する選択肢では、判断に基準との比較が必要な場合に限り、現在の画面を根拠として確認し、提示します。候補を1つ、または条件を統制した比較案を2〜3個表示し、関連する状態を確認して、ユーザーの反応を待ちます。画面全体のレビューにはbuild-prototypeを呼び出し、ユーザー固有の状況との比較には一時的な比較案を使います。製品の画面数とは独立して、その判断に必要なレイヤーを設定します。判断に必要な質問とコンテキストだけを渡し、既存のプロトタイプがある場合は選ばれた結果をそこに反映して、比較案は破棄し、形作りを再開します。十分なレンダラーがない場合は判断を保留し、それによって生じるリスクを記録します。
• フロー、状態モデル、または関係に複数の分岐、遷移、またはリンクがある場合は、後続の決定を行う前に図を1つ表示します。未解決の部分について質問できるのは最大1つです。回答を待ちます。1文で表現できる線形構造は、文章で示してください。
• ユーザーが決定ではなく説明を求めている場合は、質問とその対象となる情報源を指定してexplain-visuallyを呼び出します。レンダリングされた説明が返されたら、形作りを再開します。

ユーザーが確認した場合、またはユーザーが明示的に委任した決定の種類について、その権限のもとで決定した場合に、選択は確定します。今後の作業で再利用すべきであり、その根拠によって合理的な再検討を防げ、実際のトレードオフから導かれた場合に限り、プロジェクトの決定事項となります。機能に固有の選択は仕様に記載します。

レビューを省略できるのは、すでに確認済みのパターン、定型的な表示の詳細、またはユーザーが明示的に委任した場合のみです。理由を記録し、エージェントが判断した理由だけを仮定として扱います。

プロダクトの契約を作成する

実装に関わるすべての決定が確定するか、明示的に保留されるまで質問を続けます。ユーザーが完了を宣言するまで待ってはいけません。 確認済みのプロダクト変更要求を、必須の振る舞いに変換します。エージェントが選ぶコストの低いデフォルトは、上書き可能な前提として扱います。重要で未確定の振る舞いは質問するか、明示的に保留し、想定される影響を残るリスクとして記録します。保留中の分岐を確定した制約として記録してはいけません。保留が続く間にプロダクトに必要な暫定的な振る舞いは、置き換える決定を明記して保留項目の下に記述します。契約内でその振る舞いを再度記述し、実装やテストができるようにする場合は、そこでも暫定的なものとして示します。

実装の準備が整ったら、安定したプロダクト契約として docs/specs/<slug>/spec.md を作成します。必要に応じて kebab-case のフォルダーも作成します。ユーザーに見える結果、承認済みの範囲、観測可能な受け入れ基準、確定した制約とその根拠、前提、対象外の領域とその理由、保留事項、残るリスク、実装前の準備を含めます。ファイル、関数、コード構造、技術レイヤー、実装手順を予測せず、振る舞いと決定を記録します。該当するアプリレベルの制約のみを PRODUCT.md から引き継ぎます。ファイル全体の内容を重複して記述するのではなく、PRODUCT.md を正規のプロダクトコンテキストとして維持します。

この作業が、別の spec フォルダーの完了を前提とする場合は、リンクしたソースの隣に Blocked by: docs/specs/<other>/ の行をフォルダーごとに 1 行追加します。spec の言語にかかわらず、この英語のラベルをそのまま使います。これは後続の調整で参照されるリポジトリ情報なので、イシュートラッカーが設定されているかどうかに関係なく記述します。

必ず ## Setup before implementation という見出しをそのまま使ったセクションを作成します。実装に必要なリポジトリ外の作業を、ベンダーアカウント、発行済みキー、コンソールまたは DNS の設定など、1 項目につき 1 行で列挙します。各行には、必要なもの、それが実現する結果、およびこの spec の成果物を使わずに確認できる完了条件（コンソールの状態、アプリ外で実行した直接の API 呼び出し、DNS の照会など）を記述します。必要な作業がない場合は None. と記述し、秘密の値は決して書きません。誰が各項目をどのように実施するかは実装時に決めることとし、要件整理の段階では実施しません。

リポジトリの AGENTS.md または CLAUDE.md に ## Issue tracker セクションがあり、ユーザーがこの作業の元となる既存の issue を指定した場合は、記録された規約の ID 形式で、リンクしたソースの隣に Issue: <tracker>:<id> の行を追加します。ユーザーが提示した ID の場合にのみ記述します。タイトルでイシュートラッカーを検索して ID を探してはいけません。また、要件整理の段階で issue を作成してはいけません。このセクションがない場合、または既知の ID がない場合は、そのような行を記述しません。

承認済みの prototype.html がある場合はそれをリンクし、この作業が依存する各決定契約もリンクして、実装時に任意ではなく必須のソースとして読み込まれるようにします。以前の build-prototype の完了処理ですでに記述されたリンクは維持します。各リンク先がここで何を規定するかを明記し、そのソース固有のルール、しきい値、画面構成はそのソースに残します。spec が記述する制約にそれらを転記してはいけません。リンクは契約の各項目の近くに置き、1 か所にまとめてはいけません。

変更内容を評価できるようにする

最後に、プロダクトの契約全体を要約し、承認済みの変更内容をユーザーの視点から理解し、評価できるようにします。変更後にどのような体験になるかを知るために、ユーザーが仕様書を確認したり、別途質問したりする必要がないようにしてください。

意図した変更と、その重要な下流への影響が最もよく伝わる説明と、承認済みの視覚的な証拠を選びます。変更対象の画面だけを見ていると見落としやすい影響には、特に注意を払ってください。

実装開始前にユーザーが済ませられるよう、仕様書に記載された準備項目を締めくくりの説明に含めます。

意図した体験と実装済みであることを示す証拠を区別し、締めくくりの説明をプロダクトの契約内容と一致させ、次の行動を促さないでください。