ousiass/design-spec

design-spec

UI/UX・システム設計の両面をカバーするデザイン仕様書を、おすすめを提示しながらヒアリングして作成する。既存ドキュメントへの追記にも対応。

前提条件

• Claude Code 環境
• gh CLI（GitHub 連携モード時）

引数

• 引数なし: 新規デザイン仕様書を作成
• パス指定: 既存のデザイン仕様書に追記・更新
• テキスト: 初期情報として扱い、不足分をヒアリング

生成するドキュメント（デフォルトパス）

| ドキュメント | デフォルトファイル | 内容 | |------------|---------|------| | 画面設計 | docs/design/screens.md | 画面一覧、ワイヤーフレーム（ASCII/Mermaid）、画面遷移図 | | コンポーネント仕様 | docs/design/components.md | コンポーネント一覧、Props/状態定義、バリアント | | デザイントークン | docs/design/tokens.md | カラー、タイポグラフィ、スペーシング、その他トークン | | インタラクション仕様 | docs/design/interactions.md | ユーザー操作、状態遷移図、アニメーション、エラー/ローディング状態 |

• 上記はデフォルトパス。既存の仕様書ディレクトリが見つかった場合はそちらを使う（下記「探索」参照）

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

1-0: 既存ドキュメントの探索（必須・最初に実行）

引数でパスが指定されている場合:

• そのパスのファイル/ディレクトリを直接読み込む
• 同じディレクトリ内の関連ファイルも確認する

引数なしの場合: 以下のパターンで既存ドキュメントを検索する（Glob を使用）:

**/spec/**/*.md
**/specs/**/*.md
**/docs/**/*.md
**/design/**/*.md
**/specifications/**/*.md

探索結果に基づく判定:

• 既存ドキュメントが見つかった場合: そのディレクトリ構造を記録し、デザイン仕様書もこの構造に合わせて配置する。デフォルトパスは使わない
• 見つからなかった場合: デフォルトパス（docs/design/ 配下）を使用する

重要: 探索で見つけたドキュメントは必ず Read で読み込み、現在の仕様を把握してからフェーズを進める。

1-1: プロジェクトのスキャン

デザイン仕様に必要な情報を収集する：

• フレームワーク・UIライブラリ: React/Vue/Svelte, Tailwind/MUI/shadcn 等
• 既存デザイン基盤: tailwind.config.*, theme.ts, tokens.*, variables.css 等
• 画面・ページ構成: pages/, views/, routes/, app/ 等
• コンポーネント構成: components/ 配下の構造

スキャン結果はヒアリングの選択肢生成に使う。

1-2: 対象と方針のヒアリング

AskUserQuestion で以下を確認（引数から判明済みの情報はスキップ）：

1. 対象: 新規画面 or 既存画面のリデザイン（スキャン結果から画面一覧を選択肢に含める）
2. 範囲: 作成するドキュメントの選択（4種すべて or 必要なもののみ）
3. デザインの方向性: 選択肢で提示
   • 既存デザイン基盤に合わせる / 新しい方向性を定義する / 参考デザインがある

1-3: 出力先の選択

AskUserQuestion で確認：

• GitHub Issue + ブランチ + PR: feat Issue を作成し作業ブランチで作業、完了後 PR 作成
• GitHub Issue + ブランチ: feat Issue を作成し作業ブランチで作業。PR は手動
• コミットまで: 現在のブランチでファイル作成・コミットのみ
• ファイル作成のみ: ファイル生成のみ。git 操作なし

GitHub Issue モード選択時:

• ベースブランチ記録 → feat Issue 作成 → feat/#<Issue番号> ブランチ作成 → Issue にブランチ名追記
• Issue タイトルは「デザインする対象」を記述する（例: feat: ダッシュボード画面のデザイン仕様）
• ブランチ作成前に同名ブランチの存在を確認する。既存の場合はサフィックス付与またはユーザーに確認

TaskCreate でタスク化。

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

2-1: ヒアリング

当該ドキュメントに必要な情報を AskUserQuestion 1回にまとめて質問（4問以内）。 選択肢の description におすすめ理由やメリット・デメリットを記載する。

ドキュメント別のヒアリング指針:

| ドキュメント | 聞くべきこと | おすすめの出し方 | |------------|------------|---------------| | 画面設計 | 主要画面、画面遷移、レスポンシブ要件 | 類似サービスのパターンを選択肢で提示 | | コンポーネント仕様 | 粒度、バリアント、共有コンポーネント | 既存UIライブラリのコンポーネントを提案 | | デザイントークン | ブランドカラー、フォント、スペーシング規則 | 業界標準のスケール（4px/8px等）を提案 | | インタラクション | 主要操作、遷移アニメーション、エラー表示 | 一般的なUXパターンを選択肢で提示 |

曖昧な回答への対応（references/clarification-patterns.md 参照）

2-2: 執筆

• ヒアリング内容に基づき作成
• 図表は Mermaid 記法（references/diagram-guide.md 参照）
• 画面モックアップは ASCII アートまたは Mermaid で表現
• 改訂履歴を末尾に記載（references/diagram-guide.md 末尾のフォーマット参照）

2-3: レビュー

ユーザーに提示し AskUserQuestion で確認（「問題なし」選択肢を含める）。

2-4: 改善サイクル

フィードバックあり → 修正 → 改訂履歴更新 → 再確認 → なくなるまで繰り返す。

2-5: Format & Lint

設定があれば実行。なければスキップ。

2-6: Commit

CLAUDE.md の規約に従いコミット（コミットモード以上の場合）。

フェーズ3: 完了

1. 全ドキュメントの完了確認
2. ドキュメント間の整合性チェック（画面設計とコンポーネント、トークンとコンポーネント等）
3. 出力モードに応じた処理：
   • Issue + Branch + PR: push → PR 作成 → Issue に仕様書リンク追記 → サマリー報告
   • Issue + Branch: push → Issue に仕様書リンク追記 → サマリー報告
   • コミットまで: サマリー報告（パス一覧）
   • ファイル作成のみ: サマリー報告（パス一覧）

ルール

• 不明点は推測せず必ずユーザーに確認する
• 質問には必ず AskUserQuestion を使い選択式で提示する。 テキストだけで質問しない
• 1回あたり4問以内にまとめる
• 各選択肢の description におすすめ理由やメリット・デメリットを記載する
• 既存ドキュメントへの追記時は既存構造・スタイルとの整合性を優先
• ドキュメント更新時は必ず改訂履歴を追記する
• TaskCreate/TaskUpdate で進捗を管理する
• 既存の仕様書ディレクトリが見つかった場合、デフォルトパスではなく既存パスにファイルを配置する
• 既存ファイルを更新する場合は Edit で直接編集する。同じ内容の新規ファイルを別の場所に作成しない
• プロジェクトに存在しないコンポーネントや画面を選択肢に含めない