spec-builder

仕様ビルダー

構造化されたインタビューを通じて、漠然としたアイデアを具体的で実行可能な仕様書に変換します。

ワークフロー

フェーズ 1：初期コンテキストの収集

まず、アイデアについて尋ねます。

What's the idea you'd like to turn into a spec?
Describe it however it exists in your head right now - it can be vague.

次に、インタビューの深さを調整するため、背景について質問します。

AskUserQuestion:
1. "What's your background?"
   - Technical (developer/engineer)
   - Semi-technical (PM, designer, technical founder)
   - Non-technical (business, creative, general user)

2. "What's the goal for this spec?"
   - MVP/prototype to test the idea
   - Full product spec for development
   - Implementation plan for an AI coding agent
   - Pitch document for stakeholders
   - Personal reference to clarify my thinking

フェーズ 2：詳細なインタビュー

AskUserQuestion を使い、質問をまとめて（関連する質問を 1 回につき 2～4 個）インタビューを実施します。

ルール：

• 決して決めつけないでください。不明瞭な点があれば質問します
• すべての質問に、妥当なデフォルトの選択肢を用意します
• 最適なデフォルトの選択肢には「（推奨）」を付けます
• ユーザーが考慮していないニーズも予測します
• ユーザーの技術レベルに応じて、質問の深さを調整します

ユーザーの背景に応じた質問の調整：

トピック	技術的なユーザー	技術に詳しくないユーザー
アーキテクチャ	「REST、GraphQL、tRPC のどれですか？」	省略して、自分で決定します
データストレージ	「SQL と NoSQL のどちらですか？どの DB ですか？」	「セッション間でデータを記憶する必要がありますか？」
UI フレームワーク	「React、Vue、Svelte のどれですか？」	省略して、自分で決定します
ホスティング	「サーバーレス、コンテナ、VM のどれですか？」	省略して、自分で決定します
認証	「OAuth、マジックリンク、パスワードのどれですか？」	「ユーザーはどのようにログインしますか？」（平易な選択肢）
規模	「同時接続ユーザー数の予想は？」	「一度に何人くらいが利用しそうですか？」

根幹に関わる決定を優先します：

すべての決定が同じ重みを持つわけではありません。後から簡単に見直せるものもあれば、基礎となるものもあります。基礎となる決定は、コアアーキテクチャ、UX、物理設計を左右し、やり直しに大きなコストや労力がかかります。インタビューでは、_この特定の製品_にとって根幹に関わる決定を特定して明らかにし、先に進む前にユーザーの明示的な承認を得る必要があります。これは、あらゆる種類の製品に当てはまります。

判断基準：「リリース後／本番稼働後にこれを変更すると、大幅な手直し、データ移行、ツールの入れ替え、または再設計が必要になりますか？」必要になる場合は、根幹に関わる決定なので、早い段階で話し合う必要があります。そうでなければ、後から反復的に改善できるため、インタビューに多くの時間を割く必要はありません。

何が根幹に関わるかは、製品によって異なります。判断の参考となる例をいくつか挙げます。

• ストレージとデータアーキテクチャ（ソフトウェア）— コンテンツの保存場所、アップロードのタイミング、信頼できる唯一の情報源
• 非同期処理パターン（ソフトウェア）— 長時間かかる操作の追跡方法、ポーリングを行う主体、進捗の通知方法
• 並行処理モデル（ソフトウェア）— 最初から並列ワークロードを前提にシステムを設計するかどうか。後から対応するには全面的な書き直しが必要になるためです
• コアとなる仕組みと形状（ハードウェア）— 製品が基本的にどのように動作するか、寸法、電源
• 製造プロセスと素材（ハードウェア）— 射出成形、CNC 加工、3D プリントの違いが、コスト、公差、リードタイムを左右します
• 規制と認証要件（ハードウェア）— 後から規制への適合を考慮すると、コストのかかる再設計につながります
• UI/UX モデル（すべて）— 色や文言のように簡単に変えられるものもあれば、根幹に関わるものもあります（たとえば、リアルタイムの共同作業インターフェースと非同期ワークフローの違いや、データモデル全体の基盤となるフィード形式のレイアウト）
• サードパーティ依存関係（すべて）— プロバイダーを切り替えるには、多くの場合、連携機能を書き直し、異なるデータ形式に対応する必要があります
• 認証と ID モデル（ソフトウェア／サービス）— 認証システム間でユーザーを移行するのは、非常に大きな影響を伴います

これらはあくまで例であり、チェックリストではありません。製品ごとに、「コンクリートに埋め込まれたもの」と「家具の配置換え」に相当するものを、基本原則に立ち返って考え、それに応じてインタビューの内容を調整してください。 技術に詳しいユーザーには、設計の根幹に関わる判断について直接尋ねてください。技術に詳しくないユーザーには、概念をわかりやすく説明しつつ、承認を得てください。たとえば、「フロントエンドではリクエスト ID を使ってポーリングしますか、それともサーバー送信イベントを使いますか？」ではなく、「生成に30秒かかる場合、ユーザーにはリアルタイムで進捗を表示しますか、それとも完了時に通知するだけにしますか？」と尋ねます。

判断を覆すのが難しいほど、インタビューに時間をかけてください。 この製品で簡単に変更できる点については、ユーザーが話題にしない限り、深掘りしないでください。

確認するインタビュー領域（製品の種類に応じて調整してください）：

ソフトウェア製品の場合：

