agent-advisor

AWS Agent Advisor

スタートアップが、AWS 上で AI エージェントをどのように、どこで実行するかを判断できるよう支援します。決定論的なスコアリングで実行環境を推奨し、ユーザーの技術的な背景に合わせて会話を調整します。AgentCore マイクロ VM では、バージョンの希望を尋ねずに、デフォルトで V2 を選択します。適用可能かを確認し、証拠のある例外に限って V1 を維持してください。設計と POC の読み込み時には、このポリシーを定めた references/decision-refs/agentcore-platform.md を読み込みます。

定義

• 「読み込み」 ＝ Read ツールでファイルを読み、その指示に従います。要約したり、読み飛ばしたりしないでください。
• $RUN_DIR ＝ Intake で作成される、.agent-advisor/ 配下の実行ディレクトリ（例：.agent-advisor/0630-1430/）です。
• $PLUGIN ＝ ${CLAUDE_PLUGIN_ROOT}（インストール済みプラグインのルート）です。Claude Code では、このトークンはインラインで置き換えられます。${CLAUDE_PLUGIN_ROOT} が解決されない場合（一部の Cursor／Codex ビルド、またはパスエラーに ${CLAUDE_PLUGIN_ROOT} という文字列がそのまま表示される場合）は、スキル自体のディレクトリにフォールバックしてください。この SKILL.md は <plugin>/skills/agent-advisor/SKILL.md にあるため、エンジンとそのデータはすべてこのスキル内にあります。スクリプトは ./scripts/...、実行環境プロファイルは ./references/runtimes/...、判断用資料は ./references/decision-refs/... にあります。まず ${CLAUDE_PLUGIN_ROOT}/skills/agent-advisor/... を使用し、解決に失敗した場合にのみ相対パスへフォールバックしてください。

前提条件

• スコアリングに uv を使用します。確認方法：uv --version。見つからない場合は、公式インストールガイド（https://docs.astral.sh/uv/getting-started/installation/。例：`brew install uvまたはpipx install uv`）からインストールするようユーザーに伝え、そこで停止してください。

フェーズ構成（frontmatter）

フェーズ、フラグメント、アセンブラーの各ファイルには、各フェーズの構成要素（入力、トリガー、フラグメント、アセンブラー、成果物、ゲート、順序）を宣言する YAML frontmatter ブロックがあります。実行規約は、同梱された references/vendored/dsl/INTERPRETER.md で定義されています。このファイルでは、frontmatter のすべてのキー、フラグメント／アセンブラーモデル、ゲートプロトコル（HANDOFF_OK／GATE_FAIL）、インタープリターのループを定義しています。最初にこれを読み込んでください（実行開始時に一度だけ）。その後、各フェーズファイルの本文に従って実行します。このスキル内でパスを付けずに INTERPRETER.md と記載している場合は、読み込み済みのこの規約を指します。

実行

このスキルは、INTERPRETER.md（§ インタープリターループ）のインタープリターループによって動作します。 .phase-status.json を読み取り、現在のフェーズを特定し、各フェーズの _preconditions／フラグメント／_assemble／_postconditions を実行して、 _advances_to に従って HANDOFF_OK で次のフェーズへ進み、状態を検証します。バックボーン（intake → discover → clarify → confirm → design → estimate → generate → migration-plan → poc → complete）と、 唯一のサイドバーブランチ（add-capabilities）は、フェーズファイルのフロントマターから導出されるものであり、 ここでは再掲しません。

コールドスタート（開始フェーズ）。 .agent-advisor/ 内に .phase-status.json を含む実行がない場合は、このスキルの開始フェーズである references/phases/intake/intake.md（_init: true を持つフェーズ）から開始します。ウォームスタートでは、 .phase-status.json の current_phase が優先されます（INTERPRETER.md § インタープリターループ）。

スキルバインディング（INTERPRETER.md § スキルバインディング）。 このスキルでは、次を宣言します。

• 実行ルート：.agent-advisor/ — $RUN_DIR は、このスキルで実行ディレクトリ （.agent-advisor/[MMDD-HHMM]/）を指す名前です。intake の説明文が _init のブートストラップを 独自に実行します。
• 状態の形状：以下の§ 状態ファイル（entry_point、audience、 recommendation_reviewed、migration_plan_ctx、migration_plan_unavailable などの advisor 固有のキー）を参照してください。 共通の状態スキーマは同梱されていません。
• 実行シード（任意）：$RUN_DIR/seed.json、または実行ルートの .agent-advisor/seed.json （スキーマは scripts/schemas/seed.json）は、非対話型の実行に使用する 機械可読な回答を提供します。対象は、Clarify の各ディメンション、2 つのゲートへの 回答、POC モード、ライブプローブへの回答、および co_recommend のタイブレークです。シードは、 そこに含まれるすべての値の中で最も優先度の高い情報源です（clarify.md Step 2.5）。これにより、 決定論的エンジンへの入力がバイト単位で同一になり、繰り返し実行した際のスコアを比較できます。シードに 含まれないゲートは拒否されたものとして扱います。シードに含まれないディメンションは、検出結果、次に説明文、 それでも得られない場合は assumed の値に従います。この値は必ず $RUN_DIR/UNANSWERED.md に記録してください。 シードがない場合、対話型フローに変更はありません。
• 解決済みステータス：フェーズを実行せずにルーティングで解決した場合の skipped と、 migration_plan のみに適用される not_applicable。
• 条件付きバックボーンルーティング：以下の開始点ルーティング。ルーティングルールによってフェーズが 該当なしと判断された場合は、そのフェーズを skipped に設定し、同じ状態書き込みで _advances_to に従って次へ進みます。

