Screen Spec Generator

画面定義書ジェネレーター スキル

このスキルは、Flutterプロジェクトにおける画面定義書の作成環境をセットアップし、個別の画面定義書を生成・更新する機能を提供します。

発動トリガー

以下のような発言で発動します：

• 「画面定義書を作成したい」「screen specを生成」「画面仕様書を書きたい」
• 「画面定義書の環境をセットアップ」「screen specを導入したい」
• 「〇〇画面の定義書を作って」「〇〇ページのspec」
• 「画面の仕様をドキュメント化したい」
• 「画面定義書を更新して」「定義書を最新化」

機能概要

このスキルは以下を行います： 1. プロジェクト構造を自動解析して確認 2. 必要なセクションを会話で選択 3. テンプレートとカスタムコマンドを生成 4. 個別の画面定義書を生成 5. 既存の画面定義書を差分検出して更新

重要: 会話の進め方

各ステップで必ずユーザーの回答を待ってから次のステップに進むこと。

• ステップ1で質問したら、ユーザーの回答を待つ
• ユーザーが回答したら、次のステップに進む
• 複数の質問を一度にしない

これにより、ユーザーが混乱せず、段階的に設定を進められます。

---

動作モード

このスキルには3つの動作モードがあります：

モード1: 初期セットアップ（環境が未構築の場合）

プロジェクトに docs/screen_specs/template.md が存在しない場合、セットアップモードで動作します。

モード2: 画面定義書生成（環境構築済み、定義書未作成の場合）

プロジェクトに docs/screen_specs/template.md が存在し、対象画面の定義書が存在しない場合、新規生成モードで動作します。

モード3: 画面定義書更新（定義書が既に存在する場合）

対象画面の定義書が既に存在する場合、更新モードで動作します。コードを再解析し、差分を検出してユーザーに提示します。

---

モード1: 初期セットアップの手順

ステップ1: プロジェクト解析

まず、プロジェクトの構造を解析します。

CLAUDE.md がある場合

1. CLAUDE.md を読み込み、以下の情報を取得：

• フレームワーク（Flutter）
• 状態管理（Riverpod, BLoC, Provider等）
• ルーティングライブラリ（auto_route, go_router等）
• アーキテクチャパターン

2. 具体的なパス構造を自動解析：

• UI層のパス（lib/ui/, lib/presentation/ など）
• ViewModel/Stateのパス
• ルーターファイルの場所
• API定義の場所

3. 解析結果を簡潔に確認：

   「CLAUDE.mdを確認しました。Flutter + Riverpod + auto_route のプロジェクトですね。

   プロジェクト構造を解析したところ、以下のようになっています：
   - UI層: lib/ui/{module}/widgets/
   - ViewModel: lib/ui/{module}/view_models/
   - ルーター: lib/routing/routes/app_router.dart

   この認識で合っていますか？」

4. ここでユーザーの回答を待つ。次のステップに進まない。

CLAUDE.md がない場合

1. pubspec.yaml を読み込み、以下を検出：

• フレームワーク（flutter SDK）
• 状態管理（flutter_riverpod, flutter_bloc, provider等）
• ルーティング（auto_route, go_router等）
• HTTP通信（dio, retrofit, http等）

2. ディレクトリ構造を解析：

• UI層のパス（lib/ui/, lib/presentation/, lib/features/ など）
• ルーターファイル（router.dart）
• API定義（api.dart）

3. 検出結果をすべてユーザーに確認：

   「画面定義書の作成をお手伝いします。
   プロジェクトの構造を解析しました。

   pubspec.yaml から以下を検出しました：
   - フレームワーク: Flutter
   - 状態管理: flutter_riverpod
   - ルーティング: auto_route

   ディレクトリ構造から以下を推測しました：
   - UI層: lib/ui/{module}/widgets/
   - ViewModel: lib/ui/{module}/view_models/
   - ルーター: lib/routing/routes/app_router.dart

   この認識で合っていますか？修正点があれば教えてください。」

4. ここでユーザーの回答を待つ。次のステップに進まない。

ステップ2: セクション選択

ステップ1でユーザーが「はい」「OK」などと回答したら、このステップに進む。

