ousiass design-spec
UI/UX・システム設計の両面をカバーするデザイン仕様書を、おすすめを提示しながらヒアリングして作成する。既存ドキュメントへの追記にも対応。
前提条件
- Claude Code 環境
ghCLI（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 で以下を確認（引数から判明済みの情報はスキップ）：
- 対象: 新規画面 or 既存画面のリデザイン（スキャン結果から画面一覧を選択肢に含める）
- 範囲: 作成するドキュメントの選択（4種すべて or 必要なもののみ）
- デザインの方向性: 選択肢で提示
- 既存デザイン基盤に合わせる / 新しい方向性を定義する / 参考デザインがある
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: 完了
- 全ドキュメントの完了確認
- ドキュメント間の整合性チェック（画面設計とコンポーネント、トークンとコンポーネント等）
- 出力モードに応じた処理：
- Issue + Branch + PR: push → PR 作成 → Issue に仕様書リンク追記 → サマリー報告
- Issue + Branch: push → Issue に仕様書リンク追記 → サマリー報告
- コミットまで: サマリー報告（パス一覧）
- ファイル作成のみ: サマリー報告（パス一覧）
ルール
- 不明点は推測せず必ずユーザーに確認する
- 質問には必ず
AskUserQuestionを使い選択式で提示する。 テキストだけで質問しない - 1回あたり4問以内にまとめる
- 各選択肢の
descriptionにおすすめ理由やメリット・デメリットを記載する - 既存ドキュメントへの追記時は既存構造・スタイルとの整合性を優先
- ドキュメント更新時は必ず改訂履歴を追記する
- TaskCreate/TaskUpdate で進捗を管理する
- 既存の仕様書ディレクトリが見つかった場合、デフォルトパスではなく既存パスにファイルを配置する
- 既存ファイルを更新する場合は Edit で直接編集する。同じ内容の新規ファイルを別の場所に作成しない
- プロジェクトに存在しないコンポーネントや画面を選択肢に含めない