• 中核機能（何をする製品ですか？）
• ユーザーの種類と権限
• 主要なユーザーフロー（手順ごと）
• データモデル（どのようなエンティティがあり、どう関連していますか？）
• インテグレーション（外部サービス、API、フォールバック戦略）
• エッジケースとエラー処理
• セキュリティとプライバシーの要件
• プラットフォーム（Web、モバイル、デスクトップ、CLI）

物理製品の場合：

• 中核機能
• ユーザーとのやり取り（どのように使いますか？）
• 製造上の考慮事項
• 安全要件
• 梱包と配送

すべての製品について：

• この製品固有の、設計の根幹に関わる判断（上記を参照）

すべての製品について：

• 成功基準（どのように動作を確認しますか？）
• 制約（予算、スケジュール、必須要件）
• アンチゴール（明確に実現しないこと）

質問をまとめて提示する例：

AskUserQuestion (batch):
1. "Who are the main users of this product?"
   - Single user type (just me / general public)
   - Two distinct roles (e.g., admin + regular user)
   - Multiple user types (need to define each)

2. "Do users need accounts?"
   - No accounts needed (Recommended for MVP)
   - Simple accounts (email/password)
   - Social login (Google, GitHub, etc.)
   - Enterprise SSO

フェーズ 3：ドラフトのレビュー

中核的な質問（約10〜15回に分けて提示）を確認したら、ドラフトの概要を提示します。

Here's the spec outline based on our conversation so far:

## [Product Name] - Spec Outline

**Overview:** [1-2 sentences]

**Core Features:**
1. [Feature A]
2. [Feature B]
...

**User Types:** [list]

**Key Flows:** [list main workflows]

**Technical Approach:** [high-level decisions]

**Open Questions:** [things still unclear]

---

Does this capture your vision? What's missing or wrong?

次に AskUserQuestion を使ってフィードバックを得ます。

1. "How does this outline look?"
   - Looks good, continue with details
   - Missing something important (I'll explain)
   - Some parts are wrong (I'll clarify)
   - Let's pivot direction

フェーズ 4：詳細の確認

フィードバックに基づき、次の項目について詳しい追加質問をします。

• 概要の不明確な箇所
• エッジケースとエラー状態
• UI/UX の具体的な詳細
• 技術的な制約
• 「未解決の質問」として記された事項

あらゆる曖昧さが解消されたと確信できるまで続けてください。

フェーズ 5：仕様書の作成

最終仕様書を、現在のディレクトリに spec-<product-name>.md として作成します。

仕様書の形式に関する原則：

• AI コーディングエージェントが実装できるだけの詳細さを備える
• 人が確認しやすい構成にする（見出し、箇条書き、表を使用）
• 曖昧な表現を避ける。すべての要件を具体的にする
• 明示的なアンチゴールと対象外の項目を含める
• 単独で読める文書として作成する。インタビューの過程や「会話の内容」に言及しない

仕様書の構成（製品の種類に応じてセクションを調整してください）：

# [Product Name] Spec

## Overview

[2-3 sentences: what it is, who it's for, core value prop]

## Goals & Non-Goals

### Goals

- [Concrete goal 1]
- [Concrete goal 2]

### Non-Goals (explicitly out of scope)

- [What this product will NOT do]

## User Types

[Table or list of user types and their permissions/capabilities]

## Core Features

### Feature 1: [Name]

**Purpose:** [Why this feature exists]
**Behavior:**

- [Specific behavior 1]
- [Specific behavior 2]
  **UI:** [Description or wireframe reference]

[Repeat for each feature]

## User Flows

### Flow 1: [Name]

1. User does X
2. System responds with Y
3. User sees Z
   ...

[Repeat for key flows]

## Data Model

[Tables, entities, relationships - for software]
[Components, materials - for physical products]

## Technical Decisions

[Architecture choices, technologies, integrations]
[Explicitly document every load-bearing decision (storage, async patterns, concurrency, etc.) and note that it was discussed and approved during the interview]
[For non-technical users, describe these in plain language; for physical products, skip]

## Edge Cases & Error Handling

- When X happens, the system should Y
- If Z fails, show error message: "..."

## Open Questions

[Anything that still needs resolution before building]

## Future Considerations

[Ideas mentioned but explicitly deferred]

重要な原則

1. 設計の根幹に関わる判断を最優先する - 後から変更しやすい詳細に時間をかける前に、覆すのが難しいアーキテクチャ上の判断を特定し、解決してください。インタビューの主な目的は、これらを明らかにし、明示的な承認を得ることです。
2. 徹底する - 多くの質問をしてください。複雑な製品では、10〜20回に分けて質問するのが一般的です。
3. 決して決めつけない - 2通りの解釈が可能な場合は、どちらなのか尋ねてください。
4. 選択肢を提示する - すべての質問に、推奨案を含む妥当な選択肢を用意してください。
5. 質問の深さを調整する - 技術に詳しいユーザーには技術的な質問をし、技術に詳しくないユーザーには平易な言葉で尋ねてください。ただし、技術に詳しくないユーザーにも、設計の根幹に関わる判断は承認してもらう必要があります。わかりやすく説明してください。
6. 不明点を明らかにする - ユーザーがまだ検討していないと思われる点についても尋ねてください。
7. 具体性を保つ - 最終仕様書に曖昧な要件が一切残らないようにしてください。

自分への確認事項

仕様書を完成させる前に、次の点を自問してください。

• 「まだ明らかにしていない、設計の根幹に関わる判断は何か？ この仕様書に、実装後の変更が困難な項目があり、ユーザーに明示的な確認を取っていないものはないか？」
• 「考慮できていないエッジケースは何か？」