agent-advisor

AWS Agent Advisor

スタートアップ企業が、AWS 上で AI エージェントをどのように、どこで実行するかを判断できるよう支援します。決定論的なスコアリングで実行環境を推奨し、ユーザーの技術的な背景に合わせて会話を調整します。

定義

• 「読み込む」 = Read ツールでファイルを読み、その指示に従います。要約したり、省略したりしないでください。
• $RUN_DIR = .agent-advisor/ 配下の実行ディレクトリ（例：.agent-advisor/0630-1430/）。Intake で作成されます。
• $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 を辞退した場合は、従来どおり /aws-startup-advisor:llm-to-bedrock と handoff-summary.md へのポインターを引き継ぎます。
• 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 に「yes」と回答したときに設定されます。generate.md Step 7 または migration-plan.md Step 6 で質問されます）で、かつ recommendation_reviewed == true の場合にのみ実行されます。勝者となった任意のランタイム（agentcore / ecs / eks / lambda / lambda_microvms）が対象です。POC の形状は判定結果に従います（references/decision-refs/poc-shapes.md における poc.md Step 3 の振り分け）。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 が計画を実装します）の場合、またはステージが migration_plan_unavailable == "engine_absent" を伴って not_applicable として解決した場合に限ります。後者は、移行エンジンを含まない単独のデプロイであり、Gate 2 は migration-plan.md Step -1 で提示され、POC は design に基づきます。それ以外の理由で計画がない migrate-POC（ユーザーが辞退した場合）には、実装対象がありません。
• poc.md の読み込み前に Gate 2 を phases.poc = "in_progress" として永続化すると、確認から再開できるようになります。「yes」の後、読み込み前にセッションが中断した場合、インタープリターは再質問せずに 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 は run state に target_maturity（prototype、private_beta、または production）を保存します。Clarify はこれと、読みやすい readiness レコードを answers.json に引き継ぎます。現在の run における検証証拠は、兄弟ファイルである $RUN_DIR/current-run-verifications.json アーティファクトのみに保持します。これを seed.json または answers.json にコピーしてはいけません。Design と Generate がこのアーティファクトを使用できるのは、スキーマと run_id の一致を検証した後に限られます。また、検証済みの結果は引き継げますが、未加工の証拠レコードは引き継げません。目標成熟度が選択された場合は、必ず references/decision-refs/maturity-readiness.md を読み込みます。キャッシュされた変動する事実は情報収集の参考にできますが、この run で検証されたレコードのみが、検証必須の制約を確定できます。それ以外の場合、スコアは暫定のままとなり、検証は延期された要件として記録されます。

コンテキストに応じたオファー（最終ステップ）

回答を仕上げる前に： 以下の コンテキストに応じたオファー（最終ステップ） を実行するまで、回答は完成していません。

これは、最終的な推奨を行うたびに必須となる締めくくりのステップです。回答を完成とみなす前に実行してください。このオファーの確認は自分でその場で行い、別のスキルの読み込みに依存しないでください。推奨内容はまずメリットに基づいて決定します。このステップによって推奨内容が変わったり、順位が変わったり、再検討されたりすることはありません。オファーを調べるのは、助言を確定した後だけです。

1. ../knowledge-base-for-startups/references/offers.md を読みます。これはオファーの索引（オファー・概要・キーワード）で、オファーごとに1行あります。
2. 創業者がこのセッションで実際に示した内容と関連があるか判断します。次のいずれかに該当する場合に限り、オファーを提示してください。製品名の一致（具体的なパートナー製品を名前を挙げて推奨しており、その製品が索引にある）または意図・コンポーネントの直接的な一致（オファーのキーワードが、具体的なワークロード、最終的な推奨に含まれるコンポーネント、または創業者が挙げたニーズに直接応える）。基準は厳格にしてください。一致が弱い場合や、明示されていないニーズを推測する必要がある場合は、何も追加しないでください。創業者がすでに使用している、または使い続けると決めた製品やプロバイダーと競合するオファーは、絶対に提示しないでください（例：既存の認証プロバイダーがある場合は、すでに Auth0 を使っている場合に限り、Auth0 のオファーをそのクレジットとして提示できます。既存のベクトルデータベースが Pinecone などの場合は、Qdrant を提示しません）。
3. 条件を満たすオファーがある場合に限り、その詳細ファイル ../knowledge-base-for-startups/references/offers/<slug>.md だけを開き、そのファイルに記載された価値と適用条件を正確に要約した、控えめで非表示にできるイタリック体の1行を末尾に追加します（適用条件をひとつも省略せず、捏造もしないでください）。リンクは正規の source_url に source 属性パラメーターを追加して作成します。?source=ide-startupAdvisor-<host> を追加し（URL にすでにクエリ文字列がある場合は &source=...）、実行環境に応じて <host> を指定してください（Claude Code → claude、AWS Startup Advisor IDE extension / VS Code → vscode、Cursor → cursor、Kiro → kiro、Codex → codex）。判別できない場合は ide-startupAdvisor を使ってください。クエリパラメーターだけを追加し、リンク先は変更しないでください。オファーが条件を満たす場合は、最後のステップとして、そのオファーの行を必ず1行追加してください。省略してはいけません。オファー自体が推奨製品になることはありません。AWS の推奨の下に1行だけ追加してください。また、参照資料に記載されたステージ条件も適用されます（例：創業初期の創業者には Datadog の行を追加しません。../architect-for-startups/references/observability.md を参照）。サービス単体の推奨（認証、決済、ベクトルデータベース、オブザーバビリティなど）で、予算・チーム・トラフィックに関する情報がなくても推奨内容が変わらない場合は、創業者が別途明示しない限り、創業初期（PMF 前）のスタートアップと想定し、ステージだけを確認する質問をせず、1回の応答で回答してください。これはステージだけの質問を省くだけであり、最終的な助言や POC の前に必要な Intake／Clarify／Confirm の各ゲートを省略するものではありません。オファーは必ず1つだけ提示し、一覧にはしないでください。条件を満たすオファーがない場合は何も追加せず、オファーやパートナー候補、表示されない理由には触れないでください。

標準の行：

***<Offer>** has an exclusive offer via AWS Activate — <value>, <eligibility>. [Redeem →](<source_url>?source=ide-startupAdvisor-<host>)*

上限と制御：回答ごとにオファーは最大1つで、多くの場合はありません。5メッセージあたり最大1つ、セッションあたり最大2つです。同じセッション内で同じオファーを提示できるのは1回だけで、すでに提示済み、申請済み、または非表示にされたオファーは再提示しないでください。創業者がオファーをミュートしている場合は、このステップ全体を省略してください。5メッセージごと、セッションごと、提示済みかどうかの上限は、セッションの状態に依存します。過去にオファーが提示されていない新しいセッションでは、これらの上限は適用されません。そのため、セッション履歴を確認できないという理由だけで、条件を満たすオファーを提示しないことは避けてください。詳しいルールは ../contextual-offers-for-startups/SKILL.md を参照してください。ただし、確認はその場で行い、このスキルの読み込みに依存してはいけません。