はじめに
AIによって実装が速くなっていますが、そもそもの要件が決まらなければ実装できません。実装が速いことの価値は、上流が整っていてはじめて発揮されます。要件定義フェーズをスムーズに進めるにはどうすれば良いのかを考えました。
前提
- フェーズ: 0→1開発
- ツール: Claude Code
プロセスの全体像
何が決まっていて何が決まっていないのかが曖昧で、要件定義が必要以上に時間がかかってしまうことがありました。そこで、何に時間がかかっているのか、何を合意すべきかを整理してみたら、概念整理 → 合意形成 → 仕様生成の3段階に分かれると考えました。
| ステップ | Input | Output |
|---|---|---|
| 概念整理 | ドメイン知識、既存仕様 | 定義・責務・範囲・方針 |
| 合意形成 | 概念整理の出力 | 承認済みの概念 |
| 仕様生成 | 承認済みの概念 + テンプレート | 6セクションの仕様書ドラフト |
私が参画しているプロジェクトでは、概念整理はPdMまたはエンジニアが、仕様生成はClaude Codeのスキルを使って行っています。後述します
概念整理の出力は幹、仕様生成の出力は枝葉の考えで整理しました
| 幹（概念整理） | 枝葉（仕様生成） | |
|---|---|---|
| 性質 | 思想・判断基準 | 具体的な仕様 |
| 変化頻度 | フェーズが変わっても変わらない | フェーズや優先度で更新される |
| 作り込みの姿勢 | 丁寧に作り込む | 変わる前提で割り切る |
| 例 | 定義・責務・範囲・基本方針 | 画面仕様・状態遷移・受入条件 |
システム設計における妥協案の作り方: 理想像の STEP1 として妥協案を設計する にある通り、
YAGNI が戒めるのは「不要な先行実装」であって「理想を考えること」ではありません。ほんの少しコストをかけて発展性を考えることで、将来の変更を非常に容易にすることができます。理想への道筋がわかりやすくなるようにガイドを用意しておくことは、不要な先行実装というより今後の開発のためのメッセージと捉えることもできます。
では、この API を妥協しながら作るとしたらどのように考えるべきでしょうか？ やってほしいことは、ある程度理想的な最終形を描いてその STEP1 となるように妥協案を実装することです。
概念整理は「理想を考えること」です。理想を定義した上で、今本当に必要なものだけを仕様に落とし込み仕様を作成します
概念整理
何をするか
概念整理は、「何を作るか」ではなく「この機能は何者か」を定義します。
ペルソナ・ジャーニー・サービス利用フロー・用語集（プロジェクト内で定義したドメイン用語の一覧）や、他機能の概念整理を読み込み、以下の7項目を構造化して出力します。
| 項目 | 内容 |
|---|---|
| 定義 | 1-2文でこの機能が何かを言い切る |
| 責務 | この機能が責任を持つ範囲（複数ある場合は列挙） |
| アプリ全体での位置づけ | 他の機能との関係 |
| 範囲 | やること / やらないこと |
| 基本方針 | 設計上の判断基準 |
| データモデル方針 | エンティティの関係 |
| 命名 | 用語の定義 |
概念整理で止める
概念整理は画面の詳細には踏み込みません。「ボタンの位置」「フォームの項目」は書きません。それは仕様生成の責務です。概念整理が定義するのは「この機能がどういう存在か」であって「この機能がどう見えるか」ではありません。
仕様生成
何をするか
概念整理の出力を受けて、6セクション構成の仕様書ドラフトを生成します。
仕様書の構成は、参考記事とレビューで繰り返しあった指摘から決めました。
- ユースケースを整理してから仕様を書く → ビジネス要件・ユーザーストーリーを前半に
- 操作ではなく状態から考える → 状態・分岐を後半に配置
- やらないことを明記する → ビジネス要件に「対象外」を必須化
- ハッピーパス以外を網羅する → 状態・分岐セクションの設置
この構成には「仕様だけ書く」を防ぐ意図もあります。仕様だけが書かれていると、書いた本人以外が背景を理解できず、レビューや議論に参加しにくくなります。ビジネス要件 = 要求、ユーザーストーリー = 要件、UI仕様 = 仕様という階層を強制し、「なぜ作るか」を飛ばして「どう操作するか」だけを書くことを防ぎます。
また、UIの具体（どう操作するか）は要件定義の責任範囲外とし、Figmaに委譲しています
| セクション | 問い |
|---|---|
| ビジネス要件 | なぜ作るか |
| ユーザーストーリー | 誰が何をするか |
| 受入条件 | 何を達成すれば完了か |
| 状態・分岐 | どんな状態がありうるか |
| データ要件 | 何を入出力するか |
| 代替運用 | 作らない機能をどうするか |
「操作」ではなく「状態」から考える
画面操作から要件を考え始めると、「ボタンを押したら保存する」のようなハッピーパスしか書けません。エラー時、0件、権限不足、途中離脱 --- こういった状態が抜け落ちます。
そこで仕様書では、「どういう状態になったら完了か」を先に定義し、その状態に至る操作を後から設計する順序にしました。
状態: 時間とともに変化しうるもの。性質: 対象に紐づく不変なもの。この2つが条件に同居していたら、立ち止まるべきサイン。
操作より状態・性質に着目する / 状態と性質を区別して考える
仕様書の「状態・分岐」セクションでは、状態だけを列挙し、性質は条件として分離しています。
セクションのポイント
ビジネス要件
大切なのは対象外の明記です。「やらないこと」とその理由を書くことで、スコープクリープを要件段階で防ぎます。要望を掘り下げると、既存機能で代替できたり、大規模な修正が不要だと気づくことがあります。速く作ることよりも、不要な作業を未然に防ぐことの方が全体の生産性に効きます。実際に、「この機能ではやらない。理由はこうだ」と書いてあることで、「ついでにこれも」に対して根拠を持って対応できます
例えば、参画しているプロジェクトではアンケート（最大10分、3セクション構成）の一時保存を作らないと決めました。便利そうに見えますが、半端な状態が生まれると通知体験が破綻します。また、そもそも10分の入力を途中でやめるかはデータを見ないとわかりません。理想は一時保存が必要な可能性がありますが、まずは作らない前提で運用してみて、必要なら作る方針にしました。
ユーザーストーリー
時系列での行動の流れ。「〜として〜したい」ではなく、具体的な行動シーケンスとして書きます。時系列で追うことで状態遷移が自然に見えてきます。
状態・分岐
正常系以外の全状態を網羅します。トリガーと条件は具体的に書きます。「エラー発生時」ではなく「APIが500を返したとき、画面にリトライボタンを表示し、3回失敗でエラーメッセージを表示する」です。
データ要件
この機能を達成するために必要な入出力を全て定義します。ただし、型定義や正規化は実装側の責任範囲なので詳細には踏み込みません
代替運用
作らない機能の運用回避策。「この機能はβ版では手動運用で代替する」を明記することで、作らない判断に根拠を持たせます。
最後に
ここまで書いた概念整理と仕様生成をClaude Codeのスキルとして定義し、運用しています。
プロダクトや企業の情報は伏せています。
concept-design（概念整理スキル）
---
name: concept-design
description: 機能の概念整理を行う。遷移シナリオとペルソナを起点に、機能の思想・責務・範囲・設計判断を整理する。Architect Agent が起草し、Devil's Advocate Agent がレビューする2段階構成。
---
# Concept Design Skill
機能の概念整理を起草し、複数の視点からレビューする。概念整理は要件定義（product-spec）の前提となるドキュメント。
## 使い方
/concept-design <機能名>
引数なしの場合はユーザーに対象機能を確認する。
## ワークフロー
### Step 1: コンテキスト収集
ユーザーに以下を確認する:
1. 何の機能か --- 機能名と簡単な背景
2. 遷移シナリオはあるか --- この機能にユーザーがどんな動機でアクセスするかの一覧（必須）
3. 既存の下書きはあるか
4. 関連する資料はあるか --- エビデンス、外部資料、機能固有の資料など
5. 出力先
遷移シナリオが未作成の場合は、先にシナリオの整理を提案する。
リソースの取得:
- ペルソナ・ジャーニー
- ドメインモデル（用語集）
- 関連機能の概念整理（ある場合）
- 既存の下書き（ある場合）
### Step 2: Architect Agent（設計者）
Agent ツールで専用の subagent を起動する。
役割:
- テンプレートの各セクションを漏れなく埋める
- 遷移シナリオから責務・思想・範囲を導出する
- ペルソナの特性を設計判断の根拠に組み込む
- ドメインモデルとの整合性を確認し、既存の用語を正しく使う
- 設計判断には必ず「なぜそうするか」の根拠を添える
- 設計判断に拘束度を付記し、後工程での判断余地を明示する（必須 / 推奨 / 許容）
テンプレート:
1. 一文定義 --- この機能を一文で定義する
2. 責務 --- この機能がサービスの中で果たすべき役割
3. 体験設計の思想 --- すべての設計判断の基盤となる原則（テーブル形式）
4. 位置づけ --- サービス全体の中での位置づけ
5. 範囲 --- 含むものと含まないもの
6. 設計判断 --- この機能固有の設計判断を根拠とともに記述
制約:
- 思想に焦点を当てる。情報設計は要件定義側の責務
- 読者はエンジニア以外も含む。技術用語を避け、ビジネス用語で記述する
- 設計判断は根拠とセットで記述する。根拠のない判断は書かない
### Step 3: Devil's Advocate Agent（反対意見）
Architect の出力を受け取り、別の Agent を起動する。
レビューチェックリスト:
- 思想の一貫性 --- 設計判断が体験設計の思想から導かれているか
- 責務の明確性 --- 他機能との重複がないか
- 範囲の妥当性 --- 境界が曖昧な項目がないか
- 設計判断の根拠 --- 代替案が検討されているか
- 明確性 --- 結論先行で書かれているか
- ユーザー視点 --- ペルソナの特性が考慮されているか
### Step 4: 統合 & ユーザー確認
ドラフトと指摘を並べて、人間が取捨選択する。
### Step 5: ドメインモデル更新
新しい用語がある場合のみ実行する。
### Step 6: 最終出力
承認された概念整理を出力先に書き出す。
## product-spec との関係
concept-design の出力は product-spec の入力となる。
- 概念整理の「体験設計の思想」→ 要件定義の「体験設計の意図」の基盤
- 概念整理の「設計判断」→ 要件定義の「対象外」で「概念整理で確定済み」と参照
- 概念整理の「範囲」→ 要件定義のスコープの基盤
product-spec（仕様生成スキル）
---
name: product-spec
description: 要件定義をテンプレートに沿って起草する。Architect Agent（設計者）が起草し、Devil's Advocate Agent（反対意見）がレビューする2段階のAgent構成で、見落としや矛盾を防ぐ。
---
# Requirements Definition Skill
テンプレートに沿って要件定義を起草し、複数の視点からレビューする。
## 使い方
/product-spec <機能名>
引数なしの場合はユーザーに対象機能を確認する。
## ワークフロー
### Step 1: コンテキスト収集
ユーザーに以下を確認する:
1. 何の機能か --- 機能名と簡単な背景
2. 既存の下書きはあるか
3. ペルソナ・ジャーニーを参照するか
4. 出力先
リソースの取得:
- 仕様書テンプレート
- ドメインモデル（用語集）
- ペルソナ・ジャーニー（参照する場合）
- 既存の下書き（ある場合）
### Step 2: Architect Agent（設計者）
役割:
- テンプレートの各セクションを漏れなく埋める
- ドメインモデルとの整合性を確認し、既存の用語を正しく使う
- 状態遷移・データ要件・エッジケースを設計する
- Why（ユーザーの課題）を先に記述してから What（解決策）に進める
制約:
- テンプレートにないセクションを追加しない
- 概念整理で確定済みの設計判断の根拠は繰り返さない。「概念整理で確定済み」と参照するのみ
- 読者はエンジニア以外も含む。技術用語を避け、ビジネス用語で記述する
- 実装の詳細（API設計やDB設計）には踏み込まない
### Step 3: Devil's Advocate Agent（反対意見）
レビューチェックリスト:
- 構造・完全性 --- 全状態の列挙、状態遷移の条件定義、事前・事後条件
- 明確性 --- 曖昧表現の排除（「適切に」「必要に応じて」禁止）、検証可能な形式
- スコープ --- 「やらないこと」の理由、保留事項の担当と期限
- 矛盾検出 --- 要件間の矛盾、データ要件と機能要件の整合
- ユーザー体験 --- 自然な時系列、エラー時のリカバリ設計
### Step 4: 統合 & ユーザー確認
ドラフトと指摘を並べて、人間が取捨選択する。
### Step 5: ドメインモデル更新
新しい用語がある場合のみ実行する。
### Step 6: 最終出力
承認された要件定義を出力先に書き出す。
参考
Discussion