name: detailed-design-workflow description: 基本設計書を入力として、詳細設計書を作成し、モックアップ生成とテスト設計までを一貫して行うワークフロー。
詳細設計・完全ワークフロー (v2.9)
基本設計書を入力として、詳細設計書を作成し、モックアップ生成とテスト設計までを一貫して行うワークフロー。
入力
$ARGUMENTS（基本設計書のパス）
全体フロー
| Phase | 名称 | 内容 |
|---|---|---|
| 0 | ドキュメント計画 | 機能分解、ドキュメント一覧作成、ユーザー確認 |
| 0.5 | 影響分析 | 既存設計書・Issue・コードとの整合性確認（追加仕様時） |
| 1 | 設計書作成 | 詳細/BE/FE/画面/共通設計書の作成 |
| 1.5 | 検証 & モックアップ | ASCII禁止チェック、HTML作成、スクリーンショット |
| 2 | 品質保証ループ | detailed-design-reviewer によるレビュー（9点以上） |
| 2.5 | ユーザー承認 | approval-gate skill |
| 3 | 成果物作成 | テスト項目書、Epic/子Issue作成、Sub-issue連携 |
Phase規約:
workflow-phase-conventionskill を参照
Phase 0: ドキュメント計画
- 基本設計書を分析し、必要なサブ機能とドキュメントを特定
- 機能タイプに応じて必須ドキュメントを判定（下表参照）
- ドキュメント一覧をユーザーに提示し承認を得る
機能タイプ別 必須設計書
| 機能タイプ | 詳細設計書 | BE | FE | 画面設計書 |
|---|---|---|---|---|
| 画面あり機能 | O | O | O | O |
| API専用機能 | O | O | - | - |
| バッチ処理 | O | O | - | - |
共通設計書（機能群ごとに1つ）
| 設計書 | 必須 |
|---|---|
| データベース設計書.md | O |
| インフラ設計書.md | O |
| セキュリティ設計書.md | O |
Phase 0.5: 影響分析【追加仕様時】
トリガー: 既存の詳細設計書・Issue・コードが存在する場合
| チェック項目 | 確認内容 |
|---|---|
| API互換性 | 既存APIシグネチャを破壊しないか |
| 型定義互換性 | 既存の型定義と矛盾しないか |
| 依存Issue | 新規Issueが既存Issueに依存するか |
| 既存モジュール | src/ のどのファイルを変更するか |
ユーザー確認オプション: 1. 続行 / 2. 調整 / 3. 中断（番号選択）
Phase 1: 設計書作成
detailed-design-writer エージェントが各サブ機能に対して設計書を作成。
テンプレート:
detailed-design-templatesskill を参照
Phase 1.5: 検証 & モックアップ
ASCII禁止チェック（BLOCKING）
grep -r -l '┌\|┐\|└\|┘\|│\|─' docs/designs/detailed/{機能名}/**/画面設計書.md
# → 0件であること
モックアップ生成
ツール:
wireframe-generatorskill を使用
- 画面設計書から Wireframe DSL を生成
bun run generate.tsでmockup.html等を生成- Playwrightでスクリーンショット撮影
- 画面設計書に画像埋め込み
生成対象:
mockup.html(Desktop)mockup-mobile.html(Mobile, 固定幅375px)mockup-error.html
Phase 2: 品質保証ループ
| 条件 | アクション |
|---|---|
| スコア >= 9 & FE設計書あり | Phase 2.5へ |
| スコア < 9 | Phase 1に戻り修正（最大3回） |
| スコア悪化 | 即時中断 |
Phase 2.5: ユーザー承認ゲート
共通仕様:
approval-gateskill を参照
Phase 3: 成果物作成 & Issue化
⚠️ 責任分離（重複防止）
| ステップ | 担当 | 成果物 | 制約 |
|---|---|---|---|
| 3.1 テスト項目書作成 | test-spec-writer | .md ファイルのみ | Issue作成禁止 |
| 3.2 Epic Issue作成 | メインエージェント | GitHub Issue | 重複チェック必須 |
| 3.3 子Issue作成 | メインエージェント | GitHub Issue | 重複チェック必須 |
| 3.4 ドキュメントIssue | メインエージェント | GitHub Issue | 重複チェック必須 |
| 3.5 Sub-issue連携 | メインエージェント | GraphQL API | - |
Issue粒度ルール
| 制約 | 上限 |
|---|---|
| コード量 | 200行以下 |
| ファイル数 | 1-3ファイル |
| 責務 | 単一責務 |
作成フロー
Step 3.1: テスト項目書作成
test-spec-writer エージェントに以下を指示：
MUST DO:
- テスト項目書を {出力パス} に作成する
- 設計書のテスト観点を網羅する
MUST NOT DO:
- GitHub Issue を作成しない（Issue作成は後続ステップで行う）
- gh コマンドを実行しない
- 設計書内の TASK-XXX を Issue 化しない
Step 3.2-3.4: Issue作成（重複チェック必須）
# Issue作成前に既存Issueを確認
gh issue list --repo $REPO --search "{機能ID}" --json number,title
# 重複がなければ作成
gh issue create --title "..." --body "..."
Step 3.5: Sub-issue連携
GraphQL API:
github-graphql-apiskill を参照
テンプレート:
detailed-design-templatesskill を参照
チェックリスト
Phase 1 完了条件
- 全サブ機能に
詳細設計書.mdが存在 - 全サブ機能に
バックエンド設計書.mdが存在 - 画面機能に
画面設計書.mdとフロントエンド設計書.mdが存在 - 共通フォルダに DB/インフラ/セキュリティ設計書が存在
Phase 1.5 完了条件
- ASCII罫線チェック: 0件
- 全画面に mockup.html / mockup-mobile.html / mockup-error.html が存在
Phase 3 完了条件
- Epic Issueが作成されている
- 各子Issueが200行以下・3ファイル以下
- 依存関係がMermaid形式で記述されている
- 子IssueがEpicのSub-issueとして登録されている
- ドキュメント更新IssueがSub-issueとして登録されている
Phase 3.5: 次ステップ選択【必須】
共通仕様・出力形式:
approval-gateskill の「ワークフロー完了後の次ステップ選択」を参照
| 項目 | 値 |
|---|---|
| ワークフロー名 | 詳細設計 |
| 次ワークフロー | 実装フェーズ（TDD推奨） |
| 追加成果物 | Epic Issue, 子Issue群 |
サーキットブレーカー
| 状況 | アクション |
|---|---|
| モックアップ生成失敗 | placeholder.png を置いて続行、警告を残す |
| FE設計書欠落 | Phase 3で検出してPhase 1に戻る |
| レビュー3回失敗 | 中断、ユーザーにエスカレーション |
参考スキル
| スキル | 用途 |
|---|---|
detailed-design-templates skill | 設計書・Issueテンプレート |
approval-gate skill | ユーザー承認ゲート |
workflow-phase-convention skill | Phase命名規約 |
github-graphql-api skill | Sub-issue登録 |
design-document-types skill | 設計書タイプ判定 |
wireframe-generator skill | Phase 1.5 モックアップ生成 |
変更履歴
| バージョン | 変更内容 |
|---|---|
| v2.10 | Phase 3の責任分離明確化（Issue重複作成防止）、test-spec-writerへのMUST NOT DO追加 |
| v2.9 | ドキュメント更新Issue自動作成 |
| v2.8 | Sub-issue登録をGraphQL APIに変更 |
| v2.7 | Sub-issue連携の自動化 |
| v2.6 | 既存システム影響分析の追加 |
| v2.5 | ASCII自動検証の追加 |
| v2.4 | ドキュメント計画フェーズ追加 |
| v2.3 | 画面設計書からASCII禁止 |
| v2.2 | フロントエンド設計書必須化 |