画面定義書に含めるセクションを会話で選択します。

「では、画面定義書に含めるセクションを選びましょう。
デフォルトは以下の通りです：

1. ✅ 基本情報（必須）- 画面ID、画面名、ファイルパス、最終更新日
2. ✅ スクリーンショット - 画面キャプチャの配置領域
3. ✅ 表示項目 - 静的な表示要素の一覧
4. ✅ イベント項目 - ユーザー操作によるイベント
5. ⬜ 本画面遷移時イベント - 画面表示時の自動イベント
6. ⬜ 処理フロー - API通信等の詳細フロー
7. ✅ 備考 - 特記事項

変更したい項目はありますか？」

ここでユーザーの回答を待つ。次のステップに進まない。

ステップ3: カスタマイズ確認

ステップ2でユーザーが回答したら、このステップに進む。

「他に追加したいセクションや、テーブルの列をカスタマイズしたい点はありますか？

例：
- イベント項目に analytics 列を追加
- 表示項目にデザイントークン列を追加
- 独自のセクションを追加
」

ここでユーザーの回答を待つ。次のステップに進まない。

ステップ4: ファイル生成

ステップ3でユーザーが回答したら、このステップに進む。

確認が完了したら、以下のファイルを生成します：

1. .claude/commands/screen-spec.md - カスタムコマンド 2. docs/screen_specs/template.md - テンプレート 3. docs/screen_specs/README.md - 使い方ガイド

「以下のファイルを生成しました：
- .claude/commands/screen-spec.md
- docs/screen_specs/template.md
- docs/screen_specs/README.md

これで `/screen-spec lib/ui/xxx/widgets/xxx_page.dart` で
画面定義書を生成できるようになりました。

是非、実際に1つ画面定義書を作成してみてください。
作成後、修正点があったら教えてください。」

---

モード2: 画面定義書生成の手順

前提条件

• docs/screen_specs/template.md が存在すること
• .claude/commands/screen-spec.md が存在すること
• 対象画面の定義書が存在しないこと

生成方法

ユーザーが以下のように発言した場合：

• 「〇〇画面の定義書を作って」
• 「lib/ui/xxx/widgets/xxx_page.dart の画面定義書を生成して」

1. 対象ファイルを特定 2. docs/screen_specs/template.md を読み込み 3. .claude/commands/screen-spec.md の手順に従って生成

---

モード3: 画面定義書更新の手順

前提条件

• 対象画面の定義書が既に存在すること

更新方法

ユーザーが以下のように発言した場合：

• 「〇〇画面の定義書を更新して」
• /screen-spec lib/ui/xxx/widgets/xxx_page.dart（既存ファイルに対して）

1. 既存の定義書をパース 2. コードを再解析 3. 差分を検出（追加・削除・変更） 4. 差分をユーザーに提示 5. 確認後、定義書を更新 6. HTML版も同期更新

強制新規作成

既存の定義書を無視して新規作成したい場合：

/screen-spec lib/ui/xxx/widgets/xxx_page.dart --new

---

テンプレートファイルの参照

セクション別テンプレートは以下を参照：

• 基本テンプレート: templates/base_template.md
• 生成コマンドテンプレート: templates/screen_spec_command.md
• 表示項目セクション: templates/sections/display_items.md
• イベント項目セクション: templates/sections/event_items.md
• 本画面遷移時イベントセクション: templates/sections/navigation_events.md
• 処理フローセクション: templates/sections/process_flow.md

---

注意事項

• 既存ファイルを上書きする前に必ずユーザーに確認すること
• プロジェクト固有の設定（辞書DB等）は汎用スキルでは扱わない
• 生成される定義書は日本語で出力
• 更新モードでは差分を必ずユーザーに提示し、確認を取ること

Screen Spec Generator

Flutterプロジェクトの画面定義書を作成・管理するスキルです。プロジェクト構造を自動解析し、会話形式でテンプレートをカスタマイズします。

主な機能

• プロジェクト構造の自動解析（CLAUDE.md対応）
• セクション選択による柔軟なテンプレート作成
• カスタムコマンド（/screen-spec）の自動生成
• 個別画面の定義書自動生成
• 既存定義書の差分検出と更新

