/state-transition-analysis

description: データの状態遷移フローを包括的に分析する
allowed-tools: Read, Glob, Grep, Task, Bash, Write
argument-hint: "[対象データ名（リソース名/エンティティ名/モデル名）]"

対象データの状態遷移に関わる全ての機能を特定し、状態遷移フロー、関連データとの依存関係、リスク評価を提供します。

context

出力ディレクトリ=".dcs" カレントディレクトリ={{プロジェクトルート}} 分析ファイルリスト=[] 対象データ名="" 状態フィールド名="" 検出された状態値リスト=[]

step

• $1 がない場合、「引数に対象データ名を指定してください（例: Order, Cart, Inventory）」と言って終了する
• $1 の内容を簡潔に説明する
• AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する：

1. 対象データの種類を確認 2. 状態フィールド名を確認（自動検出も試みる） 3. 分析範囲を確認 4. 出力形式の希望を確認

• 収集した context の内容をまとめてユーザに宣言する
• step2 を実行する

step2

• 既存の出力ファイルを確認して、重複しないナンバリングを決定する
• {{出力ディレクトリ}}/{{timestamp}}_*.md を検索
• 今回の対象データ名を英語化したもの（例: "order_state", "cart_status"）を作成
• 同じ timestamp と内容で既存ファイルがある場合、末尾の連番を +1 する
• ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{データ名の英語化}}" とする
• 例: ".dcs/20251026_143000_order_state"
• 分析結果ファイルのリストを準備する（セクション別分割ファイル）
• インデックスファイル: "{{ベースディレクトリ}}/index.md"
• サマリーファイル: "{{ベースディレクトリ}}/summary.md"
• 状態遷移図ファイル: "{{ベースディレクトリ}}/diagram.md"
• 遷移表ファイル: "{{ベースディレクトリ}}/transitions.md"
• 機能別分析: "{{ベースディレクトリ}}/functions.md"
• データ依存関係: "{{ベースディレクトリ}}/dependencies.md"
• リスク評価: "{{ベースディレクトリ}}/risks.md"
• 推奨事項: "{{ベースディレクトリ}}/recommendations.md"
• すべてのファイル名を 分析ファイルリスト に追加する
• <state_transition_analysis_template> の内容を context の情報で埋めて、Task ツールで直接実行する
• subagent_type: "general-purpose"
• description: "状態遷移分析の実行"
• prompt: テンプレートの内容を context で埋めた完全なプロンプト
• Task の実行結果を受け取る
• step3 を実行する

step3

• 出力されたファイルを Read で確認する
• 深掘り内容のルール に基づいて、追加調査が必要かを判断する
• 追加調査が必要な場合：
• 追加調査の内容をリストとしてユーザに提示する
• ユーザの承認を得る
• 追加調査項目が複数ある場合、各項目に対して個別に Task ツールで追加調査を実行する
• 各項目ごとに新しい連番で追加ファイルとして保存する（例: "_2.md", "_3.md", "_4.md"）
• 各ファイル名を 分析ファイルリスト に追加する
• 再度 step3 を実行する（追加調査が不要になるまで繰り返す、最大5回）
• 追加調査が不要な場合：
• step4 を実行する

step4

• <summary_template> の内容を使って、Task ツールで最終サマリーファイルを作成する
• subagent_type: "general-purpose"
• description: "状態遷移分析 最終サマリーの作成"
• prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト
• 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md"
• 全ての分析ファイルのパスを分析回数別に整理して表示する
• 初回分析ファイル一覧（インデックス、サマリー、遷移図など）
• 追加調査ファイル一覧（該当する場合）
• 最終サマリー
• 分析完了をユーザに報告する

rules

確認ポイント

AskUserQuestion ツールを使って、以下の質問を順番に実施する：

質問1: 対象データの種類

• **質問**: 対象データはどの種類ですか？
• **header**: "データ種類"
• **options**:
• "Prismatix リソース" - YAMLで定義されたリソース（prismatix-factory/resources/）
• "Kotlinエンティティ" - バックエンドのエンティティクラス
• "TypeScript型" - フロントエンドの型定義
• "自然言語" - 概念的なデータ（具体的な実装は未特定）

質問2: 状態フィールド名

• **質問**: 状態を表すフィールド名は何ですか？（わからない場合は「自動検出」を選択）
• **header**: "状態フィールド"
• **options**:
• "status" - 一般的な status フィールド
• "state" - state フィールド
• "orderStatus" - 注文ステータス
• "自動検出" - コードから自動的に検出を試みる

質問3: 分析範囲

• **質問**: どの範囲まで分析しますか？
• **header**: "分析範囲"
• **multiSelect**: true
• **options**:
• "バックエンド" - Kotlin Spring Bootのコード
• "フロントエンド" - React/Next.jsのコード
• "BFF" - Next.js API routes
• "インターセプター" - Prismatix Factoryのインターセプター

質問4: 出力形式

• **質問**: どの出力形式を希望しますか？
• **header**: "出力形式"
• **multiSelect**: true
• **options**:
• "Mermaid図" - 状態遷移図をMermaid形式で出力
• "遷移表" - 状態遷移をテーブル形式で出力
• "フロー詳細" - 各遷移の詳細な説明
• "リスク評価" - 状態遷移に伴うリスク評価

contextとして以下を保持する

• 対象データ名
• データの種類
• 状態フィールド名
• 分析範囲
• 出力形式

