spec-gathering

要件収集スキル

概要

構造化された質問を通じてユーザーの要件を収集し、検証済みの要件ドキュメントを作成します。このスキルは、曖昧なタスクの説明を、実行可能で構造化された要件に変換します。

基本原則： 適切な質問をして、有効な構造化出力を作成します。それ以外は行いません。

使用するタイミング

必ず使用する場合：

• 新しい機能やプロジェクトを開始するとき
• 曖昧なタスクの説明を明確にするとき
• ユーザーが具体的な内容を示さずに大まかな目標を提示したとき
• 仕様書の作成を始める前

例外：

• 再現手順が明確な単純なバグ修正
• 範囲が明白な単一ファイルの変更
• ユーザーが完全な要件を明示している場合

絶対原則

NO SPEC WRITING WITHOUT VALIDATED REQUIREMENTS FIRST

仕様書の作成に進む前に、要件をユーザーに確認してもらう必要があります。

ワークフロー

フェーズ 1：プロジェクトのコンテキストを読み込む

ユーザーに確認する前に、プロジェクトの構成を理解します。

手順：

1. 存在する場合は、プロジェクト構成ファイルを読みます
2. サービス、技術スタック、ポートを特定します
3. 既存のパターンと規約を把握します

# Read project structure
cat .claude/context/product.md 2>/dev/null || echo "No product context"
cat .claude/context/tech-stack.md 2>/dev/null || echo "No tech stack"

フェーズ 2：タスクを理解する

タスクの説明が提示されている場合は、内容を確認します。

「ご希望の内容は次のとおりだと理解しました：[task description]。この理解で合っていますか？補足はありますか？」

タスクが提示されていない場合は、次のように尋ねます。

「どのようなものを構築または修正したいですか？必要な機能、バグ修正、変更について説明してください。」

ユーザーの返答を待ちます。

フェーズ 3：ワークフローの種類を判断する

タスクに基づいて、ワークフローの種類を判断します。

タスクの例	ワークフローの種類
「機能 X を追加」、「Y を構築」	feature
「X から Y に移行」、「Z をリファクタリング」	refactor
「X が発生するバグを修正」、「Y をデバッグ」	investigation
「X からデータを移行」	migration
単一サービスの小規模な変更	simple

確認を求めます。

「これは [workflow_type] タスクのようです。この認識で合っていますか？」

フェーズ 4：サービスと範囲を特定する

プロジェクトのコンテキストとタスクに基づいて、影響を受ける領域を提案します。

「タスクとプロジェクト構成から、次の領域が関係すると考えています。

• [service1]（主要）- [why]
• [service2]（統合）- [why]

ほかに関係するサービスや領域はありますか？」

確認または訂正を待ちます。

フェーズ 4.5：Context-Compressor を呼び出す（プログレッシブ・ディスクロージャー・モード／ECLAIR パターン）

手動で要件を収集する前に、Context-Compressor スキル（プログレッシブ・ディスクロージャー・モード）を使用して、確認プロセスを最適化します。

Skill({
  skill: 'context-compressor',
  context: {
    taskDescription: taskDescription,
    projectContext: projectContext,
    services: identifiedServices,
    mode: 'progressive-disclosure',
  },
});

Context-Compressor（プログレッシブ・ディスクロージャー・モード）が行うこと：

1. E：検討 - タスクの説明に含まれる曖昧さを分析します
2. C：分類 - CRITICAL、HIGH、MEDIUM、LOW の優先度で分類します
3. L：制限 - 確認質問の上限を 3～5 件に設定します
4. A：仮定 - プロジェクトのパターンから適切なデフォルトを適用します
5. I：推論 - 既存のコードパターンと技術スタックを活用します
6. R：記録 - すべての仮定を [ASSUMES: X] として記録します

返される内容：

• 優先順位付けされた確認質問（最大 5 件）
• [ASSUMES:] 表記のスマートデフォルト
• 更新された要件の理解

フェーズ 5：詳細な要件を収集する（Context-Compressor を使用）

Context-Compressor が特定した重要な確認質問のみを尋ねます。

上限： 確認質問は最大 3～5 件

手順：

1. 最初に CRITICAL 優先度の質問をします（セキュリティ、データ損失、破壊的変更）

   • 例：「システムにロールベースのアクセス制御が必要ですか？」
   • 例：「ユーザーはデータを削除できるようにする必要がありますか？削除は取り消し可能ですか？」