使い方

初期セットアップ

# Claude Codeで以下を発言
"画面定義書を作成したい"

スキルがプロジェクト構造を解析し、会話形式でセットアップを進めます。

画面定義書の生成

セットアップ完了後、カスタムコマンドで個別の画面定義書を生成できます：

/screen-spec lib/ui/mypage/widgets/mypage_page.dart

画面定義書の更新

既存の定義書がある場合、差分を検出して更新します：

/screen-spec lib/ui/mypage/widgets/mypage_page.dart

強制的に新規作成したい場合：

/screen-spec lib/ui/mypage/widgets/mypage_page.dart --new

使用例

User: "画面定義書を作成したい"
Assistant: "CLAUDE.mdを確認しました。Flutter + Riverpod + auto_route のプロジェクトですね。
           この認識で合っていますか？"

User: "はい"
Assistant: "では、画面定義書に含めるセクションを選びましょう。
           デフォルトは以下の通りです：

           1. ✅ 基本情報（必須）
           2. ✅ スクリーンショット
           3. ✅ 表示項目
           4. ✅ イベント項目
           5. ⬜ 本画面遷移時イベント
           6. ⬜ 処理フロー
           7. ✅ 備考

           変更したい項目はありますか？"

生成されるファイル

セットアップ完了後、以下のファイルが生成されます：

• .claude/commands/screen-spec.md - カスタムコマンド
• docs/screen_specs/template.md - テンプレート
• docs/screen_specs/README.md - 使い方ガイド

カスタマイズ可能なセクション

<style> table { width: 100%; } </style>

画面定義書: {画面名}

基本情報

• 画面ID: {画面を識別するID}
• 画面名: {画面の名称}
• ファイルパス: {ファイルパス}
• 最終更新日: {YYYY-MM-DD}

<!-- SECTION: screenshot -->

画面スクリーンショット

<!-- 単一画像の場合 -->

<!-- 複数画像の場合（最大4列、5枚以上は行を追加）

-->

<!-- 縦長画面の分割表示（2スクロール分以上の画面）

通常状態

{バリエーション名}（{該当部分}）

--> <!-- /SECTION: screenshot -->

<!-- SECTION: display_items -->

表示項目

<!-- /SECTION: display_items -->

<!-- SECTION: event_items -->

イベント項目

<!-- /SECTION: event_items -->

<!-- SECTION: navigation_events -->

本画面遷移時のイベント

<!-- /SECTION: navigation_events -->

<!-- SECTION: process_flow -->

処理フロー

このセクションでは、API通信や状態変更を伴う主要な処理のフローを記載します。

{処理名}

1. {ステップ1} 2. {ステップ2} 3. 成功時: {成功時の動作} 4. 失敗時: {失敗時の動作} <!-- /SECTION: process_flow -->

<!-- SECTION: remarks -->

備考

画面の特徴

{画面固有の特徴を記載}

• 例: タブ構成、特殊なUI要素、認証状態による表示切り替えなど

その他の特記事項

{その他に記載すべき情報があれば追加} <!-- /SECTION: remarks -->

---

ファイル配置ガイド

このテンプレートを使用する際は、以下のようなディレクトリ構造で管理してください：

docs/
└── screen_specs/
    ├── template.md  # このファイル
    ├── {module_name}/  # 例: map, reservation, notification など
    │   ├── documents/
    │   │   └── {screen_name}_page.md  # 実際の画面定義書
    │   └── screenshots/
    │       └── {screen_name}_page/  # 画面ごとのスクリーンショット
    │           ├── overview.png  # 画面全体
    │           └── state_example.png  # 特定の状態

記入のヒント

スクリーンショット

スクリーンショットはテーブル形式で記載します。ヘッダー行にキャプション、データ行に画像を配置します。

単一画像の場合

| 画面全体 |
|:--:|
| <img src="../screenshots/{screen_name}_page/overview.png" alt="画面全体" width="300"> |

• width="300" で幅を300pxに指定
• キャプションは「画面全体」をデフォルトとする

複数画像の場合（最大4列）

| 通常状態 | ログイン後 | エラー時 |
|:--:|:--:|:--:|
| <img src="..." width="250"> | <img src="..." width="250"> | <img src="..." width="250"> |