ファイル名のルール

timestamp の形式

• yyyyMMddHHmmss 形式（例: 20251026143000）

データ名の英語化のルール

• 対象データ名を簡潔な英語に変換し、状態を示すサフィックスを追加
• スネークケース（snake_case）を使用
• 最大30文字程度に収める
• 例:
• "Order" → "order_state"
• "Cart" → "cart_status"
• "在庫" → "inventory_state"
• "決済" → "payment_status"

セクション別ファイル名のルール

• 分析結果は論理的なセクション単位で分割し、各セクション500行以内を目標とする
• セクション一覧:
• `index.md` - インデックス（全体概要とファイル一覧）
• `summary.md` - 分析対象とサマリー
• `diagram.md` - 状態遷移図（Mermaid形式）
• `transitions.md` - 状態遷移表
• `functions.md` - 機能別の状態遷移分析
• `dependencies.md` - 他のデータとの依存関係
• `risks.md` - リスク評価
• `recommendations.md` - 推奨事項

ファイルパスの記載ルール

• **カレントディレクトリを基準とした相対パスを使用する**
• フルパス（絶対パス）は記載しない
• 例:
• ❌ `/Users/makotan/projects/ensemble-si/backend/src/main/kotlin/...`
• ✅ `backend/src/main/kotlin/...`

状態遷移分析の観点

1. 状態値の特定

• 可能な状態値をすべて列挙する
• enum定義、定数定義、YAMLでの定義を確認
• コード内で文字列リテラルで使用されている状態値も検出

2. 遷移パターンの分類

• **正常遷移**: ビジネスフローに沿った通常の遷移
• **異常遷移**: エラーやキャンセル等の例外的な遷移
• **補正遷移**: 管理者による手動修正など
• **自動遷移**: バッチ処理やスケジューラーによる遷移

3. 遷移トリガーの特定

• APIエンドポイント呼び出し
• インターセプターの自動実行
• バッチ処理
• 外部システムからの通知
• タイムアウト等の時間ベース

4. 遷移条件の分析

• 状態遷移の前提条件（どの状態からどの状態へ遷移可能か）
• ビジネスルールによる制約
• 関連データの状態依存
• 権限チェック

5. 副作用の特定

• 状態遷移に伴う他のデータの変更
• 通知の送信（メール、プッシュ通知等）
• 外部システムへの連携
• ログ記録

リスク評価基準

以下の観点でリスクを評価する：

状態の複雑度

• 状態数が多い: リスク増加
• 遷移パターンが複雑: リスク増加
• 循環遷移がある: 要注意

データ整合性

• 複数データの状態が連動: 高リスク
• トランザクション境界が不明確: 高リスク
• ロールバック処理が未実装: 高リスク

エラーハンドリング

• 異常系の遷移が未定義: 高リスク
• リトライ処理が不適切: 中リスク
• エラー通知が不足: 中リスク

テスタビリティ

• 状態遷移のテストが不足: 中リスク
• エッジケースのテストがない: 高リスク

追加調査が必要な条件

以下の条件のいずれかに該当する場合、追加調査を提案する：

• 状態数が10個以上ある
• 循環遷移パターンが検出された
• 複数のデータの状態が密接に連動している
• 外部システムとの連携がある
• トランザクション境界が不明確
• エラーハンドリングが不十分
• テストカバレッジが低い
• ドキュメントと実装が乖離している可能性

深掘り内容のルール

調査した内容を元に、以下の観点で追加調査が必要な箇所をリストアップする：

• 複雑な遷移パターンの詳細分析
• データ整合性の検証方法
• エラーハンドリングの改善点
• テストケースの不足箇所
• パフォーマンスへの影響
• セキュリティ上の懸念点

info

<state_transition_analysis_template> あなたは状態遷移分析のエキスパートです。以下の情報に基づいて、対象データの状態遷移を包括的に分析し、セクション別に分割してファイル出力してください。

分析対象の情報

対象データ名: {{対象データ名}} データの種類: {{データの種類}} 状態フィールド名: {{状態フィールド名}} 分析範囲: {{分析範囲}} 出力形式: {{出力形式}} ベースディレクトリ: {{ベースディレクトリ}}（例: ".dcs/20251026143000_order_state"） カレントディレクトリ: {{カレントディレクトリ}}

重要な注意事項

**すべてのファイルパスは、カレントディレクトリを基準とした相対パスで記載してください。** **絶対パス（/Users/... など）は使用しないでください。** **各セクションファイルは500行以内を目標としてください。**

出力ファイル構成

分析結果は以下のセクション別ファイルに分割して出力してください：

1. **インデックスファイル**: `{{ベースディレクトリ}}/index.md`

• 全体概要と全セクションファイルへのリンク

2. **サマリーファイル**: `{{ベースディレクトリ}}/summary.md`

• 分析対象、サマリー、リスク評価

3. **状態遷移図ファイル**: `{{ベースディレクトリ}}/diagram.md`

• Mermaid形式の状態遷移図

4. **遷移表ファイル**: `{{ベースディレクトリ}}/transitions.md`

• 状態遷移の詳細な表

5. **機能別分析ファイル**: `{{ベースディレクトリ}}/functions.md`

• 各機能が行う状態遷移の詳細

6. **データ依存関係ファイル**: `{{ベースディレクトリ}}/dependencies.md`

• 他のデータとの状態依存関係

7. *