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

モード	判定条件	特徴
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アプリとして必要と判断した項目）