• 複数画像の場合は width="250" 推奨
• 最大4列まで横並び可能
• 5枚以上の場合は行を追加して対応

縦長画面の分割表示（2スクロール分以上の画面）

縦に長い画面は、分割して横に並べて表示します。

キャプションの命名:

• 優先: 画面の内容に基づいた名前（例：「ヘッダー部」「クルマ情報部」「アクション部」）
• 代替: 位置ベースの名前（「上部」「中部」「下部」）

通常状態の分割表示:

### 通常状態

| ヘッダー部 | 詳細情報部 | アクション部 |
|:--:|:--:|:--:|
| <img src="..." width="250"> | <img src="..." width="250"> | <img src="..." width="250"> |

バリエーションがある場合（通常状態の下にセクションを追加）:

### エラー時（アクション部）

| エラー表示 |
|:--:|
| <img src="..." width="300"> |

表示項目テーブル

テキスト取得元

• APIレスポンスやアプリ内保持データの場合: 「アプリ内保持: {API名} APIから取得した{説明}（{フィールドパス}から抽出）」
• API名はPascalCase形式（例: GetUserInfo, Login, RetrieveList）
• 例: 「アプリ内保持: Login APIから取得したユーザー名（output.user.nameから抽出）」
• 固定値の場合は「固定値」または「ハードコード」
• その他の場合は「-」

イベント項目テーブル

遷移先

• 遷移先の画面名とファイル名を記載
• 形式: 「画面名<br>(ファイル名.dart)」
• 遷移しない場合は「-」または空欄

備考

• 重要: 非エンジニア向けに分かりやすく記載
• 技術的なメソッド名やコードは避け、一般的な言葉で説明

処理フロー

いつ記載すべきか

• API通信を伴う処理
• 3ステップ以上の処理
• 成功と失敗で異なる動作をする処理
• エラーハンドリングが重要な処理

記載方法

• 見出しは #### (レベル4) を使用
• 番号付きリストで手順を記載
• 成功時 と 失敗時 を太字で明示

画面定義書作成コマンド

プロンプト

あなたはFlutterアプリの画面定義書作成の専門家です。指定された画面ファイルから情報を自動抽出し、docs/screen_specs/template.mdの形式に従った高品質な画面定義書を作成してください。

入力

画面ファイルパス: $ARGUMENTS

※パラメータが指定されていない場合は、画面ファイルのパスを尋ねてください。 ※2つ目のパラメータとしてスクリーンショットのパスが指定されている場合は、それも処理に含めてください。 ※--new オプションが指定されている場合は、既存の定義書を無視して新規作成します。

実行手順

ステップ0: モード判定

1. 入力ファイルパスからモジュール名と画面名を抽出 2. 出力先パスを算出: docs/screen_specs/{module}/documents/{screen_name}.md 3. 出力先ファイルの存在を確認:

• 存在しない場合 → 新規作成モード（ステップ1へ）
• 存在する場合 → 更新モード（ステップU1へ）
• `--new` オプションあり → 強制的に新規作成モード（ステップ1へ）

---

新規作成モード

ステップ1: ファイル構造の分析と検証

1. 入力ファイルパスを検証（存在確認、形式確認） 2. モジュール名と画面名を抽出

• 例: lib/ui/mypage/widgets/mypage_page.dart → module: mypage, screen_name: mypage_page

3. 関連ファイルを特定:

• ViewModel: {viewmodel_pattern}
• State: {state_pattern}
• Components: {components_pattern}

4. 出力先ディレクトリを決定:

• Markdown: docs/screen_specs/{module}/documents/{screen_name}.md
• HTML: docs/screen_specs/{module}/documents/{screen_name}.html
• スクリーンショット: docs/screen_specs/{module}/screenshots/{screen_name}/

ステップ2: コード解析による情報抽出

以下の情報を実装コードから抽出してください（推測は厳禁）:

2.1 基本情報

• 画面ID: クラス名から抽出（例: MyPagePage）
• 画面名: 日本語の画面名（コメントやドキュメントから推測、不明な場合は英語名をそのまま使用）
• ファイルパス: 入力パス
• 最終更新日: 今日の日付（YYYY-MM-DD形式）

