define-requirements

name	define-requirements
description	新規・変更・削除・改善などの要望やレビュー指摘を受けたら、設計や実装に入る前にまず必ず発火させる「要件定義フェーズ」のスキル。依頼者のインテントを読み取り、Why / Done / スコープ / 影響範囲を引き出す。見える挙動が変わる依頼全般が対象で、やることが具体的でも md にまとめられていても発火させ、複数の要望が混ざる依頼ほど積極的に発火させる。発火しないのは、再現条件と期待動作が完全に明確なバグ修正、依存更新・タイポ修正などの定型作業、要件定義と基本設計の文書が両方揃った実装フェーズの続き（メモや TODO があるだけでは除外しない）だけ。

要件定義フェーズ

なぜこの skill があるか

実装に入る前に「何を、誰のために、なぜ作るか」を固めないと、エンドユーザーに価値が届かない設計が通る。依頼者は依頼者であってエンドユーザーではない。プロのエンジニアとして、依頼者の言葉の裏にある真の課題を引き出すのがこのフェーズの責務。

依頼者のインテント（真の意図）を読み取る

依頼者の発言の表面（「○○を作って」「○○を消して」「○○を確認して」）の裏にあるインテントを読み取る。なぜそれが必要か、誰のためか、何が真の課題か。表面的な依頼に縛られず、Why から最善の一手を考える。

依頼が md ファイル（review / TODO / 改善要望リスト）にまとまっていても同じ。md に書かれているのは「依頼者の表面的な要望」であって、その裏のインテントを読み取り対話で引き出す。「やることが具体的だから skip」と判断しない — 具体的な解決策の裏に真の課題があり、別の解決策の方が良いかもしれない。

モードを合意してから帰結ある行動に入る ★最初に通す

発火したら、いきなり Why 掘りや下の 5 セクションの要件定義に入らない。まず「今どのモードにいるか」を意識する。モードは 3 つ:

• モード未確定: 依頼を受けた直後 / 調査中。まだどちらのモードか決まっていない
• 対話モード: 決めに行かず、確認しながら認識を揃える（このスキルの通常フロー）
• 自走モード: ゴールが明確で「任せる」とき。決めて進め、終わってから共有する

守りたいのは「合意なしで帰結ある行動に滑り込むこと」の一点

ゲートは 1 つだけ。設計・実装・変更という帰結ある行動（＝やり直しにコストがかかる動き）に入る手前で、どのモードで進めるかを依頼者と合意する。これ以外はゲートで止めない。特に次の非破壊な動きは、モード未確定でも止めない:

• 調査（読む・探る・理解を作る、戻せる動き）: そのまま進めてよい。調査は「どちらのモードでいくか」を決めるための情報集めだから。ただし調査が終わって帰結ある行動に入る手前で、必ずモード合意に戻る（調査は実装への抜け道ではない）
• 議論・要件対話（依頼者と認識を揃える動き）: 依頼者がいきなり議論を始めたら、それは既に対話モードそのもの。止める対象ではない（むしろ望ましい）。その場で dialogue-principles skill を呼んでから議論に応じる

モード合意 ← ここがゲート

帰結ある行動に入る手前で、AskUserQuestion で「対話モードで深掘る / 自走モードで進める」を出し、自分の見立てを推奨に置く。勝手にどちらかのモードに入らない（重いから一人でゴールを決めて設計・実装まで進める、調査したからそのまま実装に直行する、はどちらも「合意なしで帰結ある行動に滑り込む」）。止めたいのは 自分が勝手に帰結ある行動へ突入すること であって、深掘り（Why 掘り）や調査そのものではない — それらはむしろ進めてよい（重いタスクほど深掘る価値がある）。見立ての目安:

• 対話モードを推奨: 依頼が特定の手段・解決策を指していて、その裏の Why 次第では別のやり方の方が良いかもしれないとき。「○○を表示して」「○○を追加して」のような解決策の指定は、それ自体が深掘る理由になりうる（手段が明確なだけで、真の課題への最善とは限らない — 下の代案提案の例を参照）
• 自走モードを推奨: 純粋作業（タブ削除・typo 的な文言修正・整形）／ゴールが明確で手段はお任せ（「任せる」「やり方は問わない」）／掘っても手段が変わらなそう、のとき

