name: spec-writer description: 対話形式で要件を深掘りし、実装者が迷わない詳細な仕様書を作成します。ユーザーが気づいていない課題や考慮漏れを質問で洗い出し、UI/UXを含む包括的な仕様を文書化します。

このスキルは、実装前の仕様書作成を支援します。対話形式で要件を深掘りし、ユーザー自身が気づいていない課題や考慮漏れを質問によって明らかにします。最終的に、実装者が迷わず作業を進められる詳細な仕様書を作成します。

スキルの目的

要件の明確化: 曖昧な要件を具体的に定義する
考慮漏れの発見: ユーザーが見落としている点を質問で洗い出す
実装の円滑化: 実装時に迷わないレベルの詳細な仕様を提供する
品質の向上: 事前に課題を洗い出し、手戻りを防ぐ

仕様書作成の流れ

Phase 1: 初期ヒアリング

まず、ユーザーから提示された内容を確認し、以下の基本情報を把握します：

何を作るのか（機能・画面・API等）
なぜ作るのか（目的・背景）
誰が使うのか（ユーザー・利用者）

この段階では、ユーザーの説明を遮らず、全体像を理解することに集中します。

Phase 2: 構造的な質問による深掘り

以下のカテゴリに沿って、体系的に質問を行います。理解が完全になるまで質問を続けます。

2.1 機能要件

主要機能: この機能の核となる動作は何か？
入力: どのようなデータを受け取るか？（形式、必須/任意、バリデーションルール）
処理: 受け取ったデータをどう処理するか？（ビジネスロジック、計算、変換）
出力: 何を返すか？（画面表示、APIレスポンス、ファイル等）
状態管理: データの状態はどう管理されるか？（永続化、セッション、メモリ）
例外処理: エラー時の挙動は？（エラーメッセージ、リトライ、ロールバック）

2.2 UI/UX要件（UIが含まれる場合）

UIが含まれる場合は、特に詳細に確認します：

ページ構成: どのようなレイアウトか？（ヘッダー、サイドバー、メインコンテンツ、フッター）
コンポーネント配置: 各要素をどこに配置するか？（位置関係、グリッドレイアウト）
インタラクション: ユーザーはどう操作するか？（クリック、ドラッグ、入力）
フィードバック: 操作結果をどう表示するか？（ローディング、成功/エラーメッセージ、アニメーション）
レスポンシブ: モバイル/タブレット対応は？（ブレークポイント、表示切り替え）
アクセシビリティ: キーボード操作、スクリーンリーダー対応は？
デザインシステム: 既存のUIコンポーネントやスタイルガイドに従うか？

UI理解のための質問例:

「このボタンを押すと、どこに何が表示されますか？」
「データが多い場合、どのように表示しますか？（ページネーション、無限スクロール）」
「このフォームの入力項目は何ですか？それぞれ必須ですか？」
「モーダルやドロワーは使いますか？」
「一覧表示の場合、ソート・フィルター機能は必要ですか？」

2.3 データ要件

データモデル: どのようなデータ構造か？（Entity、リレーション）
データソース: データはどこから取得するか？（DB、API、ファイル）
データフロー: データはどのように流れるか？（取得→加工→表示→更新）
永続化: データをどこに保存するか？（DB、ローカルストレージ、外部サービス）
整合性: データの整合性をどう保つか？（トランザクション、バリデーション）

2.4 非機能要件

パフォーマンス: 応答時間の目標は？大量データへの対応は？
セキュリティ: 認証・認可は？データの保護方法は？
可用性: ダウンタイムの許容範囲は？
スケーラビリティ: 将来的なユーザー増加への対応は？
保守性: ログ出力、監視、デバッグの仕組みは？

2.5 外部連携

API連携: 外部APIを使うか？（認証方法、レート制限、エラーハンドリング）
他システム連携: 既存システムとの連携は？（データ同期、イベント通知）
サードパーティライブラリ: 使用する外部ライブラリは？

2.6 テスト要件

テスト観点: 何をテストすべきか？（正常系、異常系、境界値）
テスト方法: 単体テスト、結合テスト、E2Eテストは？
テストデータ: どのようなテストデータを用意するか？

Phase 3: 確認と補完

質問を一通り終えたら、以下を確認します：

抜け漏れチェック: 「他に考慮すべき点はありませんか？」
制約事項: 「技術的な制約や期限はありますか？」
既存資産: 「参考にすべき既存コードやドキュメントはありますか？」

Phase 4: 仕様書作成

全ての情報が揃ったら、以下の構成で仕様書を作成します：

# [機能名] 仕様書

## 1. 概要

### 1.1 目的
[なぜこの機能を作るのか]

### 1.2 対象ユーザー
[誰が使うのか]

### 1.3 背景
[どのような課題を解決するのか]

## 2. 機能仕様

### 2.1 機能概要
[機能の全体像]

### 2.2 画面構成（UIがある場合）
[ページレイアウト、コンポーネント配置、ワイヤーフレーム]

### 2.3 機能詳細
[各機能の詳細な動作]

### 2.4 入出力仕様
- **入力**: [データ形式、バリデーションルール]
- **出力**: [レスポンス形式、表示内容]

### 2.5 状態管理
[データの状態遷移、永続化方法]

### 2.6 エラーハンドリング
[エラーケースと対処方法]

## 3. データ仕様

### 3.1 データモデル
[Entity定義、リレーション]

### 3.2 API仕様（該当する場合）
[エンドポイント、リクエスト/レスポンス形式]

### 3.3 データベーススキーマ（該当する場合）
[テーブル定義、インデックス]

## 4. UI/UX仕様（UIがある場合）

### 4.1 レイアウト
[ページ構成、グリッドレイアウト]

