Socratic Requirements Builder

Socratic Requirements Builder

ソクラテス式の質問で曖昧な要件を段階的に明確化し、合意済み要件サマリを docs/requirements/<feature>.md として出力する。

このプロジェクトはエンジニアギルドハッカソン 2026/05 team-07「偏愛キャラクター育成アプリ」。技術スタックは React 19 + Vite + TypeScript + TailwindCSS v4（`app/`）+ Firebase Cloud Functions（`app/functions/`）+ Firestore + Firebase Auth。npm 管理。短期間（〜5日）の開発のため、要件確定もスピード優先で進める。

いつ起動するか

実装系のリクエストで以下のいずれかに該当したら 自動起動 する：

• 機能リクエストが一文〜数文で短く、スコープ・成功条件・優先度が不明確
• 「〜を実装して」「〜が欲しい」「〜を直して」「〜できるようにして」
• 「ここバグってる気がする」「いい感じにして」など主観的な表現
• 設計判断の分岐が複数あって「どう作るか」が一意に決まらない

起動しないケース:

• 既に詳細な要件・受け入れ条件が示されている（docs/issues/<id>.md の Issue ファイル、API スキーマ、UI モックなど）
• 単純なリファクタ、フォーマット修正、タイポ修正など意図が自明
• ユーザーが「Socratic 不要、すぐ実装して」と明示

起動したらまずやること

Step 1: プロジェクト文脈の事前読み込み

質問する前に、既に分かっていることを把握する：

1. リポジトリルートの AGENTS.md（Firestore データモデル・セキュリティ規約が書かれている） 2. README.md（プロダクト概要・技術スタック欄） 3. `docs/issues/`配下に対応する Issue ファイルが既にあるか確認する（重要）

• docs/issues/README.md でカテゴリ別Issue一覧をまず見る
• 例: 「卵生成を実装したい」→ docs/issues/char-04-egg-generation.md が該当

4. docs/rules/git-conventions.md（ブランチ・コミット規約） 5. 既に docs/requirements/ に類似機能のサマリがあれば読む 6. 関連コードを軽くサーチ（app/src/ または app/functions/src/）

Issue ファイルが既に詳細な場合の扱い（最重要）:

docs/issues/<id>-<slug>.md に該当 Issue があり、What / Why / Done / Scope が読み取れるレベルで書かれている場合、それを 要件サマリ相当として扱い、Socratic 質問は最小限にする。重複した docs/requirements/<同名>.md を作らない。不足項目だけピンポイントで確認すれば良い。

なぜか: このPJでは docs/issues/ が Issue + 要件仕様を兼ねている。既知情報を質問するとユーザーの信頼を失う。事前読み込みで「既知 vs 未知」を分けてから質問する。

Step 2: 要件把握度の判定基準

以下6軸のうち、必須4項目（What / Why / Done / Scope）が埋まった時点で要件把握完了 とみなし、要件サマリ作成へ進む。 残り2項目（Constraints / Priority）は未確定でも構わない（未確定事項に回す）。

ハッカソン期間中は完璧を目指さず、Day1/Day2/Day3 のマイルストーン感覚で粒度感を合わせる。残りは未確定事項として扱えばよい。

質問の出し方

ルール

• 一度に投げるのは 1〜2問まで。 質問を浴びせない。
• 質問の往復は最大 3 ターンまで。 それを超えそうなら、その時点の情報＋推測でドラフトを作成し、ユーザーに修正を委ねる方が UX が良い。
• 質問は日本語で。プロジェクト全体が日本語ベース。

質問の優先順位

1. Why（なぜ）: 「この機能で誰のどんな課題を解決したいか」 2. Done（成功条件）: 「どう動けば成功か」「どうなったら失敗か」 3. Scope（境界）: 「含む／含まない」「ハッカソンMVPで何を諦めるか」 4. What の詳細: Why と Done が決まれば What も具体化される 5. （余裕があれば）Constraints / Edge cases / 代替案

質問テンプレ例（このPJ向け）

• 「この機能のユーザーは誰で、今は何をして困っていますか？」
• 「ハッカソンのMVPとして最低限これだけ動けば OK、というラインを教えてください」
• 「フロント完結（React state）／Firestore に永続化／Cloud Functions 経由、の3通りが考えられそうです。どれが要件に合いそうですか？」
• 「Firestore のどのコレクション（users / passions / eggs / characters / exchanges / chats）に保存しますか？」
• 「○○の場合はどう振る舞うべきですか？（例: 未ログイン状態でアクセスされたとき）」

