connect-blueprint
Overview
2つのモードで Amazon Connect コンタクトフローを生成する：
- モードA（ゼロから設計）: 要件ヒアリング → Mermaid設計図 → フローJSON → デプロイ
- モードB（設計図から生成）: draw.io/Mermaid/画像 → フローJSON → デプロイ
Prerequisites
- AWS CLI + 有効なプロファイル（
aws sts get-caller-identity --profile <profile>で確認） - Connect インスタンスID（
aws connect list-instances --profile <profile>で取得可） - 必要IAM権限:
connect:*
Mode A: Design from Scratch
Progress Tracking
各ステップ完了時にチェックし、現在の進捗を把握する：
- Step 1: 要件ヒアリング完了
- Step 2: Mermaid 設計図作成 → ユーザー承認済み
- Step 3: フロー JSON 生成 + AWS MCP パラメータ検証完了
- Step 4a: ローカルバリデーション通過
- Step 4b: (任意) API バリデーション通過
- Step 4c: デプロイ → ユーザー承認 → 完了
Step 1: 要件ヒアリング
以下を確認する：
- 電話の目的・業種・主なユースケース
- IVR選択肢（番号と対応内容）
- 営業時間分岐の有無
- 外部システム連携（Lambda/DynamoDB等）
- 既存フローとの統合有無
- 通話録音の要否と録音対象（Agent / Customer / 両方）
- Contact Lens 分析の有効/無効
- 分析言語（ja-JP, en-US 等）
- 機密情報マスキング（redaction）の要否
環境情報を取得してユーザーに見せる： references/aws_cli_commands.md の「環境情報の取得」セクションのコマンドで以下を取得し、ユーザーに提示する：
- キュー一覧、プロンプト一覧、Lambda一覧、フローモジュール一覧
実現不可能な要件があればこの段階で明示してユーザーに伝える。
Step 2: Mermaid 設計図の生成
references/mermaid_notation.md の記法に従ってMermaid図を生成する。
繰り返し処理（リトライメニュー等）は、まず Loop ActionType の使用を検討する。 Loop で実現できない場合のみ UpdateContactAttributes + Compare によるカウンタ方式を検討する。
Mermaid図は .md ファイルとして保存する（例: <flow-name>-design.md）。 保存後、必ずユーザーにレビューを依頼し承認を得てから次のステップへ。
Step 3: フローJSON生成
Mermaidからフロー構造を解析してJSON（Actions配列 + Transitions）を生成する。 references/flow_json_structure.md の構造仕様に従う。
フローの最初のアクションは必ず UpdateFlowLoggingBehavior とする。 StartAction に UpdateFlowLoggingBehavior のIDを設定し、その NextAction を本来のエントリーアクションにする。
AWS MCP Parameter Validation
各ActionTypeのパラメータを設定する際、references/action_types.md の共通ルールを確認した上で、AWS MCP で公式ドキュメントを参照してパラメータの正確性を保証する：
references/action_types.mdの AWS Docs パス対応テーブルから該当URLパスを取得aws___read_documentationでパラメータ仕様を確認- ドキュメントに基づいてパラメータを設定する
Why: ローカルリファレンスはパラメータの概要のみ記載。正確なフィールド名・型・制約は AWS 公式ドキュメントが信頼できるソース。
position付与:
python3 scripts/layout.py <flow.json>Step 4: Validate & Deploy
IMPORTANT: Always validate before deploying. Never skip this step.
ローカルバリデーション (required)
./scripts/validate.sh flow.jsonIf validation returns errors, fix the flow JSON and re-validate before proceeding. Only deploy after validation passes with no errors.
Validation Feedback Loop
./scripts/validate.sh flow.jsonを実行- エラーがある場合: a. エラーメッセージを解析 b.
aws___read_documentationで公式仕様を確認 c. フローJSONを修正 d. 手順 1 に戻り再実行する - エラーなしになるまで繰り返す（最大3回。超過時はユーザーに報告）
APIバリデーション (recommended)
./scripts/validate.sh --api --instance-id $INSTANCE_ID --profile $PROFILE flow.jsonローカルチェック通過後、create-contact-flow --status SAVED で下書きを作成してConnect APIによるバリデーションを実行する。成功時は下書きを自動削除する。
Why: ローカルチェックはJSON構造・遷移参照の整合性のみ検証する。ActionType固有のパラメータ制約やErrors/Conditionsの妥当性はConnect API側でしか検証できないため、APIバリデーションで事前にエラーを検出する。
Deploy
references/aws_cli_commands.md の「フロー操作」セクションのコマンドでデプロイする。 2ステップ方式: --status SAVED で作成 → update-contact-flow-metadata --contact-flow-state ACTIVE で公開。
Mode B: Convert from Diagram
入力形式に応じて処理：
- Mermaid: そのまま Step A-3 へ
- draw.io XML: ノード/エッジを抽出してMermaidに変換 → Step A-3 へ
- 画像: Vision解析でフロー構造を読み取り → Mermaidに変換 → Step A-3 へ
変換後は必ずユーザーに確認してから進む。
Key Constraints
references/flow_json_structure.md と references/action_types.md の共通ルールに従う。 以下はフロー生成時に特に重要な制約：
- StartAction は UpdateFlowLoggingBehavior にする
- サンプルフローは提供しない — 要件に応じてゼロから設計すること
Security Rules
Deploy Safety Guard
scripts/deploy.shの実行、またはaws connect create-contact-flow/aws connect update-contact-flow-contentコマンドの実行前に、必ずユーザーの明示的な承認を得ること.envファイルや AWS クレデンシャルファイル（~/.aws/credentials等）を読み取らないこと
Safe Operations (No Confirmation Required)
scripts/validate.sh <file>によるローカルバリデーション（--apiオプション含む。下書き保存は自動削除される）python3 scripts/layout.py <file>によるレイアウト座標付与- フローJSONの作成・編集
Placeholders
<YOUR_XXX_ARN>プレースホルダーを実際の ARN に置き換える際は、ユーザーから提供された値のみ使用すること- 推測や仮の値で ARN を埋めないこと
Coding Conventions
- シェルスクリプト: 変数は必ずダブルクォートで囲む。AWS CLI 引数の組み立てには bash 配列を使用する
- Python: 標準ライブラリのみ使用（外部パッケージ不可）
- JSON: テンプレートでは実際の ARN/ID を使用せず
<YOUR_XXX>プレースホルダーを使う
Validation
3層バリデーションでフロー品質を保証する:
- AWS MCP:
aws___read_documentationで ActionType パラメータ仕様を確認（フロー生成時） - ローカル:
./scripts/validate.sh flow.jsonで構造・遷移・孤立ブロック・デッドエンド検出 - Connect API:
./scripts/validate.sh --api --instance-id $ID --profile $P flow.jsonで API 側の制約を検証
Troubleshooting
エラー発生時の対処:
references/error_handling_patterns.mdでパターンを確認aws___search_documentation/aws___read_documentationで公式ドキュメントを調査- 推測による修正は避け、必ず公式ドキュメントで裏付けを取る
References
- Action Types:
references/action_types.md - Flow JSON Structure:
references/flow_json_structure.md - Mermaid Notation:
references/mermaid_notation.md - AWS CLI Commands:
references/aws_cli_commands.md - Layout Rules:
references/layout_rules.md - Error Handling Patterns:
references/error_handling_patterns.md - Connect Limits:
references/connect_limits.md