ousiass spec-gen
不明点はユーザーと積極的に会話し、参考アイデアを提示しながら仕様を固める。
前提条件
- Claude Code 環境
ghCLI（GitHub Issue モード時）
引数
- 引数なし: 新規プロジェクトの設計ドキュメント一式を作成
- パス指定: 既存の仕様書に対して追記・更新
生成するドキュメント（デフォルトパス）
| ドキュメント | デフォルトファイル | 内容 |
|---|---|---|
| 機能要件 | docs/requirements/functional.md |
ユースケース、機能一覧、画面・操作フロー |
| 非機能要件 | docs/requirements/non-functional.md |
性能、セキュリティ、可用性、スケーラビリティ |
| アーキテクチャ設計 | docs/architecture/overview.md |
全体構成、技術選定、レイヤー構造、通信フロー |
| ER / データモデル | docs/architecture/er.md |
全体ER図、テーブル別ER図、テーブル定義、制約、インデックス |
| API 仕様 | docs/api/endpoints.md |
エンドポイント、リクエスト/レスポンス、認証、エラー |
| コンポーネント設計 | docs/components/overview.md |
コンポーネント分割、責務、依存関係、インターフェース |
- 上記はデフォルトパス。既存の仕様書ディレクトリが見つかった場合はそちらを使う（下記「探索」参照）
フェーズ1: 現状把握と方針決定
1-0: 既存仕様書の探索（必須・最初に実行）
引数でパスが指定されている場合:
- そのパスのファイル/ディレクトリを直接読み込む
- 同じディレクトリ内の関連ファイルも確認する
引数なしの場合: 以下のパターンで既存仕様書を検索する（Glob を使用）:
**/spec/**/*.md
**/specs/**/*.md
**/docs/**/*.md
**/specifications/**/*.md
**/design/**/*.md
探索結果に基づく判定:
- 既存仕様書が見つかった場合: そのディレクトリ構造とファイルパスをベースマップとして記録する。新規ドキュメントもこの構造に合わせて配置する。デフォルトパスは使わない
- 見つからなかった場合: デフォルトパス（
docs/配下）を使用する
重要: 探索で見つけた仕様書は必ず内容を Read で読み込み、現在の仕様を把握してからフェーズを進める。
出力先の選択
AskUserQuestion で確認：
- GitHub Issue + ブランチ作成（推奨）: 実装 Issue を立て、その番号で作業ブランチを作る。最終的に同じ Issue を
implに渡せる - ローカルのみ: Issue やブランチを作成せず現在のブランチで作業
新規プロジェクトの場合
- 概要・目的・背景をヒアリング
- 類似プロジェクト・技術選定の方向性を提示
- ドキュメント範囲を合意
- GitHub Issue モード: ベースブランチ記録 → プレースホルダー Issue 作成 →
feat/#<Issue番号>ブランチ作成 → Issue にブランチ名追記- Issue タイトルは
feat: <機能名>（実装する機能名）。「設計ドキュメント作成」のようなドキュメント作業自体をタイトルにしない - 本文はこの時点ではプレースホルダーでよい（例:
仕様策定中（spec-gen 実行中）。完了後に実装内容を追記する。）。フェーズ3で本文を実装 Issue に書き換える - 仕様策定自体はこのスキルの作業であり Issue として独立させない。同じ Issue 番号を最終的に
implで再利用するための「番号確保」が目的
- Issue タイトルは
- TaskCreate でタスク化
既存仕様書への追記の場合
- 1-0 の探索結果を使い、既存仕様書をすべて Read で読み込み現在の仕様を把握
- 追加内容をヒアリング
- 既存機能の再利用・変更案を提示
- 方針を合意
- GitHub Issue モード: 上記と同様（Issue タイトルは追加する機能を記述する。本文はプレースホルダー）
- TaskCreate でタスク化
フェーズ2: ドキュメント作成サイクル（各ドキュメントで繰り返し）
2-1: ヒアリング
- 当該ドキュメントに必要な情報を
AskUserQuestion1回にまとめて質問 - 選択肢の
descriptionにメリット・デメリット等の参考アイデアを記載
2-2: 執筆
- ヒアリング内容に基づき作成。図表は Mermaid 記法（
references/mermaid-guide.md参照） - 改訂履歴を記載（
references/mermaid-guide.md末尾のフォーマット参照）
2-3: レビュー
- ユーザーに提示し
AskUserQuestionで確認（「問題なし」選択肢を含める）
2-4: 改善サイクル
- フィードバックあり → 修正 → 改訂履歴更新 → 再確認 → なくなるまで繰り返す
2-5: Format & Lint
- 設定があれば実行。なければスキップ
2-6: Commit
- CLAUDE.md の規約に従いコミット
フェーズ3: 完了確認と push
- 全ドキュメントの完了確認
- ドキュメント間の整合性チェック（ER と API、コンポーネントと機能要件等）
- GitHub Issue モード: push → Issue 本文を実装 Issue に書き換える → サマリー報告（Issue URL 含む）
- フェーズ1で立てたプレースホルダー Issue の本文を
templates/impl-issue.mdのフォーマットに従って実装 Issue として完成させる - 含める内容: 概要、仕様書ファイルへのリンク一覧（実装時に参照すべきもの）、受け入れ条件、ベースブランチ
- 受け入れ条件は仕様書から具体的な完了条件を抽出して列挙する（曖昧な「実装する」だけにしない）
- 一時ファイルに本文を書き出し
gh issue edit <番号> --body-file <一時ファイル>で反映 → 一時ファイル削除 - Issue はクローズせず open のまま残す（
/impl #<番号>がそのまま使える）
- フェーズ1で立てたプレースホルダー Issue の本文を
- ローカルモード: サマリー報告（パス一覧）
ルール
- 不明点は推測せず必ずユーザーに確認する
- 質問には必ず
AskUserQuestionを使い選択式で提示する。 テキストだけで質問しない - 1回あたり4問以内にまとめる
- 各選択肢の
descriptionに参考アイデアを記載する - 既存仕様書への追記時は既存機能の再利用・変更を優先的に検討
- ドキュメント更新時は必ず改訂履歴を追記する
- TaskCreate/TaskUpdate で進捗を管理する
- 既存の仕様書ディレクトリが見つかった場合、デフォルトパス（
docs/）ではなく既存パスにファイルを配置する。新しいサブディレクトリを勝手に作成しない - 既存ファイルを更新する場合は Edit で直接編集する。同じ内容の新規ファイルを別の場所に作成しない