2. 上限に達していなければ、HIGH 優先度の質問をします（UX、アーキテクチャ、スケーラビリティ）

   • 例：「想定されるユーザー数はどれくらいですか？」
   • 例：「オフラインモードに対応する必要がありますか？」

3. MEDIUM／LOW 優先度の項目には、デフォルト値とともに [ASSUMES:] 表記を使用します

   • 例：「[ASSUMES: 有効期限 1 時間の JWT トークン]」
   • 例：「[ASSUMES: 既存の /api/v1/ パターンに従う REST API]」

回答を収集し、すべての仮定を記録します。

フェーズ 6：確認と出力（前提条件を含む）

明確化した要件と前提条件を含め、理解した内容を要約します。

「理解した内容を確認させてください。

タスク：[概要] 種類：[ワークフローの種類] 範囲：[影響を受ける領域の一覧]

明確化した要件（質問した内容）：

1. ✅ [質問] → [回答]
2. ✅ [質問] → [回答]
3. ✅ [質問] → [回答]

適用した既定値（質問予算または明確さを考慮し、質問しなかった項目）：

[ASSUMES: X] [ASSUMES: Y] [ASSUMES: Z]

成功基準：

1. [基準 1]
2. [基準 2]

これで合っていますか？」

確認を待ちます。前提条件に異議がある場合は、ユーザーがその内容を上書きしたり、調整を依頼したりできるようにします。

フェーズ 7：要件をテンプレートトークンに割り当てる（前提条件を含む）

要件と前提条件をユーザーに確認した後、収集したデータをテンプレートトークンに割り当てます。

const tokens = {
  // Required tokens
  FEATURE_NAME: gatheredRequirements.taskName,
  VERSION: '1.0.0',
  AUTHOR: 'Claude',
  DATE: new Date().toISOString().split('T')[0],
  STATUS: 'draft',

  // Required: Acceptance criteria (minimum 1, maximum 50)
  ACCEPTANCE_CRITERIA_1: gatheredRequirements.criteria[0] || '[Define acceptance criterion 1]',
  ACCEPTANCE_CRITERIA_2: gatheredRequirements.criteria[1] || '[Define acceptance criterion 2]',
  ACCEPTANCE_CRITERIA_3: gatheredRequirements.criteria[2] || '[Define acceptance criterion 3]',

  // Optional tokens (can be empty strings if not gathered)
  TERM_1: gatheredRequirements.terms?.[0] || '',
  TERM_2: gatheredRequirements.terms?.[1] || '',
  TERM_3: gatheredRequirements.terms?.[2] || '',

  HTTP_METHOD: gatheredRequirements.httpMethod || '',
  ENDPOINT_PATH: gatheredRequirements.endpointPath || '',
  PROJECT_NAME: gatheredRequirements.projectName || 'Agent Studio',

  // Assumptions from context-compressor (optional but recommended)
  ASSUMPTIONS_MADE: gatheredRequirements.assumptions.map(a => `- ${a}`).join('\n') || '',
  CLARIFICATIONS_ASKED: gatheredRequirements.clarifications || 0,
};

レンダリング前の検証：

• 必須トークンがすべて入力されていることを確認します（FEATURE_NAME、VERSION、AUTHOR、DATE、STATUS）
• 少なくとも 1 つの ACCEPTANCECRITERIA* トークンに意味のある値が入力されていることを確認します（プレースホルダーではないこと）
• すべての前提条件が [ASSUMES:] 表記で記録されていることを確認します
• 必須情報が不足している場合は、不足している情報をユーザーに尋ねます
• 明確化の質問が 5 件を超えた場合は、要件が不完全である可能性をユーザーに警告します

フェーズ 8：テンプレートを使って仕様をレンダリングする

template-renderer スキルを呼び出して仕様を作成します。

Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'specification-template',
    outputPath: `.claude/context/artifacts/specifications/${featureNameSlug}-spec.md`,
    tokens: tokens,
  },
});

出力先：.claude/context/artifacts/specifications/[feature-name]-spec.md

レンダリング後の検証：

# Check file created
SPEC_FILE=".claude/context/artifacts/specifications/[feature-name]-spec.md"
test -f "$SPEC_FILE" && echo "✓ Spec created" || echo "✗ Spec creation failed"