見立ては当てにいくものではなく外すことがある（機械的に見分けるのは難しい）。だから独断で決めず、見立てを述べて依頼者に確認する — この確認が見立てのブレを受け止める安全網。依頼者は自分の意図（探ってほしいのか、任せて進めてほしいのか）を分かっているので選べる。迷ったら対話モード側を推奨に置く（「簡単そうで難しい／指定された手段が最善でない」を取りこぼさないため）。

モードが決まったら

• 自走モードで合意 → 「何をするか」「どうなったら完了か」の最小限だけ口頭で揃え、basic-design skill を挟まず slice-tdd skill での実装にそのまま渡す（最小合意を口頭で持って渡す）。要件定義.md は作らない。この時点で終わり — 下の「やること」以降のセクションは実行しない
• 対話モードで合意 → dialogue-principles skill を呼んでから、下の通常フローに進む（Why を掘り要件を固める）。対話モードで進めると決めた時点が、対話の規律を効かせ始める地点

モード合意は一度きりではなく 再来しうる。例えば調査を挟んで前提が変わったり、進める中で「ここは一度立ち止まって対話したい」となれば、その時点でモードを合意し直す。固定ではなく、その時々で合意し直せる。

やること（＝対話モードで進めると決めた場合の通常フロー）

1. ユーザーストーリーを引き出す

「誰が・何のために・何をしたいのか」を 1 文で書ける状態にする。形式は問わないが、最低限この 3 要素が揃うまで質問する:

• 誰が: エンドユーザーの role（運用担当？管理者？顧客？）
• 何のために: その人が達成したい目的・上位の Why
• 何をしたいのか: 具体的な行動・操作

例: 「運用管理者が、不正注文を早期に発見するために、注文レビュー画面で要確認の注文をまとめて見たい」

2. Why を掘る

「なぜその機能が必要か」を 2-3 段階掘る。表面的な依頼の裏にある本当の課題を引き出す。

例:

• 依頼者: 「注文のレビュー画面が欲しい」
• アシスタント: 「なぜレビュー画面が必要ですか？」
• 依頼者: 「不正注文を早く見つけたい」
• アシスタント: 「不正注文を早く見つけたい背景は？今は何が問題ですか？」
• 依頼者: 「月末締めの請求処理で大量の差し戻しが発生して、経理担当が残業してる」

→ ここまで掘ると、本当の課題が「月末の差し戻し負荷」だと分かる。レビュー画面が解決策の一つだが、他の解決策（自動承認の閾値調整、当日中の通知）もありえる。Why を掘らずに作ると、依頼者が思いついた表面的な解決策に縛られる。

3. Done（完了基準）を引き出す

「どうなったら完成と言えるか」を観測可能な形で書く。

• ✗ 「使いやすい注文レビュー画面ができている」（観測不能）
• ✓ 「運用管理者が要確認の注文一覧を 3 クリック以内で開けて、各注文に承認/差し戻しボタンが出ている」（観測可能）

E2E テストで検証可能なレベルにする。後で slice-tdd skill が E2E spec を書くとき、この Done を直接スペック文に変換できる粒度を目指す。

4. スコープ外を明示する

「今回はやらない」を明示することで、設計と実装の発散を防ぐ。例:

• 今回スコープ: 運用管理者の注文レビュー画面、要確認の一覧 + 承認/差し戻し
• スコープ外: 監査ログの可視化、CSV 出力、商品横断のサマリ

5. 制約（守るべき条件）を洗い出す

Done（達成したいこと）・スコープ外（今回やらないこと）に加えて、守るべき制約を洗い出す。制約は「絶対に踏み外せない条件」で、スコープ外とは性格が違う（スコープ外＝交渉可能な除外、制約＝非交渉のルール）。制約は他の決定（Done の粒度、解決策の選び方）を縛るので、先に効く前提として早めに拾う。この手順 5 という番号は文書上の並びであって洗い出す順番ではない — Why を掘る中で制約が見えたら、その場で拾って確認してよい（テンプレートの「5. 制約」セクションも文書レイアウト上の位置にすぎない）。

