Dev Screen Spec

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 の存在で自動判定する（ユーザー質問不要）:

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

サブエージェントは 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: 画面構成分析結果

信号機

from-plan モードでの信号機基準:

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

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>

### 生成ファイル一覧

| ファイル | 画面名 | パス | グループ | 項目数 | 🔵 | 🟡 | 🔴 |
|---------|--------|------|---------|--------|-----|-----|-----|
| _index.md | 画面一覧 | - | - | - | - | - | - |
| login.md | ログイン | /login | auth | 4 | 3 | 1 | 0 |
| ...

### ⚠️ 🔴 警告
以下の項目はソースコードに根拠がなく、AI が推論で追加しました。内容を確認してください:
- <ファイル名> <セクション>: <項目名>

### ⚠️ 到達不能画面
- <画面ID>: いずれの遷移フローにも含まれていません

### 次のステップ
- 画面仕様の内容を確認してください
- 差分更新: ソースコード変更後に `/dev-screen-spec` を再実行
- テスト計画生成: `/dev-webtest-plan` で画面仕様を入力としてテスト計画を生成

5. 中間ファイルをクリーンアップする:

   rm -rf "$(git rev-parse --show-toplevel)/tmp/screen-spec/"

ワークフロー: 差分更新モード

Phase 1: 変更検知（メイン）

1. docs/dev/screen-specs/_index.md の last_synced_commit を Grep で取得する
2. last_synced_commit が現在の git history に存在するか確認する:

   git cat-file -t <last_synced_commit>

   存在しない場合 → ユーザーに「初回生成モードで再生成」を提案して終了
3. git diff --name-only <last_synced_commit>..HEAD で変更ファイル一覧を取得する
4. 変更ファイルが50件を超える場合 → ユーザーに確認後、初回生成モードにフォールバック
5. 各画面の related_files を Grep で取得し、変更ファイル一覧と突き合わせる:

   影響判定ロジック:
   - related_files に含まれるファイルが変更されている → 影響あり
   - related_files に含まれないが、ルーティング定義が変更されている → 新画面追加の可能性
   - related_files のファイルが削除されている → 画面削除の可能性

6. 特定画面のみ更新（引数で screen-id 指定時）の場合は、その画面のみを対象にする
7. 影響画面がない場合 → 「変更なし」を表示して終了
8. 影響画面の一覧を表示する
9. 中間ファイルディレクトリを作成する:

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

Phase 1.5: from-plan 画面のソース同期判定（メイン）

1. source: from-plan かつ last_synced_commit: null の画面を Grep で検出する
2. 該当画面がある場合: a. 各画面の related_files が空なので、ルーティング情報から対応するソースファイルを特定する b. ソースファイルが見つかった画面について、general-purpose サブエージェントで分析（画面数分並列）:
   • 既存の画面仕様（from-plan）を Read
   • ソースファイルを Read
   • 差分（from-plan の内容 vs ソースの実装）を表示用にまとめる
   • 中間ファイルに出力: tmp/screen-spec/sync-<screen_id>.md
   • マーカー: SYNC_ANALYZE_SUCCESS / SYNC_ANALYZE_FAILED c. 各画面について AskUserQuestion で解決方法を選ばせる:
   • 「ソースを採用」: ソースコードの実装状態で画面仕様を上書き
   • 「from-plan を維持」: 画面仕様はそのまま（実装が仕様と異なる場合は実装を修正すべき）
   • 「マージ」: 両方の情報を統合（サブエージェントがマージ実行） d. 選択結果に基づいて画面仕様を更新、source: from-source, last_synced_commit: HEAD に変更
3. 該当画面がない場合: 通常の差分更新フローに進む

Phase 2: 差分内容の分析（グループ単位並列サブエージェント）

影響のある画面が属するグループ単位で general-purpose サブエージェントを起動（並列）:

1. references/diff-analyze-prompt-template.md を Read で読み込む
2. テンプレートのプレースホルダーを置換する:
   • {{SCREEN_ID}} ← 画面ID
   • {{LAST_SYNCED_COMMIT}} ← last_synced_commit
   • {{RELATED_FILES}} ← その画面の related_files 一覧
   • {{EXISTING_SCREEN_SPEC_PATH}} ← 既存の画面仕様ファイルパス
   • {{TMP_DIR}} ← tmp/screen-spec/ の絶対パス