2.2 表示項目の抽出

Pageファイルとコンポーネントを読み込み、以下を抽出:

• テキスト要素: Text() ウィジェットの内容
• 表示条件: if 文、Visibility、Opacity などによる条件分岐
• データソース:
• APIレスポンス: 「アプリ内保持: {API名} APIから取得した{説明}（{フィールドパス}から抽出）」
• API名はPascalCase形式（先頭大文字）で記載
• 固定値: 「固定値」または「ハードコード」
• その他: 「-」

2.3 イベント項目の抽出

以下のパターンを検索:

• 画面遷移:
• context.router.push(), Navigator.push(), context.go() 等
• ルート定義ファイルからファイル名を取得
• 形式: "画面名<br>(ファイル名.dart)"

• API呼び出し:
• ViewModelメソッドを特定 → UseCaseを追跡 → APIメソッドを確認
• API名はPascalCase形式（先頭大文字）で記載

• アクション内容:
• 非エンジニア向けに簡潔に記述
• 処理フローセクションに詳細がある場合は参照リンクを追加

• 備考:
• 非エンジニア向けの言葉で補足情報を記載
• 技術的なメソッド名、URL、実装詳細は記載しない
• 表示条件、重要な動作の補足のみ記載

2.4 本画面遷移時のイベント（オプション）

Pageファイルのbuildメソッドやinitメソッドを確認:

• 初期化処理: initState(), useEffect(), ref.listen() 等
• データ取得: 画面表示時に自動的に呼ばれるAPI

2.5 処理フローの抽出（オプション）

対象: API通信を伴う処理、3ステップ以上の処理、try-catch文を含む処理

1. try-catch文を含むメソッドを検索 2. 各メソッドについて:

• 成功時の処理（tryブロック内）
• 失敗時の処理（catchブロック内）
• 重要: エラー時の画面遷移、状態のクリア処理を正確に記載

ステップ3: ドキュメント生成

3.1 ディレクトリ作成

mkdir -p docs/screen_specs/{module}/documents
mkdir -p docs/screen_specs/{module}/screenshots/{screen_name}

※ Claude Codeの場合は、Bashコマンドではなく専用ツール（Write等）の使用を推奨します。

3.2 Markdown生成

docs/screen_specs/template.mdの構造を厳密に従い、セクションを順次生成

3.3 スクリーンショット処理

• パラメータで渡された場合: 自動的に docs/screen_specs/{module}/screenshots/{screen_name}/ にコピー
• 会話中に指定された場合: 指示に従って配置
• 指定がない場合: プレースホルダーを設置し、手動配置の案内を表示

スクリーンショット受け取り時の対話確認:

スクリーンショットを受け取った際は、以下の点をユーザーに確認してください：

1. 分割表示の確認: 「このスクリーンショットは縦長画面のため、分割して横に並べて表示しますか？」 2. 分割数の確認: 分割する場合、「何分割にしますか？（例: 2分割、3分割）」 3. キャプションの確認: 「各部分のキャプション名を指定してください（例: ヘッダー部、詳細情報部、アクション部）。指定がない場合は上部・中部・下部を使用します。」 4. バリエーションの確認: 「他にバリエーション（エラー時、ローディング時など）のスクリーンショットはありますか？」

※ユーザーが事前に「分割してください」等の指示を出している場合は、確認をスキップして指示に従ってください。

3.4 HTML生成（オプション）

Markdownファイルと同じ内容をHTML形式で出力

ステップ4: 検証と出力

必須項目チェック:

• [ ] 基本情報の完全性
• [ ] 表示項目最低1行
• [ ] イベント項目最低1行

確認が必要な項目のリスト化:

• API名の確認が必要な項目
• 複雑な表示条件

出力フォーマット:

✅ 画面定義書を生成しました

【生成ファイル】
- Markdown: docs/screen_specs/{module}/documents/{screen_name}.md
- スクリーンショット: docs/screen_specs/{module}/screenshots/{screen_name}/

【抽出情報サマリー】
- 表示項目: XX件
- イベント項目: XX件

