shape-up

Shape Up — トップダウン設計仕様書

トップダウンで進め、漠然としたアイデアを明確な設計仕様書にまとめます。全体像から始め、各レイヤーで認識を合わせてから、詳細に進みます。これはインタビューではありません。エージェントが草案を作成し、ユーザーが形を整える共同執筆です。

使用するタイミング

• ユーザーが「shape up」「設計仕様書」「一緒に設計しよう」「システムを計画しよう」「これについて考えを整理したい」と言ったとき
• ユーザーが大規模または曖昧なプロジェクトに取り組んでいて、まず全体像を把握したいとき
• /grill-design の前 — 詳細を掘り下げるには、まだスコープが明確でないとき

基本原則

一度に一つのレイヤーだけ進めます。深掘りする前に確認します。先走ってはいけません。

ユーザーが現在のレイヤーの質問に答えられない場合は、[TBD] と記して先に進みます。不明点を掘り下げてはいけません。そうすると、ユーザーの集中力が途切れてしまいます。

ワークフロー

レイヤー 1：ビジョン

ユーザーに、何を作ろうとしているのかを平易な言葉で説明してもらいます。その後、短いビジョンの項目を一緒に作成します。

• 何を作るか — 対象を説明する一文
• なぜ作るか — 解決する問題と対象ユーザー
• 成功の基準 — 成功したとどう判断できるか

これを短いブロック（最大 5～8 行）にまとめ、ユーザーに提示します。ユーザーが納得するまで調整します。

技術スタック、アーキテクチャ、実装については、まだ質問しないでください。

レイヤー 2：スコープ

ビジョンが明確になったら、スコープを一緒に作成します。

• スコープ内 — このプロジェクトで行うこと（箇条書き）
• スコープ外 — 明確に行わないこと（箇条書き）
• 制約 — 期間、技術、チーム、予算、依存関係
• ユーザー／アクター — このプロジェクトとやり取りする人

草案を作成して提示します。ユーザーに項目を削除、追加し、スコープ内外で移動してもらいます。スコープが明確になるまで続けます。

スコープが大きくなりすぎている場合は、そう伝えます。「大きくなってきているようです。分割しますか？」

レイヤー 3：構成要素

スコープ内の作業を、3～7 個の大きなブロックに分けます。各ブロックは、主要なコンポーネント、機能領域、または作業の流れを表します。各ブロックについて、次の項目をまとめます。

• 名前 — 短いラベル
• 目的 — 一行での説明
• 依存関係 — 必要となる他のブロック

シンプルなリストまたは図で提示します。ユーザーは順序の変更、名前の変更、統合、分割を行います。ここでは骨組みだけを作り、詳細には踏み込みません。

ブロックが不明確な場合は、[TBD] と記して先に進みます。不明点が一つあるからといって、作業全体を止めてはいけません。

レイヤー 4：仕様書の草案

ユーザーが選んだ順に、各ブロックについて短い仕様書を一緒に作成します。

• 何をするか
• 重要な判断やトレードオフ
• 未解決の質問

各ブロックの仕様書は、最大でも半ページから 1 ページに収めます。長くなりそうな場合は、ブロックをさらに小さく分割する必要があるでしょう。レイヤー 3 に戻ります。

ユーザーはいつでも「今回はここまで」と言って作業を止められます。それを尊重してください。最初の段階ですべてのブロックに仕様書が必要なわけではありません。

出力

仕様書をファイルに書き込みます。ファイル名と保存場所はユーザーが決めます。ユーザーから指定がない場合は、カレントディレクトリに design-spec.md を提案します。

仕様書には複数の草案を作成できます。たとえば、draft/phase-1.md や draft/final-spec.md などです。構成はユーザーの意向に従います。

一緒に書く方法（インタビューではなく）

• まず草案を作り、質問はその後です。 質問を並べて始めないでください。把握している情報をもとに大まかな案を書き、ユーザーに修正してもらいます。
• 質問するのではなく、案を見せます。 「スコープはどうすべきですか？」と尋ねる代わりに、スコープ案を書き、「こういう理解です。違うところはありますか？」と伝えます。
• 進行を止めません。 ユーザーの回答が曖昧なら、最善の解釈を記して先に進みます。間違っていれば、ユーザーが訂正してくれます。
• 短いブロックにします。 各レイヤーの出力は、画面一つに収まる程度にします。それ以上書いている場合は、詳細に踏み込みすぎています。

してはいけないこと

• 10 個の確認質問から始めないでください（それは grill-design の役割です）
• レイヤー 1～2 で実装の詳細を話し合わないでください
• ユーザーに求められない限り、[TBD] の項目を掘り下げないでください
• 仕様書を一度にすべて書かないでください。レイヤーごとに進めます
• ユーザーが現在のレイヤーを確認していないのに、深掘りを続けないでください