ルーティングとゲート（オーケストレーション）

サイドバーの配置と条件付きのバックボーンルーティングに関する説明は、このファイル（INTERPRETER.md § スキルバインディング、§ バックボーンとサイドバー）が管理します。

エントリーポイントのルーティング：

• build_scratch → Discover をスキップします。Clarify → Confirm → Design → Estimate → Generate → Gate 2 → POC（勝者となった任意のランタイム）。移行計画はありません（移行対象となる既存環境がないためです）。
• build_deploy → Discover（コードがある場合）→ Clarify → Confirm → Design → Estimate → Generate → Gate 1 → Migration Plan（既存の非 AWS AI ワークロードが検出され、ユーザーが確認した場合） → Gate 2 → POC（勝者となった任意のランタイム）。
• migrate → Discover（コードがある場合）→ Clarify → Confirm → Design → Estimate（ターゲット状態での実行コスト。移行 TCO の比較は Migration Plan エンジンが担当します）→ Generate → Gate 1 → Migration Plan（スキル内で、兄弟スキルの gcp-to-aws を再利用） → Gate 2 → POC（計画が作成された場合、勝者となった任意のランタイム）。Gate 1 を辞退した場合は、従来の引き継ぎが維持されます。handoff-summary.md とともに /migration-to-aws:llm-to-bedrock へのポインターを提示します。
• add_capabilities → references/phases/add-capabilities/add-capabilities.md を読み込み、その指示に従います（ランタイムのスコアリングは行わず、capabilities-recommendation.md を書き込みます）。これは自己完結型の分岐です。Clarify／Confirm／Design／Estimate／Generate を経由しないため、以下のフェーズゲートは適用されません。
• Temporal が検出された場合は、Temporal ユニットを事前設定したうえで migrate にルーティングします（discover を参照）。

ゲートのセマンティクス（バックボーンの末尾）：

• Gate 1 → migration_plan は、generate が完了し、recommendation_reviewed == true（generate.md の Step 5.5）で、エントリーポイントが {migrate, build_deploy} に含まれ、実行が移行対象となり（generate.md の Step 6）、ユーザーが Gate 1 を確認した場合にのみ実行されます。それ以外の場合は、not_applicable（build_scratch／移行可能なワークロードがない）または skipped（辞退）として解決し、次に進みます。
• Gate 2 → poc は、phases.poc == "in_progress"（ユーザーが Gate 2 に「はい」と回答したときに設定されます。質問は generate.md の Step 7 または migration-plan.md の Step 6）かつ recommendation_reviewed == true の場合にのみ実行されます。勝者となったランタイム（agentcore / ecs / eks / lambda / lambda_microvms）は問いません。POC の形状は判定結果に従います（poc.md の Step 3 で references/decision-refs/poc-shapes.md に基づき振り分けます）。Gate 2 を提示するのは、migration_plan ∈ {completed, skipped, not_applicable} の場合、または build_deploy に限り in_progress の場合（Stage 2 が失敗／中断し、migration-plan.md の失敗時の処理に従って design.json からフォールバック POC を作成する場合）です。エントリーポイントが migrate の場合は、migration_plan == "completed"（POC が計画を実装する）か、ステージが not_applicable として解決され、migration_plan_unavailable == "engine_absent" の場合に限ります。これは移行エンジンが同梱されていないスタンドアロンのデプロイで、Gate 2 は migration-plan.md の Step -1 で提示され、POC は design を基にします。その他の理由で計画のない migrate-POC（ユーザーが辞退した場合など）は、実装するものがありません。
• phases.poc = "in_progress" を poc.md の読み込み前に永続化すると、確認を再開可能にできます。「はい」と回答してから読み込みまでの間にセッションが中断した場合、インタープリターは再度質問せずに poc に戻ります。（これは INTERPRETER.md § インタープリターループのステップ 5 にある、ゲートを通過してから in_progress にする順序からの意図的な逸脱です。ユーザーの確認は、永続化する価値のある開始イベントです。）

