/dev-screen-spec

name: dev-screen-spec
description: This skill should be used when the user asks to "dev-screen-spec", "画面仕様を生成", "画面仕様を更新", "screen spec", "generate screen spec", "update screen spec", "画面仕様ドキュメント". ソースコードから画面仕様ドキュメントを自動生成・差分更新する。受け入れ条件から画面仕様を事前生成する from-plan モードも対応。
argument-hint: '[init|update [screen-id]|from-plan <plan-name>]'

Dev Screen Spec

ソースコードから画面仕様ドキュメント（Screen Spec）を生成・差分更新するスキル。 `docs/dev/screen-specs/` 配下に画面ごとの Markdown with frontmatter 形式で出力する。 webtest 計画の差分更新パイプラインにおいて、ソースコード変更を画面・機能単位の変更に翻訳する中間レイヤーとして機能する。

前提知識

dev-* スキルフロー内の位置

[ソースコード変更]  ← dev-impl / 手作業 / 何でも
       │
       │  git diff (last_synced_commit → HEAD)
       ▼
[dev-screen-spec]   ← 手動実行（本スキル）
       │
       │  画面仕様の差分
       ▼
[dev-webtest-plan]  ← 既存の受け入れ要件 + 画面仕様を入力に
       │
       ▼
[dev-webtest]       ← 既存のまま

引数フォーマット

/dev-screen-spec              # 自動判定（初回 or 差分更新）
/dev-screen-spec init         # 強制的に初回生成モード
/dev-screen-spec update       # 強制的に差分更新モード
/dev-screen-spec update login # 特定画面のみ更新
/dev-screen-spec from-plan              # AC変更のある plan を自動検出
/dev-screen-spec from-plan <plan-name>  # 特定の plan を明示指定

モード自動判定

`docs/dev/screen-specs/_index.md` の存在で自動判定する（ユーザー質問不要）:

| モード | 判定条件 | 特徴 | |-------|---------|------| | from-plan | 引数が `from-plan` で始まる | 受け入れ条件（AC + plan.md）から画面仕様を生成。ソースコード不要 | | 初回生成 | `_index.md` が存在しない、または引数 `init` | ソースコード全体を解析して一括生成 | | 差分更新 | `_index.md` が存在する、または引数 `update` | git diff で影響画面のみ更新 |

サブエージェント制約（重要）

サブエージェントは Task ツールを使用できない（ネスト不可のアーキテクチャ制約）。そのため:

• コード探索は Glob/Grep/Read を直接使用する
• TodoWrite は使用しない
• サブエージェントに渡すのはファイルパスのみ。サブエージェントが自分で Read する

コンテキスト管理戦略

メインコンテキストの肥大化を防ぐため、**中間ファイルとパス参照** を使用する:

• メインエージェントはファイルの全文を Read しない（パス存在確認・Grep での部分情報取得のみ）
• サブエージェントに渡すのはファイルパス。サブエージェントが自分で Read する
• Phase 間のデータ受け渡しは中間ファイル経由（`tmp/screen-spec/`）
• サブエージェントの返却はマーカー＋ファイルパス＋行数のみ

中間ファイル

tmp/screen-spec/
├── explore-routes.md          # Phase 1: ルーティング探索結果
├── explore-pages.md           # Phase 1: ページコンポーネント一覧
├── group-<group-name>.md      # Phase 3: グループサマリー（初回生成）
├── diff-<screen_id>.md        # 差分更新 Phase 2: 各画面の変更サマリー
├── sync-<screen_id>.md        # 差分更新 Phase 1.5: from-plan ソース同期分析
└── from-plan/
    └── screen-analysis.md     # from-plan Phase 2: 画面構成分析結果

信号機

| 信号 | 基準 | |------|------| | 🔵 | ソースコードから直接読み取れた情報（HTML要素、バリデーション属性、ルーティング定義等） | | 🟡 | ソースコードから推測した情報（コンポーネント名から画面名を推定、import関係からの推論等） | | 🔴 | AI推論補完（ソースに明示されていないが、一般的なWebアプリとして必要と判断した項目） |

from-plan モードでの信号機基準: | 信号 | 基準 | |------|------| | 🔵 | ACに明示されている情報 | | 🟡 | plan.md から推測した情報 | | 🔴 | AI推論補完 |

ワークフロー: 初回生成モード

Phase 1: プロジェクト分析（メイン）

1. `docs/dev/context.md` の存在を確認する。存在しない場合は `/dev-context` の実行を案内して終了する 2. `docs/dev/context.md` を Read して技術スタック（フレームワーク、言語）を把握する 3. 中間ファイルディレクトリを作成する:

   mkdir -p "$(git rev-parse --show-toplevel)/tmp/screen-spec"

4. general-purpose サブエージェントを **2つ並列** で起動する:

1a. ルーティング探索（general-purpose）

1. `references/explore-routes-prompt-template.md` を Read で読み込む 2. テンプレートのプレースホルダーを置換する:

• `{{CONTEXT_MD_PATH}}` ← `docs/dev/context.md` の絶対パス
• `{{TMP_DIR}}` ← `tmp/screen-spec/` の絶対パス

3. general-purpose サブエージェントを起動する 4. 出力のマーカーを確認する:

• `EXPLORE_ROUTES_SUCCESS` → 次へ
• `EXPLORE_ROUTES_FAILED` → エラー理由をユーザーに報告して終了

1b. ページコンポーネント探索（general-purpose）

1. `references/explore-pages-prompt-template.md` を Read で読み込む 2. テンプレートのプレースホルダーを置換する:

• `{{CONTEXT_MD_PATH}}` ← `docs/dev/context.md` の絶対パス
• `{{TMP_DIR}}` ← `tmp/screen-spec/` の絶対パス

3. general-purpose サブエージェントを起動する 4. 出力のマーカーを確認する:

• `EXPLORE_PAGES_SUCCESS` → 次へ
• `EXPLORE_PAGES_FAILED` → エラー理由をユーザーに報告して終了

Phase 2: グループ分割の設計（メイン）

1. Phase 1 の中間ファイルの「パス構造のみ」を Grep で取得する:

• `tmp/screen-spec/explore-routes.md`
• `tmp/screen-spec/explore-pages.md`

2. ルーティング情報とページコンポーネント情報を統合する 3. 画面一覧を構成する:

• 画面ID（ケバブケース）、画面名（日本語）、パス、認証要否を決定
• 各画面の related_files（対応するソースファイルパス）を決定

4. グループ案を自動生成する（URLパス構造や機能ドメインに基づく） 5. AskUserQuestion でユーザーに確認・調整する:

• 画面一覧（画面ID, 画面名, パス, グループ）
• グループ分割案
• 修正が必要ならユーザーの指示を反映

6. 画面遷移フローを設計する:

• ルーティング情報とページ間のリンク関係から遷移フローを構成
• 業務的な意味のあるフロー単位でまとめる

7. 到達不能画面チェックを実施する:

• 全画面がいずれかのフローに含まれているか検証
• 含まれていない画面があれば警告リストに追加

Phase 3: 画面仕様ファイル生成（グループ単位並列サブエージェント）

グループ単位で general-purpose サブエージェントを起動（並列）。1サブエージェントが「グループ内の全画面」を担当する:

1. `references/generate-prompt-template.md` を Read で読み込む 2. テンプレートのプレースホルダーを置換する:

• `{{GROUP_NAME}}` ← グループ名
• `{{SCREENS}}` ← グループ内の画面情報一覧（画面ID, 画面名, パス, 認証要否, related_files）
• `{{SCREEN_SPEC_FORMAT_PATH}}` ← `references/screen-spec-format.md` の絶対パス
• `{{CONTEXT_MD_PATH}}` ← `docs/dev/context.md` の絶対パス
• `{{OUTPUT_DIR}}` ← `docs/dev/screen-specs/` の絶対パス
• `{{TMP_DIR}}` ← `tmp/screen-spec/` の絶対パス

3. general-purpose サブエージェントを起動する 4. サブエージェントの作業:

• グループ内の全画面仕様ファイルを生成
• グループサマリーを中間ファイルに出力: `tmp/screen-spec/group-<group-name>.md`

5. 出力のマーカーを確認する:

• `GENERATE_SCREEN_SPEC_SUCCESS` → 完了
• `GENERATE_SCREEN_SPEC_FAILED` → エラー理由を記録

複数グループがある場合は並列で実行する（Agent ツールを複数同時起動）。

Phase 4: 完了処理（メイン）

1. グループサマリー（パス＋行数のみ）から `_index.md` を組み立てる:

• 画面一覧テーブル（Phase 2 の設計に基づく）
• グループ情報
• 画面遷移フロー（Phase 2 の設計に基づく）
• 到達不能画面チェック結果
• frontmatter: `last_synced_commit` を現在の HEAD に設定、`updated_at` を今日の日付に設定、`groups` を設定

2. `_index.md` の frontmatter にグループ情報を含める:

   ---
   last_synced_commit: abc1234
   updated_at: "2026-03-10"
   groups:
     - name: user-management
       screens: [user-list, user-detail, user-create]
     - name: auth
       screens: [login, forgot-password]
     - name: settings
       screens: [user-settings]
   ---

3. 全ファイルの `last_synced_commit` を現在の HEAD（短縮形）に設定する:

   git rev-parse --short HEAD

4. 生成結果のサマリーを表示する:

## dev-screen-spec 完了レポート（初回生成）

### 生成概要
- 画面数: N
- グループ数: N
- 生成ファイル数: N + 1（_index.md 含む）
- last_synced_commit: <commit hash>

### 生成ファイル一覧

| ファイル | 画面名 | パス | グループ | 項目数 | 🔵 | 🟡 | 🔴 |
|---------|--------|------|---------|--------|-----|--