質問しながら必須4項目の充足を更新し、同じ軸を何度も聞かない。

必須4項目が埋まったら：要件サマリを出力

保存場所

docs/requirements/<feature-name>.md

ファイル名は AI 側から提案する。 ユーザーに考えさせない。

要件内容から適切な kebab-case 名を推測し、こう確認する：

「今回は docs/requirements/egg-generation-tweak.md というファイル名で作成してよいですか？」

命名例（このPJのドメイン語彙）:

• passion-registration-form.md（偏愛登録フォーム）
• egg-hatch-animation.md（卵の孵化アニメーション）
• qr-exchange-flow.md（QR交換フロー）
• character-chat-streaming.md（キャラチャットのストリーミング）
• firestore-security-tightening.md（Firestoreルール強化）

`docs/issues/` の Issue 名と被るときの方針:

• Issue ファイルがあるなら基本それを参照する形にし、docs/requirements/ の重複作成はしない
• Issue では足りない補足（設計判断・代替案の比較など）だけを別途 docs/requirements/<issue-id>-followup.md のように分けて書く

ディレクトリが無ければ作成する（mkdir -p docs/requirements）。既存ファイルがあれば、上書きせずに「追記しますか／別ファイルにしますか」を確認。

フォーマット（厳守）

# <機能名>

最終更新: <YYYY-MM-DD>
ステータス: 要件確定 / 設計中 / 実装中 / 完了
対応Issue: <docs/issues/xxx.md があれば相対パスでリンク。なければ「なし」>

## 目的（Why）
<誰のどんな課題を解決するか。1〜3行で簡潔に>

## スコープ
### 含むもの
- ...

### 含まないもの（明示的に対象外）
- ...

## 成功条件（Definition of Done）
- [ ] ...
- [ ] ...

## 制約
- 技術: <例: React 19 + Vite / Firebase v12 / TailwindCSS v4 / Cloud Functions Node22>
- データ: <例: Firestore `passions` コレクションに保存。`AGENTS.md`のスキーマに準拠>
- セキュリティ: <例: `firestore.rules` で ownerUid==auth.uid のみ書き込み許可>
- 期限: <ハッカソンのDay○マイルストーン>
- その他（規約・コンプライアンス等）: ...

## 主な振る舞い
- 正常系: ...
- 異常系: <例: Firebase Auth 未ログイン時／Firestore書き込み失敗時>
- 境界条件: ...

## 未確定事項
<把握できなかった項目。将来検討 or 実装中に決定する>
- [ ] ...

## 関連
- 仕様書: <パス or URL>
- 関連コード: <例: app/src/firebase/firebase.ts, app/functions/src/index.ts>
- 関連 issue/PR: ...

出力後の手順

要件サマリ.md を作成したら、ユーザーに：

1. ファイルパスを伝える 2. 「この内容で合っていますか？修正点があれば指摘してください」と合意を取る 3. ユーザーが OK したら、次のステップ（設計 or 実装＝incremental-implementation スキル）に進む

ユーザーが質問を遮ったとき / 3ターン上限に達したとき

ユーザーが「もういいから実装して」「細かいことはいい」と明示的に打ち切ったとき、または質問が 3 ターンを超えそうなとき：

• その時点の情報＋合理的な推測で要件サマリのドラフトを作成（必須4項目が未充足でも可）
• 未確定事項 セクションに残った疑問と「自分が置いた仮定」を全部明記
• 「以下は仮定として進めます。違っていたら指摘してください」と前置きしてユーザーに修正を委ねる

ユーザーの時間を尊重する。Socratic は手段であって目的ではない。ハッカソンは特に時間が貴重。

アンチパターン

• ❌ 一度に 5 問以上ぶつける（圧迫感を与える）
• ❌ 質問の往復が 3 ターンを超える（ユーザーが疲弊する）
• ❌ AGENTS.md・README.md・docs/issues/ に書いてあることを質問する
• ❌ docs/issues/<id>.md で既に詳細な要件が定義されているのに、重複した docs/requirements/<同名>.md を作る
• ❌ Yes/No だけで答えられない抽象的すぎる質問
• ❌ ユーザーが既に答えた内容を別の言い方で再質問
• ❌ ファイル名を「どうしますか？」とオープンに聞く（提案型で確認する）
• ❌ 必須4項目が未充足なのに勝手に実装に進む
• ❌ 必須4項目が埋まっているのに永遠に質問を続ける
• ❌ 既存の要件サマリを確認せず重複ファイルを作る
• ❌ Firestore コレクション名や型を AGENTS.md で確認せず勝手に決める