# Check no unresolved tokens
grep -E '[{]{2}' "$SPEC_FILE" && echo "✗ Unresolved tokens found" || echo "✓ All tokens resolved"

# Check YAML frontmatter valid
YAML_COUNT=$(head -50 "$SPEC_FILE" | grep -E "^---$" | wc -l)
test "$YAML_COUNT" -eq 2 && echo "✓ YAML valid" || echo "✗ YAML invalid"

検証チェックリスト

要件の収集を完了する前に、次の項目を確認します。

• タスクの説明をユーザーに確認した
• progressive disclosure モードで context-compressor スキルを呼び出した（フェーズ 4.5）
• 明確化の質問数が上限（最大 3～5 件）を超えていない
• 重要度が「CRITICAL」の質問を行い、回答を得た
• すべての前提条件を [ASSUMES:] 表記で記録した
• ワークフローの種類を特定し、確認した
• 範囲と影響を受ける領域を特定した
• 具体的な要件を記録した
• 受け入れ基準を定義した（最低 1 件。ACCEPTANCE_CRITERIA_1/2/3 に割り当て済み）
• 制約を記録した
• ユーザーが最終的な要約（前提条件を含む）を確認した
• 作業を進める前に、ユーザーが前提条件を上書きできるようにした
• トークンの割り当てが完了した（ASSUMPTIONS_MADE を含め、すべての必須トークンに値を入力した）
• テンプレートレンダラーの呼び出しに成功した
• 仕様ファイルを作成した（未解決のトークンがない）
• YAML のフロントマターが有効である（区切りが 2 つあり、必須フィールドが含まれている）
• 仕様の出力に [ASSUMES:] 表記が含まれている

よくある間違い

質問せずに決めつける

なぜ間違いなのか： 前提を決めつけると、誤ったものを作ってしまう可能性があります。

代わりに行うこと： 明確化の質問をし、理解した内容を確認します。

確認を省略する

なぜ間違いなのか： ユーザーが要約を誤解している可能性があります。

代わりに行うこと： 必ず要約し、明示的な確認を待ちます。

要件が曖昧

なぜ間違いなのか： 「もっと良くする」だけでは、実行に移せません。

代わりに行うこと： 具体的に確認します。どのような動作か、どのような結果か、どう検証するのかを尋ねます。

他のスキルとの連携

このスキルは、以下のスキルと相性よく連携します。

• context-compressor：Phase 4.5（段階的開示モード）で呼び出され、ECLAIR パターン（3～5 件の上限、スマートなデフォルト、[ASSUMES:] 表記）を用いて確認プロセスを最適化します
• template-renderer：Phase 8 の後に自動的に使用され、収集した要件と前提条件を使って仕様テンプレートをレンダリングします
• spec-critique：生成された仕様の検証に使用します
• complexity-assessment：要件が明確になった後に複雑さを評価します
• brainstorming：要件の収集前に創造的な探索を行うために使用します

ワークフローチェーン：

spec-gathering (→ context-compressor in Phase 4.5) → template-renderer → spec-critique → planner

Context-Compressor との連携の詳細（段階的開示モード）：

• タイミング：Phase 5 の開始時（手動で質問する前）に呼び出されます
• 理由：確認事項を 3～5 件に制限して認知負荷を軽減し、スマートなデフォルトを適用し、すべての前提条件を記録します
• 出力：[ASSUMES:] 表記付きの優先順位付けされた質問とデフォルトの前提条件
• 影響：仕様には記録された前提条件が含まれ、実装時に変更できます

例

例 1：機能リクエスト（段階的開示とテンプレートのレンダリングを含むエンドツーエンド）

入力：「アプリにユーザー認証を追加する」

プロセス：

1. タスクを確認します：「ユーザー認証を追加したいということですね。合っていますか？」

   • ユーザーが確認します

2. 段階的開示モードで context-compressor を呼び出します（Phase 4.5）：

   Skill({
     skill: 'context-compressor',
     context: {
       taskDescription: "Add user authentication",
       projectContext: {...},
       mode: 'progressive-disclosure'
     }
   });
   