【確認が必要な項目】
- 表示項目 #X: XXXを確認してください
- イベント項目 #X: XXを確認してください

【次のステップ】
1. スクリーンショットを追加（未配置の場合）
2. 確認が必要な項目を手動で修正

---

更新モード

既存の画面定義書がある場合に、コードの変更を検出して差分を反映します。

ステップU1: 既存定義書のパース

1. 既存の定義書ファイルを読み込み 2. 各セクションの内容をパース:

• 表示項目テーブル
• イベント項目テーブル
• 本画面遷移時のイベントテーブル
• 処理フローセクション

ステップU2: コード再解析

新規作成モードのステップ2と同様にコードを解析し、最新の情報を抽出

ステップU3: 差分検出

既存定義書と再解析結果を比較し、以下の差分を検出:

• 表示項目:
• 追加された項目（コードにあるが定義書にない）
• 削除された項目（定義書にあるがコードにない）
• 変更された項目（要素名は同じだが内容が異なる）

• イベント項目:
• 追加されたイベント
• 削除されたイベント
• 変更されたイベント

• 処理フロー:
• 新規追加されたフロー
• 削除されたフロー

ステップU4: 差分提示

検出した差分をユーザーに分かりやすく提示:

既存の画面定義書を検出しました。更新モードで実行します。

【差分サマリー】
- 表示項目: 追加X件、削除X件、変更X件
- イベント項目: 追加X件、削除X件、変更X件
- 処理フロー: 追加X件、削除X件

【追加された表示項目】
- {要素名}（{表示条件}）

【削除された表示項目】
- {要素名}

【追加されたイベント】
- {トリガー名}: {アクション内容}

この差分を定義書に反映しますか？

ステップU5: 定義書更新

ユーザーの確認後、以下を実行:

1. 追加項目を適切な位置に挿入 2. 削除項目をテーブルから除去 3. 変更項目を更新 4. 最終更新日を今日の日付に更新

ステップU6: HTML同期更新

Markdownを更新した場合、対応するHTMLファイルも同期更新

ステップU7: 完了レポート

✅ 画面定義書を更新しました

【更新ファイル】
- Markdown: docs/screen_specs/{module}/documents/{screen_name}.md
- HTML: docs/screen_specs/{module}/documents/{screen_name}.html

【更新内容】
- 表示項目: 追加X件、削除X件
- イベント項目: 追加X件、削除X件
- 処理フロー: 追加X件
- 最終更新日を更新

【確認が必要な項目】
- {確認事項}

---

制約

1. 実装コードを必ず確認してから記述（推測は絶対に禁止） 2. template.mdの形式を厳密に守る（セクション構成、テーブルカラム、形式） 3. 備考は非エンジニア向けの言葉で記述（技術用語、メソッド名、URLは避ける） 4. API名はPascalCase形式で記載 5. 日本語で出力 6. エラー時の挙動は実装コードを確認して正確に記載 7. 高品質を目指す: できる限り完全な情報を抽出し、手動修正が最小限になるよう努力

エラーハンドリング

実行パターン

1. 新規作成: /screen-spec lib/ui/mypage/widgets/mypage_page.dart 2. スクリーンショット付き: /screen-spec lib/ui/mypage/widgets/mypage_page.dart ~/Desktop/screenshot.png 3. 強制新規作成: /screen-spec lib/ui/mypage/widgets/mypage_page.dart --new 4. 対話形式: /screen-spec のみで実行し、ファイルパスの入力を促す

表示項目セクション

基本構造

## 表示項目

| 番号 | 要素名 | 表示条件 | テキスト取得元 | 備考 |
|------|--------|---------|---------------|------|
| 1    |        |         |               |      |

列の説明

要素名

• 画面に表示される要素の名称を記載
• 例: 「予約ボタン」「ステーション名」「インフォメーションタブ」

表示条件

• 要素が表示される条件を記載
• 例: 「常に表示」「ログイン済みの場合のみ」「予約中の場合のみ」
• コードパターン:
• if (user.isLoggedIn) → 「ログイン済みの場合のみ」
• Visibility(visible: isEnabled) → 条件に応じた記述
• 条件なし → 「常に表示」

テキスト取得元

