ousiass/spec-gen

spec-gen

不明点はユーザーと積極的に会話し、参考アイデアを提示しながら仕様を固める。

前提条件

• Claude Code 環境
• gh CLI（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 やブランチを作成せず現在のブランチで作業

新規プロジェクトの場合

1. 概要・目的・背景をヒアリング
2. 類似プロジェクト・技術選定の方向性を提示
3. ドキュメント範囲を合意
4. GitHub Issue モード: ベースブランチ記録 → プレースホルダー Issue 作成 → feat/#<Issue番号> ブランチ作成 → Issue にブランチ名追記
   • Issue タイトルは feat: <機能名>（実装する機能名）。「設計ドキュメント作成」のようなドキュメント作業自体をタイトルにしない
   • 本文はこの時点ではプレースホルダーでよい（例: 仕様策定中（spec-gen 実行中）。完了後に実装内容を追記する。）。フェーズ3で本文を実装 Issue に書き換える
   • 仕様策定自体はこのスキルの作業であり Issue として独立させない。同じ Issue 番号を最終的に impl で再利用するための「番号確保」が目的
5. TaskCreate でタスク化

既存仕様書への追記の場合

1. 1-0 の探索結果を使い、既存仕様書をすべて Read で読み込み現在の仕様を把握
2. 追加内容をヒアリング
3. 既存機能の再利用・変更案を提示
4. 方針を合意
5. GitHub Issue モード: 上記と同様（Issue タイトルは追加する機能を記述する。本文はプレースホルダー）
6. TaskCreate でタスク化

フェーズ2: ドキュメント作成サイクル（各ドキュメントで繰り返し）

2-1: ヒアリング

• 当該ドキュメントに必要な情報を AskUserQuestion 1回にまとめて質問
• 選択肢の 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

1. 全ドキュメントの完了確認
2. ドキュメント間の整合性チェック（ER と API、コンポーネントと機能要件等）
3. GitHub Issue モード: push → Issue 本文を実装 Issue に書き換える → サマリー報告（Issue URL 含む）
   • フェーズ1で立てたプレースホルダー Issue の本文を templates/impl-issue.md のフォーマットに従って実装 Issue として完成させる
   • 含める内容: 概要、仕様書ファイルへのリンク一覧（実装時に参照すべきもの）、受け入れ条件、ベースブランチ
   • 受け入れ条件は仕様書から具体的な完了条件を抽出して列挙する（曖昧な「実装する」だけにしない）
   • 一時ファイルに本文を書き出し gh issue edit <番号> --body-file <一時ファイル> で反映 → 一時ファイル削除
   • Issue はクローズせず open のまま残す（/impl #<番号> がそのまま使える）
4. ローカルモード: サマリー報告（パス一覧）

ルール

• 不明点は推測せず必ずユーザーに確認する
• 質問には必ず AskUserQuestion を使い選択式で提示する。 テキストだけで質問しない
• 1回あたり4問以内にまとめる
• 各選択肢の description に参考アイデアを記載する
• 既存仕様書への追記時は既存機能の再利用・変更を優先的に検討
• ドキュメント更新時は必ず改訂履歴を追記する
• TaskCreate/TaskUpdate で進捗を管理する
• 既存の仕様書ディレクトリが見つかった場合、デフォルトパス（docs/）ではなく既存パスにファイルを配置する。新しいサブディレクトリを勝手に作成しない
• 既存ファイルを更新する場合は Edit で直接編集する。同じ内容の新規ファイルを別の場所に作成しない