AgentSkillsCN

spec-gen

以交互式方式编写全新项目的全套设计文档，并支持对现有规格说明书的补充与更新。

SKILL.md
--- frontmatter
name: spec-gen
description: 新規プロジェクトの設計ドキュメント一式を対話的に作成する。既存仕様書への追記にも対応。
user-invocable: true

spec-gen

プロジェクトの設計ドキュメントを対話的に作成・更新するスキル。不明点はユーザーと積極的に会話し、参考となるアイデアを提示しながら仕様を固めていく。

引数

  • •引数なし: 新規プロジェクトの設計ドキュメント一式を作成
  • •パス指定: 既存の仕様書に対して追記・更新を行う

生成するドキュメント

ドキュメントファイル内容
機能要件docs/requirements/functional.mdユースケース、機能一覧、画面・操作フロー
非機能要件docs/requirements/non-functional.md性能、セキュリティ、可用性、スケーラビリティ
アーキテクチャ設計docs/architecture/overview.md全体構成、技術選定、レイヤー構造、通信フロー
ER / データモデルdocs/architecture/er.mdテーブル定義、リレーション、制約、インデックス方針
API 仕様docs/api/endpoints.mdエンドポイント、リクエスト/レスポンス、認証、エラー
コンポーネント設計docs/components/overview.mdコンポーネント分割、責務、依存関係、インターフェース
  • •ディレクトリ構成やファイル名はプロジェクトの慣習があればそれに従う
  • •既存の仕様書がある場合は、上記構成に限らず既存の構成に合わせる

実行プロセス

フェーズ1: 現状把握と方針決定

新規プロジェクトの場合

  1. •ユーザーからプロジェクトの概要・目的・背景をヒアリングする
  2. •類似プロジェクトや技術選定の方向性について参考アイデアを提示する
  3. •生成するドキュメントの範囲をユーザーと合意する
  4. •現在のブランチをベースブランチとして記録する
  5. •実装用の feat Issue を gh issue create で作成し、Issue 番号を取得する
    • •タイトル: feat: <機能名> の形式
    • •本文に要件サマリーを記載する（フェーズ3 で仕様書リンク等を追記する）
  6. •作業ブランチ feat/#<Issue番号> を作成してチェックアウトする
  7. •gh issue edit で Issue 本文に作業ブランチ名を追記する
  8. •TodoWrite でドキュメント一覧をタスク化する

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

  1. •既存の仕様書をすべて読み込み、現在の仕様を正確に把握する
  2. •追加したい機能・変更内容をユーザーからヒアリングする
  3. •既存機能の再利用や変更で対応できる案を提示する
    • •「既存の○○を拡張すれば対応可能」
    • •「○○と○○を組み合わせれば実現できる」
    • •「新規で作る場合と既存を変更する場合の比較」
  4. •方針をユーザーと合意する
  5. •現在のブランチをベースブランチとして記録する
  6. •実装用の feat Issue を gh issue create で作成し、Issue 番号を取得する
    • •タイトル: feat: <機能名> の形式
    • •本文に要件サマリーを記載する（フェーズ3 で仕様書リンク等を追記する）
  7. •作業ブランチ feat/#<Issue番号> を作成してチェックアウトする
  8. •gh issue edit で Issue 本文に作業ブランチ名を追記する
  9. •TodoWrite でタスク化する

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

各ドキュメントに対して以下を実行：

ステップ2-1: ヒアリング

  • •当該ドキュメントに必要な情報をユーザーに質問する
  • •不明点や曖昧な点は必ずユーザーに確認する。推測で書かない
  • •質問は AskUserQuestion 1回にまとめる。 同じドキュメントについて複数回に分けて聞かない
  • •選択肢がある場合は、各選択肢のメリット・デメリットを参考アイデアとして提示する
  • •例:「認証方式は JWT と Session がありますが、○○の理由で JWT を推奨します。どちらにしますか？」

ステップ2-2: 執筆

  • •ヒアリング内容に基づきドキュメントを作成する
  • •既存仕様書への追記の場合は、既存の記述との整合性を保つ
  • •改訂履歴を記載する（後述のフォーマットに従う）

ステップ2-3: レビュー

  • •作成したドキュメントの内容をユーザーに提示し、AskUserQuestion で確認を求める
  • •「問題なし（次へ進む）」を選択肢に含め、フィードバックがなければすぐ次へ進めるようにする
  • •以下の観点でフィードバックを求める：
    • •記述内容が意図と合っているか
    • •不足している情報はないか
    • •表現や粒度は適切か

ステップ2-4: 改善サイクル

  • •フィードバックがある場合：
    • •修正を反映する
    • •改訂履歴を更新する
    • •再度ユーザーに確認する
    • •フィードバックがなくなるまで繰り返す

ステップ2-5: Format & Lint

  • •ドキュメントの format / lint 設定があれば実行する
  • •設定が見つからない場合はこのステップをスキップする

ステップ2-6: Commit

  • •現在のドキュメントの変更をコミットする
  • •コミットメッセージは CLAUDE.md の規約に従う
  • •コミット後、次のドキュメントへ進む

フェーズ3: 完了確認と push

  1. •すべてのドキュメントが作成・更新されたことを確認する
  2. •ドキュメント間の整合性を最終チェックする（ER とAPI、コンポーネントと機能要件など）
  3. •リモートに push する
  4. •gh issue edit で feat Issue の本文に仕様書へのリンク（作成したドキュメントのパス一覧）を追記する
  5. •作成内容のサマリーをユーザーに報告する（feat Issue URL を含める）

改訂履歴フォーマット

すべてのドキュメントの末尾に以下の形式で改訂履歴を記載する：

markdown
## 改訂履歴

| 版 | 日付 | 変更内容 | 変更理由 |
|---|------|---------|---------|
| 1.0 | YYYY-MM-DD | 初版作成 | — |
| 1.1 | YYYY-MM-DD | ○○のエンドポイントを追加 | ○○機能の追加に伴い |
  • •新規作成時は 1.0 から開始
  • •追記・更新時はマイナーバージョンを上げる（1.1, 1.2, ...）
  • •構成の大幅な変更はメジャーバージョンを上げる（2.0, 3.0, ...）
  • •変更理由は「なぜ変更したか」を簡潔に記載する

ルール

  • •不明点は推測せず、必ずユーザーに確認する
  • •少しでも曖昧さがあれば質問する。質問しすぎて困ることはない。確認不足で間違った仕様を書くほうが問題
  • •ユーザーへの質問・確認には必ず AskUserQuestion ツールを使い、選択式で提示する。 テキストだけで質問しない
  • •一度に大量の質問をせず、テーマごとにまとめて聞く（AskUserQuestion の上限である1回あたり4問以内）
  • •各選択肢の description に参考アイデア（推奨案、メリット・デメリット）を記載する
  • •既存仕様書への追記時は、既存機能の再利用・変更を優先的に検討し、案として提示する
  • •整合性問題はすべての重大度（🔴🟠🟡🟢）で修正する
  • •各フェーズの進捗は TodoWrite ツールで管理する
  • •ドキュメントの更新時は必ず改訂履歴を追記する