制約は技術に閉じない。次のような広い範囲から、該当するものだけ拾う（全項目を機械的に聞かない）:

• 技術: 採用フレームワーク・ランタイムの制限、既存仕様との互換、依存ライブラリ
• 非機能: 性能（応答時間・スループット）、可用性、運用負荷
• セキュリティ・コンプライアンス: 認証認可、個人情報、業界規制
• 資源・時間: コスト（API・infra 料金、人件費）、期限・納期（ローンチ日、業務上の締め）、投入できるリソース（人員、開発期間、権限）
• 組織・社内ルール: コーディング規約、承認フロー、使えるツール / SaaS の制限

引き出し方は制約の種類で変える:

• 技術制約は毎回棚卸ししない。要件・Done の実現可能性が論点になったときだけ扱う（毎回「このフレームワークだからこうなる」を持ち出さない）。扱うときは憶測やフレームワーク一般論でなく、コード・既存仕様を調べて具体を確認する
• コスト・期限・組織ルール・リソースは調べても分からないので、関係しそうなら依頼者に聞く

6. Why と解決策がズレてたら代案を提案する

依頼者が示す解決策（「○○の機能を作って」）と、Why を掘って出てきた真の課題が整合していないと感じたら、代案を提案する。一人前の開発者として「依頼通りに作る」だけが仕事ではない。Why から最善の一手を考えて、依頼者の指定した解決策が最適でないなら別案を出す。

例:

• 依頼: 「ユーザー詳細画面に USER ID を表示したい」
• Why（聞いてみる）: 「注文一覧で『この注文は誰のか』が分からなくて辛い」
• 提案: 「USER ID を詳細画面に出すのも一つですが、真の課題が顧客特定なら、注文一覧に顧客名を直接表示する方が運用は楽そうです。両案で検討しませんか？」
• 依頼者が「いや USER ID 表示で十分」と判断したらそれに従う

押し付けではなく選択肢として提示する。Why と整合してれば代案は不要、整合してない時だけ提案する。

代案を出すときは propose-options skill のフォーマット（複数案＋メリデメ＋推奨）に乗せる。

振る舞いのルール

依頼者に迎合しない（最重要）

エンドユーザー価値を守るために、依頼者の発言を無批判に受け入れない。

• 「いいですね」「賢明です」「素晴らしい」のような空虚な肯定をしない
• 矛盾点・リスク・コスト・スコープ膨張を必ず指摘する
• 過去の決定や既存仕様と矛盾していたら指摘する
• エンドユーザー視点で「これは本当にユーザーにとって価値があるのか」を問う

即同意も迎合の一種

依頼者の指摘や反論に「あ、確かに、そうですね」と即引き下がるのは迎合の一種。同意する前に:

1. 自分の以前の判断との整合性を再評価する
2. 指摘内容に潜むリスクを洗い出す
3. 依頼者の指摘が正しいか、根拠を比較する

賛成するなら自分の根拠を述べ、反対するなら根拠を示す。本当に依頼者の指摘が正しければ修正する。両立するなら追加質問する。

対話の型 (proactive な認識合わせ)

要件定義は対話駆動。インテント・Why・Done を引き出すには、以下を厳守する。

1 問ずつ質問する

深い議論は 1 つずつ。複数を 1 メッセージに混ぜると依頼者が回答しづらい。軽い確認 (Yes/No 程度) なら複数 OK。

multiple choice を優先する

質問はクローズな選択肢で出すのを基本に。依頼者の負担が小さい。「3 案あります、どれが近いですか?」のような形。AskUserQuestion ツールが使える場面では使う。

段階的な認識合わせを proactive に出す

議論の節目で「ここまでの理解はこうです、合ってますか?」を 依頼者が確認サインを出す前に こちら側から出す。節目の例:

• Why が掘れた直後
• ユーザーストーリーが書けた直後
• Done が固まった直後
• スコープ外が決まった直後
• 制約が洗い出せた直後

「サマリ → 確認」を pattern 化する。依頼者が違和感を感じたタイミングで戻れる。

