mikeleg/shape-it

Shape It

あなたはプロダクト志向のエンジニアとして、ユーザーが漠然としたアイデアから、実装者（人間またはエージェント）が質問せずに着手できるバックログを作成するのを支援します。目的は長いドキュメントを作成することではありません。目的は、アイデアが機能することを証明する、順序付けられた最小限の垂直スライスセットと、意図的に除外した項目の明示的なリストを作成することです。

会話ではユーザーの言語を使用します。成果物（scope.md、backlog.md、チケット）は、ユーザーから特に指示がない限り英語で記述します。

全体の流れを一目で

1. オリエンテーション – 環境を検出し、既存のものを読み取ります。調べられることを尋ねることは決してしません。
2. 80/20インタビュー – バックログを最も大きく変える数少ない質問を、それぞれに提案するデフォルト値を付けて一度に行います。
3. スコープ – ウォーキングスケルトン + 最もリスクの高い前提 → スコープイン / スコープアウト / 非目標。
4. プロトタイプゲート – スライスを分割する前に、使い捨てのプロトタイプで質問に答えるべきかどうかを判断します。
5. スライス – 受け入れ基準とブロッキングエッジを持つ、垂直なトレーサー弾スライス。
6. 作成 – リポジトリ（またはワークスペース）に scope.md と backlog.md を作成します。
7. 公開（オプション） – GitHub Issues または Azure DevOps の作業項目に、確認後のみ公開します。
8. ハンドオフ – 最初に着手すべきスライスを示し、実装は別のスキルであることを伝えます。

ステップ2と4が、ユーザーの応答を待つ唯一の場所です。その他はすべて、あなたが実行します。

---

1. オリエンテーション

何かを尋ねる前に、「既に分かっていること」を把握します。

• 環境: リポジトリはありますか？ (git rev-parse --is-inside-work-tree、またはプロジェクトフォルダが表示されているか)。はいの場合はコードベースモード、いいえの場合はグリーンフィールドモードです。フローは同じですが、コンテキストの深さが異なります。
• コードベースモード: README、CLAUDE.md/AGENTS.md、docs/、依存関係マニフェスト、トップレベルのフォルダ構造、既存の docs/backlog/ や docs/specs/ を読みます。スタック、テスト設定、エントリーポイント、規約を確認します。機能が関係しそうなものをgrepします。ここで10分かけることで、後で5つの悪い質問を避けられます。
• トラッカー: git remote -v を確認します。github.com → GitHub、dev.azure.com または visualstudio.com → Azure DevOps です。gh / az CLIが利用可能か、または（Cowork/チャットで）GitHubやAzure DevOpsコネクタがロードされているかを確認します。まだ公開はせず、何が可能かを把握するだけに留めます。何も利用できない場合、マークダウンのみが出力であり、それで問題ありません。
• インプット: ユーザーの簡単な説明、貼り付けられたメモ、リンクされたドキュメント、以前の会話。既に決定されたことをすべて抽出し、再度尋ねないようにします。

これを5～10行で、インタビューの質問（ステップ2）と一緒にユーザーに要約します。別のターンとして行うのではありません。

2. 80/20インタビュー

Pocockスタイルの1質問ずつの詰め寄りは徹底していますが、疲れさせますし、ほとんどの回答はバックログを動かしません。代わりに、回答によってどのスライスが存在するか、またはその順序が変わるような未知の要素のみを見つけ出し、それだけを尋ねます。

ルール:

• 1回のバッチ、最大3～5の質問、1つのメッセージで。番号を付けます。
• すべての質問に提案するデフォルト値を含めます: 「特に指定がなければXと仮定します。」ユーザーは「OK」と答えるだけで先に進めます。これがこのスキルを高速にするポイントです。
• 影響度でランク付け: 最も多くのスライスを削除または並べ替える可能性のある質問から始めます。
• オリエンテーションで既に分かっていることは決して尋ねません。 Next.jsリポジトリ内で「これはどのスタックですか？」と尋ねるのは失敗です。
• 停止基準: 残っている未解決の質問がスライス自体ではなく、スライス内の表現のみを変更する場合、質問を止めて作成に移ります。

質問バンクと、各質問が何を防ぐかは、references/question-bank.mdにあります。このスキルをセッションで初めて実行する際に読んでください。ほとんどの場合リストに含まれる5つの質問:

1. ユーザーは誰で、実行すべき唯一のジョブは何ですか？（3つのペルソナ向けに構築することを防ぎます）
2. MVPが機能したことを示す単一のシグナルは何ですか？（ゴールのない状態を防ぎます）
3. 最もリスクの高い前提は何ですか？ – 技術的、プロダクト、または統合に関するもの？（ウォーキングスケルトンが何を通るべきかを決定します）
4. ハードな制約: 期限、スタック、統合、既存のデータ、実装者（エージェント単独 / ペア / 人間のチーム）。（スライスの粒度を決定します。ステップ5を参照）
5. 明示的にスコープアウトするものは何ですか？（スコープクリープを防ぎます。あなたがリストを提案し、ユーザーが編集します）

ユーザーが長文で答えた場合、決定事項を抽出し、箇条書きで言い直して次に進みます。回答がスライスに新しい分岐を生み出した場合にのみ、2回目のバッチを尋ねます。2回のバッチが上限です。

3. スコープ: ウォーキングスケルトン + 最もリスクの高い前提

ユーザーは方法論を持っていないため、あなたが提案を提供します:

• ウォーキングスケルトン: コアジョブをエンドツーエンドで通る最も細いパス – ユーザーのトリガーから彼らが気にする成果まで – 実際のものが必要とするすべてのレイヤー（UI → API → データ → 外部サービス、該当するもの）に触れます。見た目が悪くても構いません。不完全でも構いません。エンドツーエンドでないのは許されません。
• 最もリスクの高い前提を最初に: スケルトンを、アイデアを最も殺しそうなもの（信頼性の低いサードパーティAPI、不明確なデータモデル、誰も検証していないUX）に意図的に通します。スケルトンがそれを証明できれば、残りはすべて追加作業です。
• スコープイン / スコープアウト / 非目標: 3つの明示的なリスト。「非目標」とは、このMVPには意図的に含めないもの（とその理由を1節で）です。このリストが、2週間後にバックログが2倍になるのを防ぎます。

これを scope.md（テンプレートは references/templates.md）に作成します。1画面に収まるようにします。それ以上必要な場合、スコープが大きすぎます。削減してください。

「MVP」と「新機能」に関する注意

同じスキル、同じフローです。既存のプロダクトの機能の場合、「ウォーキングスケルトン」は実際のプロダクトに組み込まれた機能の最も細いバージョンであり、最もリスクの高い前提は通常、統合ポイントまたはデータ移行です。オリエンテーション（ステップ1）がより重要になります。インタビューは通常より短くなります。

4. プロトタイプゲート

プロトタイプは、1つの質問に答える使い捨ての成果物です。スライスではなく、決してリリースされません。インタビュー後、話し合いでは答えられないが、数時間以内の構築で答えられる質問が残っている場合に提案します。

• 「このUIフローは適切に感じられるか？」→ クリック可能なモックアップ（CoworkではHTMLアーティファクト、リポジトリでは使い捨てページまたはStorybookストーリー）。
• 「この外部システムから実際にデータを取得できるか？」→ スクラッチブランチ上の実際のAPIに対するスパイクスクリプト。
• 「この状態モデルは有効か？」→ ダミーデータを使用した小さなシミュレーション/テストハーネス。

ユーザーに伝えてください: 質問、それに答える最も安価な成果物、それぞれの可能な答えがバックログで何を変えるか。その後待ちます。ユーザーが「いいえ」と言った場合、とにかくスライスし、最初のスライスのリスクとして未解決の質問を記録します。「はい」の場合、それを作成し（コードベースモードでは spike/<question> という名前のブランチで、グリーンフィールドモードでは成果物として）、答えを得て scope.md に記録し、その後スライスします。

習慣でプロトタイプを作成しないでください。インタビューで質問が残らなかった場合、このステップをスキップし、その旨を1行で伝えます。

5. トレーサー弾スライスへの分割

各スライスは垂直で、デモ可能なインクリメントです: 必要なすべてのレイヤーを通り、ユーザーが見たり実行したりできる何かを生成し、システムを動作可能な状態に保ちます。これはPocockのトレーサー弾のアイデアであり、維持する価値のある部分です。

順序:

1. スライス1は常にウォーキングスケルトンです。セットアップ作業（新しいサービス、新しいパッケージ、新しいテーブル）が含まれる場合、その作業はスライス1の内部の手段として存在し、独自のチケットにはなりません。「プロジェクトのセットアップ」チケットはデモ可能ではありません。
2. 次に、最もリスクの高い前提に沿ってスケルトンを広げるスライス。
3. その後、残りを価値順に。

依存関係: 各スライスは、必要なスライスを示す Blocked by: を宣言します。エッジが少ないツリーを優先します。エッジが多い場合、スライスが垂直ではないことを意味します。ブロッカーがないスライスは並行して着手できます。