3. general-purpose サブエージェントを起動する
4. 出力のマーカーを確認する:
   • DIFF_ANALYZE_SUCCESS → Phase 3 へ
   • DIFF_ANALYZE_FAILED → エラー理由を記録

Phase 3: 画面仕様の更新（グループ単位並列サブエージェント）

グループ単位で general-purpose サブエージェントを起動（並列）:

1. references/diff-update-prompt-template.md を Read で読み込む
2. テンプレートのプレースホルダーを置換する:
   • {{SCREEN_ID}} ← 画面ID
   • {{DIFF_SUMMARY_PATH}} ← tmp/screen-spec/diff-<screen_id>.md の絶対パス
   • {{EXISTING_SCREEN_SPEC_PATH}} ← 既存の画面仕様ファイルパス
   • {{SCREEN_SPEC_FORMAT_PATH}} ← references/screen-spec-format.md の絶対パス
   • {{OUTPUT_DIR}} ← docs/dev/screen-specs/ の絶対パス
3. general-purpose サブエージェントを起動する
4. 出力のマーカーを確認する:
   • UPDATE_SCREEN_SPEC_SUCCESS → 完了
   • UPDATE_SCREEN_SPEC_FAILED → エラー理由を記録

Phase 4: 新画面・削除画面の処理（メイン）

• 新画面: ルーティング変更が検出された場合、初回生成モードの Phase 3 と同様に生成する
• 削除画面: ソースファイルが全て削除されている画面は、ユーザーに削除を確認する

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

1. _index.md を更新する:
   • 画面一覧テーブルの更新（新規追加・削除を反映）
   • グループ情報の更新
   • 画面遷移フローの更新
   • 到達不能画面チェックの再実施
   • last_synced_commit を HEAD に更新、updated_at を今日の日付に更新
2. 全更新ファイルの last_synced_commit を更新する
3. 変更サマリーを表示する:

## dev-screen-spec 完了レポート（差分更新）

### 更新概要
- 前回同期: <last_synced_commit> → 今回: <HEAD>
- 変更ファイル数: N
- 影響画面数: N

### 更新画面一覧

| 画面ID | 画面名 | 変更セクション | 変更概要 |
|--------|--------|-------------|---------|
| login | ログイン | バリデーション | パスワード最低文字数を6→8に変更 |

### 新規追加画面
- <画面ID>: <画面名>

### 削除画面
- <画面ID>: <画面名>（ユーザー確認済み）

### ⚠️ 🔴 警告
以下の項目はソースコードに根拠がなく、AI が推論で追加しました:
- <ファイル名> <セクション>: <項目名>

### ⚠️ 到達不能画面
- <画面ID>: いずれの遷移フローにも含まれていません

4. 中間ファイルをクリーンアップする:

   rm -rf "$(git rev-parse --show-toplevel)/tmp/screen-spec/"

ワークフロー: from-plan モード

Phase 0: 対象 plan の特定（メイン）

plan-name が明示指定されている場合はそのまま Phase 1 へ進む。省略されている場合は自動検出する:

1. docs/dev/screen-specs/_index.md が存在する場合: a. last_synced_commit を Grep で取得する b. 以下のコマンドで AC が変更された plan を検出する:

   git diff --name-only <last_synced_commit>..HEAD -- docs/dev/plans/*/acceptance-criteria.md

   c. 結果のパスから plan 名を抽出する（例: docs/dev/plans/auth/acceptance-criteria.md → auth）
2. _index.md が存在しない場合: a. Glob で docs/dev/plans/*/acceptance-criteria.md を取得する b. 全 plan を候補にする
3. 候補が0件 → 「対象の plan がありません」と報告して終了
4. 候補が1件 → そのまま Phase 1 へ進む
5. 候補が複数 → AskUserQuestion で選択する:

   以下の plan の acceptance-criteria.md が変更されています。対象を選んでください:
   1. auth
   2. user-management
   (all で全部、カンマ区切りで複数選択可)

6. 複数 plan が選択された場合、選択された plan を 順番に Phase 1〜5 のワークフローを繰り返す