/sequence-diagram-analysis

description: 機能のシーケンス図を作成する
allowed-tools: Read, Glob, Grep, Task, Bash, AskUserQuestion, Write
argument-hint: "[機能名または対象(ファイルパス/関数名/クラス名/自然言語)]"

指定された機能のシーケンス図をmermaid形式で作成します。調査結果を一時ファイルに保存し、Task で参照することでコンテキスト削減を実現します。

context

出力ディレクトリ=".dcs" カレントディレクトリ={{プロジェクトルート}} 分析ファイルリスト=[] 機能特定済み=false 対象機能=[] ベースディレクトリ="" tmpディレクトリ=""

step

• $1 がない場合、「引数に機能名または対象を指定してください（例: 注文確定処理、OrderController.confirmOrder、src/api/order など）」と言って終了する
• $1 の内容を簡潔に説明する
• step2 を実行する

step2

• $1 が具体的な機能を指していない場合（自然言語の一般的な記述、ディレクトリパスなど）:
• Grep/Glob を使って、$1 に関連する機能を調査する
• 調査結果から具体的な機能候補をリストアップする
• AskUserQuestion ツールを使って、ユーザに対象機能を選択してもらう
• **質問**: どの機能のシーケンス図を作成しますか?
• **header**: "対象機能の選択"
• **multiSelect**: true
• **options**: {{調査結果から抽出した機能リスト}}（最大10件程度）
• 選択された機能を 対象機能 に設定し、機能特定済み=true とする
• $1 が具体的な機能を指している場合（関数名、クラス名、特定のエンドポイントなど）:
• その機能を 対象機能 に設定し、機能特定済み=true とする
• 対象機能をユーザに宣言し、確認を得る
• AskUserQuestion ツールを使って以下の質問を順番に実施し、context を更新する：

1. 図に含めるシナリオを確認 2. 詳細レベルを確認 3. 除外条件の有無を確認

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

step2.5 (初期調査と一時ファイル作成)

• 既存の出力ファイルを確認して、重複しないナンバリングを決定する
• {{出力ディレクトリ}}/{{timestamp}}_* を検索
• 今回の内容を簡単に英語化したもの（例: "order_confirmation", "cart_update"）を作成
• 同じ timestamp と内容で既存ディレクトリがある場合、末尾の連番を +1 する
• ベースディレクトリを "{{出力ディレクトリ}}/{{timestamp}}_{{内容の英語化}}" とする
• 例: ".dcs/20251027_123456_order_confirmation"
• tmpディレクトリを "{{ベースディレクトリ}}/tmp" とする
• tmpディレクトリを作成する（Bash で mkdir -p）
• 対象機能に関する初期調査を Task ツールで実施し、以下の一時ファイルに結果を保存する：

調査ファイル構造

1. **コンポーネント分析**: `{{tmpディレクトリ}}/component_analysis.md`

• 関連するコンポーネント（Frontend, BFF, Backend, Database, External API）の情報
• 各コンポーネントの役割、技術スタック、主要ファイルパス（相対パス）

2. **処理フロー分析**: `{{tmpディレクトリ}}/flow_analysis.md`

• エントリーポイント情報（ファイルパス、関数名、行番号）
• 主要な処理ステップと呼び出し順序
• 処理の分岐条件
• データベースアクセスや外部API呼び出しの概要

3. **エラーハンドリング分析**: `{{tmpディレクトリ}}/error_handling.md`

• バリデーションエラーのパターン
• ビジネスロジックエラーのパターン
• システムエラー、外部API障害のハンドリング
• 認証/認可エラーのハンドリング

4. **重要ファイル抜粋**: `{{tmpディレクトリ}}/file_contents/`

• 各重要ファイルの関連部分を抜粋して保存
• ファイル名: `controller.md`, `service.md`, `repository.md` など
• 各ファイルには以下を含める:
• 元のファイルパス（相対パス）
• 関連する関数/メソッドの抜粋（最大200行程度）
• 重要なコメントやアノテーション

調査実施手順

1. Grep/Glob で対象機能に関連するファイルを特定 2. Read で主要ファイルの内容を確認（必要な部分のみ） 3. コンポーネント分析結果を `component_analysis.md` に Write 4. 処理フロー分析結果を `flow_analysis.md` に Write 5. エラーハンドリング分析結果を `error_handling.md` に Write 6. 重要ファイルの抜粋を `file_contents/*.md` に Write（各ファイル個別に） 7. 作成した調査ファイルのパスをユーザに報告

• step3 を実行する

step3

• 分析結果ファイルのリストを準備する
• インデックスファイル: "{{ベースディレクトリ}}/index.md"
• サマリーファイル: "{{ベースディレクトリ}}/summary.md"
• シーケンス図ファイル: "{{ベースディレクトリ}}/sequence_success.md" (成功パターン)
• シーケンス図ファイル: "{{ベースディレクトリ}}/sequence_error.md" (エラーパターン)
• シーケンス図ファイル: "{{ベースディレクトリ}}/sequence_exception.md" (例外パターン)
• 分析詳細ファイル: "{{ベースディレクトリ}}/details.md"
• すべてのファイル名を 分析ファイルリスト に追加する
• <sequence_diagram_template> の内容を context の情報で埋めて、Task ツールで実行する
• subagent_type: "general-purpose"
• description: "シーケンス図の作成"
• prompt: テンプレートの内容を context で埋めた完全なプロンプト
• **重要**: 調査結果ファイルのパスを渡し、Task内でReadして使用する
• Task の実行結果を受け取る
• step4 を実行する