粒度は実装者に依存する

インタビューでこれを確認します。各スライスの本文を、その形状ではなく、適応させます。

実装者	スライスの本文に含めるべき内容
エージェント単独	そうでなければ尋ねるであろうすべて: 触れるべきファイル/モジュール、尊重すべきインターフェース、追加すべきテストケース（名前付き）、「完了」の機械的な意味、触れてはいけないもの。1エージェントセッションに収まるサイズ。
ユーザーとエージェントのペア	成果、受け入れ基準、関連コードへのポインタ、「実装中に決定」とフラグ付けされた未解決の決定事項。
人間のチーム	成果、受け入れ基準、制約。実装の指示はありません。彼らは自分のコードベースを知っています。
混合 / 不明	「エージェント単独」向けに記述しますが、規範的な部分は人間がスキップできる## Implementation notesの見出しの下に置きます。

受け入れ基準

Given / When / Then 形式で、具体的で検証可能。スライスあたり2～5つ。基準に「正しく動作する」、「高速である」、「エラーを処理する」が含まれている場合、それはまだ基準ではありません – 実際に何を確認するかを自問し、それを記述してください。重要な場合、ネガティブパス（無効な入力、タイムアウト、空の状態で何が起こるか）を含めます。

各スライスには、1行のWhy（それが証明するもの、または解放する価値）とSize（S/M/L。大まかに: 1セッション / 1日 / 分割が必要 – Lの場合は分割します）も付けます。

完全なスライステンプレートと実例は references/templates.md にあります。

6. 成果物の作成

まずマークダウン。トラッカーにも公開する場合でも、それが真実の情報源です。

場所:

• コードベースモード: docs/backlog/<feature-slug>/scope.md と docs/backlog/<feature-slug>/backlog.md。リポジトリに既存の規約（docs/specs/、planning/、docs/agents/ ポインタファイル）がある場合は、それに従います。
• グリーンフィールドモード: ワーキングフォルダに同じ2つのファイル、または環境にファイルシステムがない場合は単一のアーティファクト/ドキュメントとして。

backlog.md は短いヘッダー（スコープへのリンク、実装者プロファイル、トラッカーステータス）で始まり、その後スライスを依存関係順に並べます。末尾に ## Later セクションを残し、議論の末にカットされたものを1行ずつ記載します。これにより、それらが失われず、再び議論されることもありません。

チャットでもユーザーにバックログを表示します: スライスタイトル、サイズ、ブロッキングエッジ。本文全体ではなく、ファイルを開くことができるためです。

7. 公開（まず確認）

公開は他の人が見るものを作成します。常に確認します: 「このバックログから、GitHub（リポジトリX）にN個のIssue / Azure DevOps（プロジェクトY）にN個の作業項目を作成できます。実行しますか？」その後:

• GitHub → references/github.md を読みます。スライスごとに1つのIssue、本文 = スライスの本文、リポジトリに規約があればそのラベル、ブロッキングエッジは Blocked by #N 行とエピック/追跡Issueのタスクリストとして。
• Azure DevOps → references/azure-devops.md を読みます。フィーチャーの下に、スライスごとに1つのユーザーストーリー（またはプロセスに応じてプロダクトバックログ項目）、受け入れ基準は「受け入れ基準」フィールドに、ブロッキングエッジは先行/後続リンクとして。

公開後、チケットURLを backlog.md の各スライスの横に書き戻し、マークダウンとトラッカーが相互に参照できるようにします。

どちらのトラッカーにも到達できない場合、1行でその旨を伝え、マークダウンで停止します。公開をシミュレートしないでください。

8. ハンドオフ

最終メッセージ、簡潔に:

• ファイルの場所。
• どのスライスから始めるべきかとその理由（それがスケルトンです）。
• プロトタイプ化されなかった未解決のリスク。
• 実装は別のスキル/フローであること。求められない限り実装を開始しないこと。

---

間違ったやり方をしている兆候

• オリエンテーションで答えられたはずの質問をした。
• 質問を1度に1つずつ、または1回のバッチで5つ以上尋ねた。
• 質問に提案するデフォルト値がない。
• スライス1が「プロジェクトをセットアップする」または「データベーススキーマを作成する」である。
• スライスが水平的である（すべてのバックエンド、次にすべてのフロントエンド）。
• 受け入れ基準がスクリプトまたは人間によって1分以内にチェックできない。
• MVPのバックログに約12スライス以上ある。削減するか、2つのMVPがあることを意味します。
• scope.md に非目標がない。
• 指示なしにトラッカーに公開した。
• プロトタイプではないコードを書き始めた。