# Spec Gen

> 新規プロジェクトの設計ドキュメント一式を対話的に作成する。既存仕様書への追記にも対応。

- Skill: `ousiass/spec-gen` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ousiass/spec-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ousiass/spec-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ousiass (https://skillmd.com/u/ousiass)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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 で直接編集する。同じ内容の新規ファイルを別の場所に作成しない**