セクション単位の approval gate

要件定義 md は 5 セクション (背景と動機 / ユーザーストーリー / Done / スコープ外 / 制約)。各セクションを埋め終わるごとに「このセクションで合っているか」を明示的に確認してから次へ。一気に全部書いてからレビューを求めない。

不明点を推測で埋めない

「たぶんこういう意図だろう」で進めない。不明点が出たらその場で質問。依頼者の沈黙を「OK」と解釈しない。

依頼者が確認サインを出したら必ず確認する (reactive ルール)

proactive な対話の型に加えて、依頼者が以下のサインを出した時は必ず「私の理解はこうです、合ってますか」と確認する:

• 「伝わってる？」「分かるかな？」と確認を求めている
• 「悪くないけど…」「大丈夫そう？」と微妙な同意ニュアンス
• 「もう少し議論したい」「気になる点がある」
• 雑な OK サイン（「いいよ」「OK」だけで具体的な合意点に触れていない）

認識合わせの形式: 「私の理解は次のとおりです: [箇条書きでサマリ]。合ってますか？ずれている点はありますか？」

複数アプローチがありそうなら propose-options を呼ぶ

要件の解釈や Done の定義に複数案がありえると感じたら、必ず propose-options skill を呼んで「複数案＋メリデメ＋推奨」のフォーマットで整理する。一案だけポンと出すのは禁止。

例:

• 「注文レビュー画面の動線」が 2 通りありえる → propose-options
• 「要確認の判定ロジック」が複数案ある → propose-options

このフェーズで「設計」「実装」の話に踏み込まない

要件が固まる前に「じゃあ画面はこういう構造で...」「DB に column 追加して...」と踏み込まない。それらは basic-design skill / slice-tdd skill の仕事。

ただし、制約（技術に限らず、コスト・期限・組織ルール等）は要件に影響するので、上の「制約（守るべき条件）を洗い出す」の通り引き出して要件に反映する。これは設計・実装の詳細に踏み込むこととは別（守るべき前提の確認であって、どう作るかの決定ではない）。

成果物

要件が固まったら docs/working/<title>/要件定義.md を新規作成する。<title> は機能を表すケバブケース（日本語可）。例:

• docs/working/注文レビュー画面/要件定義.md
• docs/working/顧客単位サマリ/要件定義.md

ディレクトリ構成（基本設計フェーズで 基本設計.md が同ディレクトリに追加される）:

docs/working/<title>/
├── 要件定義.md  ← この skill が作る
└── 基本設計.md  ← basic-design skill が作る

要件定義.md の構成:

# <機能名> — 要件定義

> このドキュメントは進行中の設計メモ。実装後もそのまま残す（振り返り・PR レビューで参照される）。
> 削除のタイミング・要否は依頼者または外側の仕組みで別途判断する（あなたは削除しない）。

## 1. 背景と動機
[Why の掘り下げ結果]

## 2. ユーザーストーリー
- [誰が] が [何のために] [何をしたい]

## 3. Done（完了基準）
- [観測可能な完了条件 1]
- [観測可能な完了条件 2]
- ...

## 4. スコープ外
- [今回やらないこと 1]
- [今回やらないこと 2]
- ...

## 5. 制約（Constraints）
- [守るべき条件 1（種類: 技術 / 非機能 / セキュリティ / 資源・時間 / 組織）]
- [守るべき条件 2]
- ...
（該当する制約がなければ「特になし」と書く。空欄で飛ばさない — 後で再発見する事故を防ぐため）

ドキュメント執筆ルール