• テキストの取得元を記載
• パターン:
• APIレスポンス: 「アプリ内保持: {API名} APIから取得した{説明}（{フィールドパス}から抽出）」
• API名はPascalCase形式（例: GetUserInfo, Login, RetrieveList）
• 単一フィールドの例: 「アプリ内保持: Login APIから取得したユーザー名（output.user.nameから抽出）」
• 配列フィールドの例: 「アプリ内保持: GetMonthlyList APIから取得した年度（output.list[].monthから抽出）」
• 固定値: 「固定値」または「ハードコード」
• アイコンなど辞書や外部リソースを使用しない場合: 「-」

備考

• 補足情報を記載
• 非エンジニア向けに分かりやすく

オプション列

プロジェクトの要件に応じて追加可能な列:

analytics列

| 番号 | 要素名 | 表示条件 | テキスト取得元 | analytics | 備考 |

• 表示時に送信されるAnalyticsイベントがある場合

デザイントークン列

| 番号 | 要素名 | 表示条件 | テキスト取得元 | デザイントークン | 備考 |

• デザインシステムのトークンを記録する場合

イベント項目セクション

基本構造

## イベント項目

| 番号 | トリガー名 | 発火条件 | アクション内容 | 遷移先 | API | 備考 |
|------|----------|---------|---------------|--------|-----|------|
| 1    |          |         |               |        |     |      |

列の説明

トリガー名

• イベントのトリガーとなる操作やイベント名を記載
• 例: 「予約ボタンをタップ」「Pull-to-Refresh」「スワイプで削除」

発火条件

• イベントが発火する具体的な条件を記載
• 例: 「予約ボタンをタップした時」「リストを下方向にスワイプした時」
• 条件付きの場合: 「ログイン済みかつ予約可能な場合」

アクション内容

• イベント発火時の動作を簡潔に記載
• 例: 「予約詳細画面へ遷移」「通知データを再取得」「ローディング表示」
• 処理フローセクションに詳細がある場合は参照リンクを追加
• 例: 「ログアウト処理を実行（ログアウト処理を参照）」

遷移先

• 遷移先の画面名とファイル名を記載
• 形式: 「画面名<br>(ファイル名.dart)」
• 遷移しない場合: 「-」または空欄
• 例: 「予約詳細画面<br>(reservation_detail_page.dart)」

API

• 呼び出すAPIメソッド名を記載
• API名はPascalCase形式（例: GetUserInfo, CreateReservation）
• APIを呼ばない場合: 「-」または空欄

備考

• イベントに関する補足情報を記載
• 重要: 非エンジニア向けに分かりやすく記載してください
• 技術的なメソッド名やコードは避け、一般的な言葉で説明
• アクション内容と重複する場合は削除

記載すべき内容の例:

• 表示条件（例: 「管理者のみ表示」「会員のみ表示」）
• 重要な動作の補足（例: 「APIエラーが発生してもログアウトは継続される」）
• 特殊な挙動の説明

記載すべきでない内容の例:

• メソッド名（例: ~~「operationCode: WebOperationCodes.memberInfo」~~）
• URL（アクション内容に含まれている場合）
• 技術的な実装詳細

オプション列

プロジェクトの要件に応じて追加可能な列:

analytics@property_value列

| 番号 | トリガー名 | 発火条件 | アクション内容 | 遷移先 | API | analytics@property_value | 備考 |

• Firebase Analyticsで送信するイベント名やプロパティを記載
• 例: 「MyPagePage_LogoutButton」「ReservationPage_ConfirmButton」

確認ダイアログ列

| 番号 | トリガー名 | 発火条件 | 確認ダイアログ | アクション内容 | 遷移先 | API | 備考 |

• アクション前に確認ダイアログが表示される場合
• 例: 「ログアウトしますか？」

本画面遷移時のイベントセクション

基本構造

## 本画面遷移時のイベント

| 番号 | イベント概要 | 内容 | API | 備考 |
|------|------------|------|-----|------|
| 1    |            |      |     |      |

列の説明

イベント概要

• イベントの概要を簡潔に記載
• 例: 「ログイン状態の確認」「データの初期取得」「画面表示の記録」

内容