### 4.2 コンポーネント一覧
[使用するUIコンポーネントとその配置]

### 4.3 インタラクション
[ユーザー操作とシステムの応答]

### 4.4 レスポンシブ対応
[ブレークポイント、モバイル表示]

### 4.5 アクセシビリティ
[キーボード操作、ARIA対応]

## 5. 非機能要件

### 5.1 パフォーマンス
[応答時間、スループット]

### 5.2 セキュリティ
[認証・認可、データ保護]

### 5.3 可用性・信頼性
[ダウンタイム、エラー率]

## 6. 外部連携

### 6.1 外部API
[連携先、認証方法、エラーハンドリング]

### 6.2 他システム連携
[データ同期、イベント通知]

## 7. テスト仕様

### 7.1 テスト観点
[正常系、異常系、境界値テスト]

### 7.2 テストケース
[具体的なテストケース一覧]

## 8. 備考

### 8.1 制約事項
[技術的制約、ビジネス制約]

### 8.2 今後の拡張予定
[将来的な機能追加の可能性]

### 8.3 課題・懸念事項
[実装時に注意すべき点]

質問の進め方

基本原則

一度に多くを質問しない: 3〜5個の質問ずつ、段階的に確認する
回答を踏まえて深掘り: ユーザーの回答から新たな質問を導く
具体例を求める: 曖昧な回答には「例えば？」と具体化を促す
視覚化を促す: 「どのように配置されますか？」「どこに表示されますか？」
前提を確認する: 「〜という理解で合っていますか？」と認識を合わせる

AskUserQuestionツールの活用

選択肢形式で質問できる場合は、積極的にAskUserQuestionツールを使用してください。

ユーザーは選択肢から選ぶだけで回答でき、心理的な負担が大幅に軽減されます。

いつ使うか

以下のような場合に、AskUserQuestionツールを使用します：

アプローチの選択: 複数の実装方法から選ぶ場合（例：ページネーション vs 無限スクロール）
UI/UXパターン: デザインパターンやレイアウトを選ぶ場合（例：モーダル vs ドロワー vs 別ページ）
データ表示形式: 情報の表示方法を選ぶ場合（例：テーブル vs カード vs リスト）
機能の有無: 特定機能を実装するか確認する場合（例：ソート機能、フィルター機能）

使い方のガイドライン

質問は1〜4個まで: 一度に多くを聞きすぎない
選択肢は2〜4個: 選択肢が多すぎると逆に負担になる
明確なラベル: 選択肢のラベルは簡潔に（1〜5単語）
説明を付ける: 各選択肢に説明（description）を付けて、選びやすくする
multiSelectの活用: 排他的でない選択肢（複数選択可能）の場合はmultiSelect: trueを使用
headerは短く: 12文字以内の短いラベルをつける

質問設計の例

良い選択肢形式の質問:

質問: 「検索結果が多い場合、どのように表示しますか？」
header: 「表示方式」
選択肢:
  - ページネーション（ページ番号で切り替え）
  - 無限スクロール（スクロールすると自動読み込み）
  - 「もっと見る」ボタン（ボタンクリックで追加読み込み）

質問: 「検索結果の表示形式はどれが適していますか？」
header: 「表示形式」
選択肢:
  - テーブル形式（行と列で整理）
  - カード形式（各結果をカード表示）
  - リスト形式（シンプルなリスト）

質問: 「どの機能を実装しますか？」（複数選択可）
header: 「必要な機能」
multiSelect: true
選択肢:
  - ソート機能（列をクリックで並び替え）
  - フィルター機能（条件で絞り込み）
  - エクスポート機能（CSV/Excel出力）
  - 一括操作（複数選択して一括処理）

テキスト質問との使い分け

以下の場合は、通常のテキスト質問を使用してください：

自由記述が必要: 具体的な文言、数値、名称などを聞く場合
選択肢を事前に用意できない: 回答のバリエーションが予測できない場合
複雑な説明が必要: ユーザーが詳細を説明する必要がある場合

テキスト質問の例:

「検索結果が0件の場合、どのようなメッセージを表示しますか？」（具体的な文言を聞く）
「この画面のページタイトルは何にしますか？」（名称を聞く）
「1ページあたり何件表示しますか？」（数値を聞く）

質問の例

良い質問:

「ユーザーが検索ボタンを押した後、結果はどこにどのように表示されますか？」
「検索結果が0件の場合、どのようなメッセージを表示しますか？」
「検索中はローディング表示をしますか？その場合、どのような表示ですか？」

避けるべき質問:

「何か他に考慮すべき点はありますか？」（漠然としすぎ）
「この機能の仕様は？」（範囲が広すぎ）

スキル実行時の注意事項

焦らない: 理解が不十分な状態で仕様書を作らない
仮定しない: 不明点は必ず確認する（「おそらく〜だろう」はNG）
視覚化: UI要件は図やワイヤーフレームで確認（必要に応じてASCIIアートも活用）
プロジェクト固有ルールの確認: CLAUDE.mdや既存ドキュメントを参照し、プロジェクトの規約に従う

成果物

最終的に、以下が含まれた仕様書を出力します：

✅ 実装者が迷わず作業できる詳細度
✅ UI/UXの具体的な設計（該当する場合）
✅ データモデルとAPI仕様
✅ エラーケースとエッジケースへの対応
✅ テスト観点と非機能要件

重要: このスキルの成功は「どれだけ深く質問できるか」にかかっています。ユーザーの最初の説明だけで満足せず、実装者が困らないレベルまで要件を明確にしてください。ただし、同時に質問するとユーザーは困惑するため、**1度のやり取りでは多くても必ず5問に止めてください。**それによりユーザーの心理的な負担を減らすことができるため、問答においてこの制約が何よりも重要です。

spec-writer

SKILL.md