• 省略記号は使わない: 会話文脈に依存する「案 A」「案 D」「α」「β」のような略号は md に持ち込まない。skill 名・案名は具体名で書く
• Done に番号 (D1 / D2 等の識別子) を振らない: Done を md に書き起こすときに番号を振らない。Done は 内容で参照 する。理由: 依頼者は要件定義書を見ていない (= md は Claude 自身が context を再現するための文書)。対話の中で「D5 を満たす」のように番号で言及すると、依頼者は中身が伝わらず認知負荷が上がる。番号は識別子として便利だが、対話への波及で省略を促す根本原因になる
  • ✗ NG 例: - **D5**: skill-reviewer が違反パターンを検出する機能を持つ
  • ✓ OK 例: - **skill-reviewer が違反パターンを検出する機能を持つ** (= 内容で書く)
  • ✓ OK 例: 見出しで section 化して中身を書く (= ### skill-reviewer の機能 の下に内容を書く)
  • 内部参照も中身で書く: ✗ 「D3 を満たすには D1 が必要」 → ✓ 「『skill-reviewer の自動呼び出し』を満たすには『skill-reviewer の新規作成』が必要」
• 同じ md 内の内部参照（「上記」「セクション 3.x」「フロー図」など）は許容するが、編集時に参照先が削除/移動されてないかをレビューする。セクションを削除/移動した際は、そこを参照してる箇所を grep して全部更新する
• 自己完結性は handoff-docs を呼んで効かせる: 要件定義.md は別セッションのエージェントが会話文脈ゼロで読んで設計・実装に進む成果物。書くときは handoff-docs skill を呼んで、自己完結性の規律を効かせる。

書き起こしのタイミング

要件の議論が完全に固まってから書き起こす。途中段階で md にしない。理由: ドキュメントの構造が議論を縛り、未決論点の存在が見えにくくなる。

依頼者が明示的に「一旦見たい」「ドキュメントに起こして」と言った場合のみ、その時点までの合意で書く（暫定であることを冒頭に明記）。暗黙に「これで合意できたから書こう」と判断しない。

規模・複雑度を判断して pre-implementation-reviewer を提案する

要件定義が固まったタイミングで、規模や複雑度を判断して「第三者レビューを入れる価値あり」と感じたら、依頼者に pre-implementation-reviewer subagent を呼ぶことを提案する。自動では呼ばない（毎回呼ぶと Opus コストが嵩む）、提案に留める。

判断基準:

• 規模が大きい（複数 table 追加、複数画面追加、複数 user role に影響など）→ 提案する
• 影響範囲が広い（既存の重要な機能に影響、permission 変更、migration 必要）→ 提案する
• セキュリティ観点が含まれる（認証・認可・個人情報・secrets 扱い）→ 提案する
• 複雑な状態遷移や非自明な業務ロジックが含まれる → 提案する
• 軽微な変更（タブ削除、typo 的な文言修正、整形）→ 提案不要（「○○を表示・追加して」のように解決策が指定された変更は、真の課題がズレていれば軽微に数えない）

提案の形式:

要件が固まりました → docs/working/<title>/要件定義.md

この要件は <理由> なので、pre-implementation-reviewer の第三者レビューを入れる価値ありそうです。呼びますか？

依頼者が「呼んで」と言ったら、Task ツールで pre-implementation-reviewer subagent を起動する。レビュー結果は依頼者と一緒に議論する材料として扱う（main session が機械的に対応/非対応を決めない）。

引き継ぎ可能性を点検してから次フェーズへ渡す

要件定義.md は別セッションのエージェントが読んで設計・実装に進む成果物。次フェーズへ渡す前に、handoff-docs skill を呼んで引き継ぎ可能性を点検する（handoff-verifier で文脈ゼロ点検し、Yes になるまで穴を直す）。

pre-implementation-reviewer（妥当性）と handoff-docs 経由の点検（引き継ぎ可能性）が両方効く場面では、妥当性が先・引き継ぎ可能性が後。中身の妥当性がまだ固まっていないのに引き継ぎ可能性を点検しても、中身が変われば書き直しになるため。

次のフェーズへの誘導

要件が固まり md に書き起こしたら、次のフェーズ（基本設計）に進む案内を出す:

要件定義が固まりました → docs/working/<title>/要件定義.md

このセッションのコンテキストはもう使わないので、節約したい場合は:
1. /clear でこのセッションをリセット
2. 新しい入力で次のメッセージを送ってください:
   @docs/working/<title>/要件定義.md basic-design で設計を進めて

そのまま続けても問題ありません。

強制ではなく任意のガイド。設計 md があれば context 再現できるので、依頼者が選べばよい。