• イベントの詳細な内容を記載
• どのような処理が行われるかを具体的に説明
• 非エンジニア向けに分かりやすく記載
• 例: 「ログインしているユーザー情報を取得。未ログインの場合はログイン誘導画面を表示。同時に画面アクセスをAnalyticsに記録」

API

• 呼び出すAPIメソッド名を記載
• API名はPascalCase形式
• APIを呼ばない場合: 「-」または空欄
• ローカルストレージからのデータ取得の場合も「-」

備考

• 補足情報を記載
• ローカルデータ取得の場合は「ローカルデータ取得」などと明記

対象となるイベント

画面表示時に自動的に発火するイベントを記載します。ユーザー操作によるイベントは「イベント項目」に記載してください。

典型的なパターン

1. initState() / useEffect()

   @override
   void initState() {
     super.initState();
     _loadData();
   }

2. ref.listen() / ref.watch()

   ref.listen(authStateProvider, (previous, next) {
     // 認証状態の監視
   });

3. Analytics画面表示イベント

   useAnalyticsScreen(ref);  // screenName: 'MyPagePage'

4. FutureBuilder / StreamBuilder

   FutureBuilder(
     future: fetchData(),
     builder: ...
   )

オプション列

analytics@property_value列

| 番号 | イベント概要 | 内容 | API | analytics@property_value | 備考 |

• 画面表示イベントの場合、通常は画面名を記載
• 例: 「MyPagePage」「ReservationDetailPage」

処理フローセクション

基本構造

## 処理フロー

このセクションでは、API通信や状態変更を伴う主要な処理のフローを記載します。

#### {処理名}

1. {ステップ1}
2. {ステップ2}
3. **成功時**: {成功時の動作}
4. **失敗時**: {失敗時の動作}

記載ルール

いつ記載すべきか

• API通信を伴う処理
• 3ステップ以上の処理
• 成功と失敗で異なる動作をする処理
• エラーハンドリングが重要な処理
• try-catch文を含む処理

記載方法

• 見出しは #### (レベル4) を使用
• 番号付きリストで手順を記載
• 成功時 と 失敗時 を太字で明示
• 非エンジニア向けに、技術用語を避けて一般的な説明を記載

重要な注意事項

• 必ず実装コードを確認する: 処理フローを記載する際は、実際の実装コード（ViewModel、UseCase、Repository等）を必ず確認
• エラー時の挙動を正確に記載: 特にエラー発生時の挙動（画面遷移の有無、状態のクリア処理など）は推測せず、コードで確認
• 例外処理の流れを追う: try-catch文やエラーハンドリングの実装を確認し、実際の動作を正確に記載
• API名を明記する: API呼び出しを含む処理では、API名を必ず明記（例: 「ログアウトAPI（Logout）を呼び出し」）

例

例1: ログアウト処理

#### ログアウト処理

1. ログアウトボタンをタップ
2. 確認ダイアログを表示
3. 「はい」を選択するとログアウトAPI（Logout）を呼び出し
4. **成功時**: ログイン画面へ自動遷移
5. **失敗時**: エラーをログに記録するが、処理は継続してログアウト状態にする

例2: データ更新処理

#### データ更新処理

1. 更新ボタンをタップ
2. ローディング表示
3. 最新データをサーバーから取得（GetUserData）
4. **成功時**:
   - 画面にデータを反映
   - 更新成功メッセージを表示
5. **失敗時**:
   - 通信エラーダイアログを表示
   - リトライ可能

例3: 複数ステップの処理

#### 予約確定処理

1. 「予約を確定する」ボタンをタップ
2. 入力内容のバリデーション
3. バリデーションエラーがある場合はエラーメッセージを表示して終了
4. 確認ダイアログを表示
5. 「確定」を選択すると予約API（CreateReservation）を呼び出し
6. **成功時**:
   - 予約完了画面へ遷移
   - 予約完了のプッシュ通知を登録
7. **失敗時**:
   - エラーダイアログを表示
   - 入力画面に留まり、リトライ可能

シンプルな処理の場合

シンプルな画面遷移のみの場合は、イベント項目テーブルだけで十分です。処理フローセクションは、複雑な処理がある場合のみ記載してください。