step4

• 出力されたファイルを Read で確認する
• 深掘り内容のルール に基づいて、追加調査が必要かを判断する
• 追加調査が必要な場合：
• 追加調査の内容をリストとしてユーザに提示する
• ユーザの承認を得る
• 追加調査項目が複数ある場合、各項目に対して個別に処理する:

1. 追加調査用の一時ファイルを作成（`{{tmpディレクトリ}}/additional_N_*.md`） 2. Task ツールで追加調査を実行（調査結果ファイルのパスを渡す） 3. 各項目ごとに新しい連番で追加ファイルとして保存する（例: "2_sequence_success.md", "3_sequence_error.md"） 4. 各ファイル名を 分析ファイルリスト に追加する

• 再度 step4 を実行する（追加調査が不要になるまで繰り返す、最大5回）
• 追加調査が不要な場合：
• step5 を実行する

step5

• <summary_template> の内容を使って、Task ツールで最終サマリーファイルを作成する
• subagent_type: "general-purpose"
• description: "シーケンス図作成 最終サマリーの作成"
• prompt: サマリーテンプレートの内容を context で埋めた完全なプロンプト
• **重要**: 分析ファイルリストを渡し、Task内でReadして使用する
• 最終サマリーファイル名: "{{ベースディレクトリ}}/final_summary.md"
• 全ての分析ファイルのパスを分析回数別に整理して表示する
• 初回分析ファイル一覧（インデックス、サマリー、シーケンス図など）
• 追加調査ファイル一覧（該当する場合）
• 最終サマリー
• 一時ファイル（tmpディレクトリ）について説明する
• 調査結果は `{{tmpディレクトリ}}` に保存されている
• 必要に応じて参照可能
• 分析完了をユーザに報告する

rules

確認ポイント

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

質問1: 図に含めるシナリオ

• **質問**: どのシナリオのシーケンス図を作成しますか？
• **header**: "シナリオ選択"
• **multiSelect**: true
• **options**:
• "成功パターン" - 正常な処理フロー
• "バリデーションエラー" - 入力値検証エラーのパターン
• "ビジネスロジックエラー" - ビジネスルール違反のパターン
• "例外パターン" - システムエラー、外部API障害など
• "認証/認可エラー" - 認証・認可失敗のパターン
• "すべて" - すべてのパターンを含める

質問2: 詳細レベル

• **質問**: シーケンス図の詳細レベルはどの程度にしますか？
• **header**: "詳細レベル"
• **options**:
• "概要レベル" - 主要なコンポーネント間の処理フローのみ
• "標準レベル" - コンポーネント間の主要な処理とデータフロー
• "詳細レベル" - 内部処理やメソッド呼び出し、データ変換も含める

質問3: 除外条件

• **質問**: シーケンス図から除外したい対象はありますか？
• **header**: "除外条件"
• **multiSelect**: true
• **options**:
• "ログ出力処理" - ログ出力の記述を除外
• "バリデーション詳細" - バリデーションの詳細を簡略化
• "データ変換処理" - データ変換の詳細を簡略化
• "キャッシュ処理" - キャッシュアクセスを除外
• "除外なし" - すべて含める

contextとして以下を保持する

• 対象機能（具体的な機能名、エンドポイント、関数名など）
• 図に含めるシナリオ
• 詳細レベル
• 除外条件
• ベースディレクトリ
• tmpディレクトリ

ファイル名のルール

timestamp の形式

• yyyyMMddHHmmss 形式（例: 20251027123456）

内容の英語化のルール

• 対象機能を簡潔な英語に変換する
• スネークケース（snake_case）を使用
• 最大30文字程度に収める
• 例:
• "注文確定処理" → "order_confirmation"
• "カート更新" → "cart_update"
• "OrderController.confirmOrder" → "order_confirm"
• "商品在庫確認" → "inventory_check"

シーケンス図ファイル名のルール

• シーケンス図はシナリオごとに個別ファイルとして配置
• シナリオ別ファイル名:
• `sequence_success.md` - 成功パターン
• `sequence_error.md` - エラーパターン（バリデーション、ビジネスロジック）
• `sequence_exception.md` - 例外パターン（システムエラー、外部API障害）
• `sequence_auth_error.md` - 認証/認可エラーパターン

追加調査ファイル名のルール

• 追加調査が必要な場合、追加調査ごとに新しいファイルを作成
• 追加調査には連番プレフィックスを付与: `2_`, `3_`, `4_` など
• 例: `2_sequence_success.md`, `3_sequence_error.md` など（ベースディレクトリ内に配置）

一時ファイルのルール

• すべての調査結果は `{{ベースディレクトリ}}/tmp/` に保存
• コンポーネント分析: `tmp/component_analysis.md`
• 処理フロー分析: `tmp/flow_analysis.md`
• エラーハンドリング分析: `tmp/error_handling.md`
• 重要ファイル抜粋: `tmp/file_contents/*.md`
• 追加調査結果: `tmp/additional_N_*.md`

完全なファイル名の例

**初回分析**:

• `.dcs/20251027123456_order_confirmation/index.md` (インデックス)
• `.dcs/