3. Context-compressor が返す内容：

   • 重要な質問（5 件の上限のうち 3 件を質問）：

     1. 「ユーザーはメールでパスワードをリセットできるようにしますか？」→ はい
     2. 「ロールベースのアクセス制御（RBAC）は必要ですか？」→ はい（Admin、User、Guest）
     3. 「シングルサインオン（SSO）は必要ですか？」→ いいえ

   • 適用された前提条件（[ASSUMES:] 表記付き）：

     • [ASSUMES: 有効期限 1 時間の JWT トークン]
     • [ASSUMES: パスワードのハッシュ化に bcrypt を使用し、コストファクターは 12]
     • [ASSUMES: すべてのエンドポイントで HTTPS を必須とする]

4. スコープを特定します：「バックエンド API、データベース、フロントエンドのログインページに影響します。」

   • ユーザーがスコープを確認します

5. 確認事項とデフォルトに基づいて成功基準を定義します

6. トークンにマッピングします：

{
  FEATURE_NAME: "User Authentication",
  VERSION: "1.0.0",
  AUTHOR: "Claude",
  DATE: "2026-01-28",
  STATUS: "draft",
  ACCEPTANCE_CRITERIA_1: "Users can sign up with email and password",
  ACCEPTANCE_CRITERIA_2: "Email verification required before login",
  ACCEPTANCE_CRITERIA_3: "Users can reset password via email link",
  ACCEPTANCE_CRITERIA_4: "Role-based access control working (Admin/User/Guest)",
  ASSUMPTIONS_MADE: "- JWT tokens with 1-hour expiry\n- bcrypt cost factor 12\n- HTTPS required",
  CLARIFICATIONS_ASKED: 3
}

1. template-renderer を呼び出します：

Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'specification-template',
    outputPath: '.claude/context/artifacts/specifications/user-authentication-spec.md',
    tokens: tokens,
  },
});

出力：

• .claude/context/artifacts/specifications/user-authentication-spec.md にレンダリングされた仕様
• すべてのトークンを解決済み
• 前提条件を [ASSUMES:] 表記で明確に記録
• YAML フロントマターが有効
• spec-critique によるレビューの準備完了（ユーザーは任意の前提条件に異議を唱えられます）

例 2：バグ調査

入力：「ページの読み込みが遅い」

プロセス：

1. 確認します：「具体的にはどのページですか？どのくらいの遅さを想定していますか？」
2. 状況を確認します：「いつから発生していますか？最近変更したことはありますか？」
3. 指標を確認します：「許容できる読み込み時間はどのくらいですか？」

**出力：**具体的なページ、指標、成功基準を含む調査要件。

トラブルシューティング

問題：ユーザーの回答が一言だけ

症状：「はい」「いいえ」「それで大丈夫です」など、詳細がありません。

**解決策：**より具体的な質問をします。選択肢を提示します：「A、B、C のどれがよいですか？」

問題：スコープが拡大し続ける

**症状：**回答のたびに新しい機能が追加されます。

**解決策：「対象外」を明確に記録します。確認します：「これを今回のタスクに含めますか？それとも後回しにしますか？」

絶対遵守事項

1. STANDARD 以上の複雑さでは、検証済みの仕様が存在する前に決して実装を開始しないでください
2. パフォーマンス、セキュリティ、スケーラビリティなどの非機能要件を必ず明示的に収集してください
3. 曖昧な成功基準を決して受け入れず、測定可能でテスト可能な数値を求めてください
4. スコープ内の内容だけでなく、明示的にスコープ外とする内容も必ず記録してください
5. 要件についてユーザーの明示的な確認を得ずに、プランナーへ引き継いでは決していけません

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
要件が曖昧（「速くする」）	測定もテストもできません	「P95 応答時間 <100ms」のように、具体的な指標を指定します
非機能要件の欠落	品質特性への配慮が後回しになります	パフォーマンス、セキュリティ、スケーラビリティの要件を必ず記録します
対象外の項目の記載がない	実装中にスコープが拡大します	このタスクに含まれない内容を明確に記載します
ユーザー確認の省略	要件を誤解し、誤った実装につながります	引き継ぎ前に、すべての要件をユーザーと確認します
エッジケースの未記載	QA 中にエラー処理の不備が見つかります	空の入力、不正なデータ、タイムアウト、同時アクセスのケースを記載します

メモリプロトコル

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 見つかった問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断を想定してください。メモリに記録されていなければ、起きていないのと同じです。