フェーズゲート： $RUN_DIR/.phase-status.json が存在し、かつ phases.clarify == "completed" と phases.confirm == "completed" の両方を満たさない限り、design.md／estimate.md／generate.md を読み込まないでください。Confirm ではデプロイモデル、サービスのセット、および（co_recommend が同点の場合）ユーザーの chosen_runtime を確定します。Design と図はその confirm.json の出力に依存するため、スキップしてはいけません。ユーザーから Clarify または Pass 2 をスキップするよう求められた場合は、簡潔に断り、実行してください。

状態ファイル（.phase-status.json）

{
  "run_id": "0630-1430",
  "entry_point": "build_scratch",
  "audience": "technical",
  "current_phase": "clarify",
  "phases": {
    "intake": "completed",
    "discover": "skipped",
    "clarify": "in_progress",
    "confirm": "pending",
    "design": "pending",
    "estimate": "pending",
    "generate": "pending",
    "migration_plan": "pending",
    "poc": "pending"
  }
}

状態値：pending → in_progress → completed、および skipped。読み取り・マージ・書き込みの手順を使います。 各更新の前に読み取り、進行するキーのみを変更し、前のフェーズは保持してください。

recommendation_reviewed（トップレベル、ブール値）は、ユーザーが推奨事項を確認したことを明示的に確認した場合、generate.md のステップ 5.5 で true に設定されます。Gate 1、Gate 2、および migration_plan / poc の状態はいずれも、この値が設定されていることを必須とします。設定されていない場合、いずれのゲートについてもユーザーに確認を求めてはなりません。

migration_plan では、追加で not_applicable も使用します（build_scratch、または移行可能なワークロードが検出されなかった場合）。Stage 2 の実行時に、トップレベルへ migration_plan_ctx が追加されます：{"repo": "<対象リポジトリの絶対パス>", "migration_dir": "<.migration/<id>/ の絶対パス>"} — Stage 3 は、この記録されたパスを通じてのみ gcp-to-aws の成果物を読み込み、グロブによる再検索は行いません。

ファイル

ファイル	目的
references/vendored/dsl/INTERPRETER.md	ベンダー提供の DSL 実行契約（インタープリターループ＋ゲートプロトコル）
references/phases/intake/intake.md	エントリーポイント＋技術的背景＋未解決のコンテキスト
references/phases/discover/discover.md	軽量なコード検出
references/phases/clarify/clarify.md	明確化オーケストレーター＋回答からスコアリングキーへのマッピング
references/phases/clarify/clarify-technical.md	技術的背景に関する質問の表現
references/phases/clarify/clarify-business.md	ビジネス背景に関する質問の表現
references/phases/confirm/confirm.md	選定候補に固有の追加質問
references/phases/design/design.md	推奨事項の作成；移行引き継ぎ分岐
references/phases/estimate/estimate.md	概算コスト規模
references/phases/generate/generate.md	レイヤー化された推奨ドキュメント＋スキャフォールディング
references/phases/migration-plan/migration-plan.md	ステージ 2：兄弟関係にある gcp-to-aws エンジンを使った完全な移行計画
references/decision-refs/temporal.md	Temporal のルール：Tier 1/2 の表、アダプター、ランブック、商用条件（discover/clarify/design/generate で使用）
references/decision-refs/poc-shapes.md	ランタイムごとの POC デプロイ形態（ECS/EKS/Lambda/MicroVMs/Temporal）
references/decision-refs/*.md	ランタイムサービスカード、モデルのデフォルト、鮮度
references/decision-refs/workload-classes.md	エージェント以外のワークロード単位（batch/service/io）に対する決定論的な判定
references/runtimes/*.json	ランタイムレジストリ（scoring.py で読み込み）
scripts/scoring.py	決定論的スコアリングエンジン
scripts/test_temporal_decision_refs.py	Temporal の意思決定リファレンスの内容ロック
scripts/test_poc_shapes.py	POC デプロイ形態の内容ロック
scripts/test_workload_classes.py	workload-classes.md（判定表）の内容ロック
scripts/test_unit_grouping.py	単位のグループ化＋パターンマッチング（ワークロードクラスの割り当て）
scripts/test_collapse_invariant.py	縮約不変の順序付けの適用（A→B は [B] ⊆ [A] の出力を意味します）

成熟度と準備状況の契約

Intake は target_maturity（prototype、private_beta、または production）を実行状態に保持します。Clarify はこれと、読み取り可能な readiness レコードを answers.json に引き継ぎます。今回の実行における検証証拠は、兄弟ファイルである $RUN_DIR/current-run-verifications.json アーティファクトにのみ保持します。これを seed.json や answers.json にコピーしてはいけません。Design と Generate は、スキーマを検証し、run_id が一致することを確認した後に限り、このアーティファクトを使用できます。また、検証済みの結果は引き継げますが、生の証拠レコードは引き継げません。目標成熟度が選択された場合は、references/decision-refs/maturity-readiness.md を読み込んでください。キャッシュされた揮発性の事実は調査の参考にできますが、今回の実行で検証されたレコードのみが、検証必須の制約を確定できます。それ以外の場合、スコアは暫定のままとし、検証要件を先送りとして記録します。