migration-to-aws

迁移到 AWS 技能

理念

• 默认重新平台化：选择与 GCP 工作负载类型相匹配的 AWS 服务（例如，Cloud Run → Fargate、Cloud SQL → RDS）。
• 未指定时采用开发环境规格：默认使用开发级容量（例如，db.t4g.micro、单个 AZ）。仅在用户指示时升级。
• 基于成本做出明智决策：生成基础设施代码前，始终估算成本。
• 不计入人工一次性迁移成本：不得将人工劳动、专业服务或人力工时作为美元估算，或列为“一次性迁移成本”预算类别。基于数据的供应商费用（例如，在账单数据存在时，将 GCP 数据传出费用纳入基础设施估算）可以列入。
• 多信号方法：设计阶段根据可用输入进行调整：基础设施使用 Terraform IaC，服务映射使用账单数据，AI 工作负载检测使用应用代码。
• 优先生成 Terraform：默认使用 Terraform 作为迁移成果的 IaC 工具。
• 保留架构选择：迁移期间保留现有应用架构模式。
• BigQuery / google_bigquery_*：此技能不会推荐特定的 AWS 分析或数据仓库服务。在澄清阶段，如果发现 BigQuery（IaC google_bigquery_* 和/或账单中有 BigQuery 记录），则必须在设计之前提供专项咨询建议（参见 references/phases/clarify/clarify.md）。设计输出使用 Deferred — specialist engagement；在设计、估算和文档阶段，继续引导用户联系其 AWS 账户团队和/或数据分析迁移合作伙伴（参见 references/phases/design/design-infra.md 中的 BigQuery 专家关卡）。

---

定义

• “加载” = 使用 Read 工具读取文件并遵循其中的说明。不得总结或跳过任何章节。
• $MIGRATION_DIR = .migration/ 下针对本次运行的目录（例如，.migration/0226-1430/）。在第 1 阶段（发现）设置。

上下文加载规则

每个阶段都会按需加载参考文件。为控制每轮上下文的大小并避免指令遵循能力下降：

• 预算： 每个阶段加载的指令不得超过约 800 行（用户提供的 JSON 配置文件、MCP 工具结果等材料除外）。
• 按条件加载： 带有触发条件的参考文件（例如，agentic_profile.is_agentic == true）只有在条件满足时才可加载。不得推测性地加载文件。
• 不重复： 模型映射表、定价数据和通用警告均只存放在一个规范文件中。其他文件引用这些内容，而不会在文件内复制。
• 逐步深入： 阶段协调文件（design.md、generate.md）包含简短的路由逻辑，指向详细的子文件。仅在选定对应路径时加载子文件。

条件参考文件（仅在条件为真时加载）：

文件	条件
design-refs/ai-gemini-to-bedrock.md	ai-workload-profile.json 存在，且 summary.ai_source = "gemini" 或 "both"
design-refs/ai-openai-to-bedrock.md	ai-workload-profile.json 存在，且 summary.ai_source = "openai" 或 "both"
design-refs/ai.md	ai-workload-profile.json 存在，且 summary.ai_source = "other"
design-refs/design-ref-harness.md	agentic_profile.is_agentic == true 且 ai_constraints.agentic.migration_approach == "harness"
design-refs/design-ref-agentic-to-agentcore.md	agentic_profile.is_agentic == true 且 ai_constraints.agentic.migration_approach == "strands"
shared/retarget-gotchas.md	agentic_profile.is_agentic == true 且 ai_constraints.agentic.migration_approach == "retarget"

添加新的参考文件时，请确认该阶段加载的指令总数仍低于预算。如果与其他已加载的参考文件合并后，新文件会使总行数超过约 800 行，请拆分该文件或将其设为条件加载。

---

前提条件

用户必须至少提供一种 GCP 来源：

• Terraform IaC： .tf 文件（可选提供 .tfvars、.tfstate）
• 应用代码： 包含 GCP SDK 或 AI 框架导入语句的源文件
• 账单数据： GCP 账单／成本／用量导出文件（CSV 或 JSON）

如果未找到上述任何内容，请停止并要求用户至少提供一种来源。

状态机

这是执行控制器。完成每个阶段后，请查阅此表以确定下一步操作。

当前状态	条件	下一步操作
discover	phases.discover != "completed"	加载 references/phases/discover/discover.md
clarify	phases.discover == "completed" AND phases.clarify != "completed"	加载 references/phases/clarify/clarify.md
design	phases.clarify == "completed" AND phases.design != "completed"	加载 references/phases/design/design.md
estimate	phases.design == "completed" AND phases.estimate != "completed"	加载 references/phases/estimate/estimate.md
generate	phases.estimate == "completed" AND phases.generate != "completed"	加载 references/phases/generate/generate.md
complete	phases.generate == "completed" AND phases.feedback == "pending"	将 phases.feedback 设为 "completed"（用户已有两次机会），然后迁移完成
complete	phases.generate == "completed" AND phases.feedback == "completed"	迁移规划完成

如何确定当前状态（确定性）：

1. 读取 $MIGRATION_DIR/.phase-status.json
2. 如果 current_phase 存在，则使用它（必须是以下之一：discover、clarify、design、estimate、generate、complete）
3. 否则按顺序评估阶段：discover → clarify → design → estimate → generate
4. 按此顺序选取第一个 phases.<phase> != "completed" 的阶段；如果没有，则状态为 complete

阶段门禁检查：如果前一阶段尚未完成，则不得进入下一阶段（例如，未完成 design 阶段就不能进入 estimate 阶段）。

Clarify 阶段为必需阶段： 除非 $MIGRATION_DIR/.phase-status.json 存在且 phases.clarify 的值恰好为 "completed"，否则不得加载 references/phases/design/design.md、references/phases/estimate/estimate.md 或 references/phases/generate/generate.md。仅有 preferences.json 文件并不足以证明 Clarify 阶段已运行。如果用户要求跳过 Clarify 阶段，或直接进入 Design、成本估算或生成产物，请简短拒绝，然后加载 references/phases/clarify/clarify.md 并运行 Phase 2。即使迁移“很简单”或“显而易见”，也没有例外。

反馈检查点：反馈不是一个顺序阶段，而是在两个交错的检查点提供（分别在 Discover 阶段之后和 Estimate 阶段之后）。详情请参阅下文的 反馈检查点 部分。

---

状态验证

读取 $MIGRATION_DIR/.phase-status.json 时，继续之前请先验证：

1. 多个会话：如果 .migration/ 下存在多个目录，列出这些目录及其阶段状态，并询问：[A] 恢复最新会话，[B] 重新开始，[C] 取消。
2. JSON 无效：如果 .phase-status.json 解析失败，停止。输出：“状态文件已损坏（JSON 无效）。删除该文件并重新开始当前阶段。”
3. 无法识别的阶段：如果 phases 对象包含不属于 {discover、clarify、design、estimate、generate、feedback} 的阶段，停止。输出：“无法识别的阶段：[value]。有效阶段：discover、clarify、design、estimate、generate、feedback。”
4. 无法识别的状态：如果任何 phases.* 值不属于 {pending、in_progress、completed}，停止。输出：“无法识别的状态：[value]。有效值：pending、in_progress、completed。”
5. current_phase 无效（如果存在）：如果 current_phase 不属于 {discover、clarify、design、estimate、generate、complete}，停止。输出：“无法识别的 current_phase：[value]。有效值：discover、clarify、design、estimate、generate、complete。”
6. 阶段完成顺序错误：对于按顺序排列的阶段 [discover、clarify、design、estimate、generate]，如果某个后续阶段为 "completed"，而某个更早阶段未达到 "completed"，则停止。输出：“检测到阶段顺序不一致。恢复前请协调 .phase-status.json。”
7. 多个活动阶段：在核心阶段 {discover、clarify、design、estimate、generate} 中，最多只能有一个阶段为 "in_progress"。如果有多个，则停止。输出：“多个阶段处于 in_progress 状态。恢复前请只保留一个活动阶段。”

---

状态管理

迁移状态存储在 $MIGRATION_DIR（.migration/[MMDD-HHMM]/）中，由阶段 1 创建，并在多次调用间保留。

.phase-status.json 架构：

{
  "migration_id": "0226-1430",
  "last_updated": "2026-02-26T15:35:22Z",
  "current_phase": "design",
  "phases": {
    "discover": "completed",
    "clarify": "completed",
    "design": "in_progress",
    "estimate": "pending",
    "generate": "pending",
    "feedback": "pending"
  }
}

状态值："pending" → "in_progress" → "completed"。状态绝不回退。 对于核心阶段（discover、clarify、design、estimate、generate），任何时刻最多只能有一个阶段为 "in_progress"。 current_phase 为可选项，但建议设置；如果存在，则以它为准。

.migration/ 目录会由阶段 1 创建的 .gitignore 文件自动保护。

阶段状态更新协议

更新 .phase-status.json 时使用读取-合并-写入方式：

1. 每次更新前读取当前文件。
2. 只更改正在推进的阶段键和 last_updated。
3. 保持之前已完成阶段的状态不变。
4. 将 current_phase 设为下一个确定的阶段（或在 generate 之后设为 complete）。
5. 在发送阶段工作的最终消息时，在同一轮中写入完整文件。

示例——完成 Clarify 阶段后，将 $MIGRATION_DIR/.phase-status.json 写入为：

{
  "migration_id": "MMDD-HHMM",
  "last_updated": "2026-02-26T15:35:22Z",
  "current_phase": "design",
  "phases": {
    "discover": "completed",
    "clarify": "completed",
    "design": "pending",
    "estimate": "pending",
    "generate": "pending",
    "feedback": "pending"
  }
}

将 MMDD-HHMM 替换为实际的迁移 ID，自行生成 last_updated 的 ISO 8601 UTC 时间戳，并将每个阶段设为该时点的正确状态。

---

阶段摘要表

阶段	输入	输出	参考文档
Discover（发现）	.tf 文件、应用源代码和/或账单导出（至少需要一项）	gcp-resource-inventory.json、gcp-resource-clusters.json、ai-workload-profile.json、billing-profile.json、已更新的 .phase-status.json（输出因输入而异）	references/phases/discover/discover.md
Clarify（明确需求）	发现阶段产物（gcp-resource-inventory.json、gcp-resource-clusters.json、ai-workload-profile.json、billing-profile.json——以实际存在的文件为准）	preferences.json、已更新的 .phase-status.json	references/phases/clarify/clarify.md
Design（设计）	preferences.json + 发现阶段产物	aws-design.json（基础设施）、aws-design-ai.json（AI）、aws-design-billing.json（仅账单）	references/phases/design/design.md
Estimate（估算）	aws-design.json 或 aws-design-billing.json 或 aws-design-ai.json、preferences.json	estimation-infra.json 或 estimation-ai.json 或 estimation-billing.json、已更新的 .phase-status.json	references/phases/estimate/estimate.md
Generate（生成）	estimation-infra.json 或 estimation-ai.json 或 estimation-billing.json、aws-design.json 或 aws-design-billing.json 或 aws-design-ai.json、preferences.json	generation-infra.json 或 generation-ai.json 或 generation-billing.json + terraform/、scripts/、ai-migration/、validation-report.json（启用基础设施路径时）、MIGRATION_GUIDE.md、README.md、已更新的 .phase-status.json	references/phases/generate/generate.md
Feedback（反馈）	.phase-status.json（至少已完成 Discover 阶段）、所有现有迁移产物	feedback.json、trace.json、已更新的 .phase-status.json	references/phases/feedback/feedback.md

---

MCP 服务

awspricing（用于成本估算）：

• 提供 get_pricing、get_pricing_service_codes、get_pricing_service_attributes 工具
• 仅在估算阶段需要。发现和设计阶段不需要。
• 主要定价来源：references/shared/pricing-cache.md（缓存的 2026 年费率，基础设施费用误差为 ±5-10%，AI 模型费用误差为 ±15-25%）。MCP 是次要来源，仅用于缓存中未包含的服务。

---

此技能中的文件

migration-to-aws/
├── SKILL.md                                    ← You are here (orchestrator + state machine)
│
├── references/
│   ├── phases/
│   │   ├── discover/
│   │   │   ├── discover.md                     # Phase 1: Discover orchestrator
│   │   │   ├── discover-iac.md                 # Terraform/IaC discovery
│   │   │   ├── discover-app-code.md            # App code discovery
│   │   │   └── discover-billing.md             # Billing data discovery
│   │   ├── clarify/
│   │   │   ├── clarify.md                     # Phase 2: Clarify orchestrator
│   │   │   ├── clarify-global.md              # Category A: Global/Strategic (Q1-Q7)
│   │   │   ├── clarify-compute.md             # Categories B+C: Config Gaps + Compute (Q8-Q11)
│   │   │   ├── clarify-database.md            # Category D: Database (Q12-Q13)
│   │   │   ├── clarify-ai.md                  # Category F: AI/Bedrock (Q14-Q22)
│   │   │   └── clarify-ai-only.md             # Standalone AI-only migration flow
│   │   ├── design/
│   │   │   ├── design.md                       # Phase 3: Design orchestrator
│   │   │   ├── design-infra.md                 # Infrastructure design (IaC-based)
│   │   │   ├── design-ai.md                    # AI workload design (Bedrock)
│   │   │   └── design-billing.md               # Billing-only design (fallback)
│   │   ├── estimate/
│   │   │   ├── estimate.md                     # Phase 4: Estimate orchestrator
│   │   │   ├── estimate-infra.md               # Infrastructure cost analysis
│   │   │   ├── estimate-ai.md                  # AI workload cost analysis
│   │   │   └── estimate-billing.md             # Billing-only cost analysis
│   │   ├── generate/
│   │   │   ├── generate.md                     # Phase 5: Generate orchestrator
│   │   │   ├── generate-infra.md               # Infrastructure migration plan
│   │   │   ├── generate-ai.md                  # AI migration plan
│   │   │   ├── generate-billing.md             # Billing-only migration plan
│   │   │   ├── generate-artifacts-infra.md     # Terraform configurations
│   │   │   ├── generate-artifacts-scripts.md  # Migration scripts
│   │   │   ├── generate-artifacts-ai.md        # Provider adapter + test harness
│   │   │   ├── generate-artifacts-billing.md   # Skeleton Terraform
│   │   │   └── generate-artifacts-docs.md      # MIGRATION_GUIDE.md + README.md
│   │   └── feedback/
│   │       ├── feedback.md                     # Phase 6: Feedback orchestrator
│   │       └── feedback-trace.md               # Anonymized trace builder
│   │
│   ├── design-refs/
│   │   ├── index.md                            # Lookup table: GCP type → design-ref file
│   │   ├── fast-path.md                        # Deterministic 1:1 mappings (Pass 1)
│   │   ├── compute.md                          # Compute mappings (Cloud Run, GCE, GKE, etc.)
│   │   ├── database.md                         # Database mappings (Cloud SQL, Spanner, etc.)
│   │   ├── storage.md                          # Storage mappings (GCS, Filestore, etc.)
│   │   ├── networking.md                       # Networking mappings (VPC, LB, DNS, etc.)
│   │   ├── messaging.md                        # Messaging mappings (Pub/Sub, etc.)
│   │   └── ai.md                               # AI mappings (Vertex AI → Bedrock)
│   │
│   ├── clustering/terraform/
│   │   ├── classification-rules.md             # Primary/secondary classification
│   │   ├── clustering-algorithm.md             # Cluster formation rules
│   │   ├── depth-calculation.md                # Topological depth calculation
│   │   └── typed-edges-strategy.md             # Edge type assignment
│   │
│   └── shared/
│       ├── schema-phase-status.md              # .phase-status.json schema (canonical reference)
│       ├── schema-discover-iac.md              # gcp-resource-inventory + clusters schemas (loaded by discover-iac.md)
│       ├── schema-discover-ai.md               # ai-workload-profile schema (loaded by discover-app-code.md and discover-iac.md Step 7d)
│       ├── schema-discover-billing.md          # billing-profile schema (loaded by discover-billing.md)
│       ├── schema-estimate-infra.md            # estimation-infra.json schema (loaded by estimate-infra.md at write time)
│       ├── migration-complexity.md             # Complexity tier definitions (small/medium/large) for timeline scaling
│       ├── pricing-cache.md                    # Cached AWS + source provider pricing (±5-25%, primary source)
│       └── bedrock-quotas.md                   # Bedrock TPM/RPM quota awareness, burndown rates, capacity planning

条件	操作
未找到 GCP 来源（没有 .tf、应用代码或账单数据）	停止。输出：“未检测到 GCP 来源。请至少提供一种来源类型（Terraform 文件、应用代码或账单导出），然后重试。”
.phase-status.json 缺少阶段门禁	停止。输出：“无法进入阶段 X：阶段 Y-1 尚未完成。请从阶段 Y 开始，或恢复阶段 Y-1。”
尝试 3 次后 awspricing 仍不可用	向用户显示精度约为 ±5-25% 的警告。使用 pricing-cache.md。在适用的 estimation-*.json 文件中添加 pricing_source: "cached_fallback"。
用户跳过问题或表示“其余部分使用默认值”	对当前批次和后续所有批次中的剩余问题应用已记录的默认值。无论哪种情况，阶段 2 均会完成。
aws-design.json 缺少必需的集群	停止阶段 4。输出：“请重新运行阶段 3，以生成缺失的集群设计。”

默认值

• IaC 输出：Terraform 配置、迁移脚本、AI 迁移代码和文档
• 区域：us-east-1（除非用户另有指定，或 GCP 区域到 AWS 区域的映射另有建议）
• 规格：开发层级（例如，数据库使用 db.t4g.micro，Fargate 使用 0.5 CPU）
• 迁移模式：根据可用输入（基础设施、AI 或仅账单）进行调整
• 成本货币：USD
• 时间线假设：根据迁移复杂度，为 2-16 周——小型（2-6 周）、中型（6-12 周）、大型（12-18 周）。层级定义请参阅 references/shared/migration-complexity.md。

工作流执行

调用时，Agent 必须严格按照以下顺序执行：

1. 加载阶段状态：从 .migration/*/ 读取 .phase-status.json。

   • 如果文件不存在：初始化为第 1 阶段（Discover）
   • 如果文件存在：根据 State Machine 中的确定性规则确定当前阶段

2. 确定要执行的阶段：

   • 如果存在 current_phase：执行该阶段。
   • 否则，按顺序执行第一个未完成的阶段：discover → clarify → design → estimate → generate。
   • 如果所有阶段均已完成：迁移已完成（需遵循反馈最终处理规则）。

3. 读取阶段参考文件：加载目标阶段的完整参考文件。

4. 按顺序执行所有步骤：遵循参考文件中的每个编号步骤。不得跳过、优化或偏离。

5. 验证输出：在继续之前，确认所有必需的输出文件均存在且符合正确的架构。

6. 更新阶段状态：在阶段的最终输出消息所在的同一轮中，使用阶段状态更新协议（读取-合并-写入）。

7. 反馈检查点：阶段完成后，检查是否需要收集反馈（见下方规则）。此步骤在进入下一阶段之前执行。

   • Discover 阶段后（如果 phases.feedback 为 "pending"）：向用户输出： "您愿意分享快速反馈吗（5 个可选问题 + 匿名使用数据），以帮助改进此工具？您的数据绝不包含资源名称、文件路径或账户 ID。 [A] 现在发送反馈 [B] 等到 Estimate 阶段之后"

     • 如果用户选择 A → 加载 references/phases/feedback/feedback.md，执行其中的内容，然后继续 Clarify。
     • 如果用户选择 B → 继续 Clarify（反馈仍为 "pending"）。

   • Estimate 阶段后（如果 phases.feedback 为 "pending"）：向用户输出： "您现在愿意分享快速反馈吗？（5 个可选问题 + 匿名使用数据） [A] 是，分享反馈 [B] 不，谢谢，继续 Generate"

     • 如果用户选择 A → 加载 references/phases/feedback/feedback.md，执行其中的内容，然后继续 Generate。
     • 如果用户选择 B → 使用阶段状态更新协议，将 phases.feedback 设为 "completed"。继续 Generate。

   • Generate 阶段后：不提供反馈选项。如果 phases.feedback 仍为 "pending"，使用阶段状态更新协议将其设为 "completed"（用户已有两次机会选择延后或跳过）。

8. 显示摘要：向用户说明已完成的工作，突出显示下一阶段，或确认迁移已完成。

关键限制：Agent 必须严格遵循参考文件中的工作流。如果无法完成某个步骤，请停止并报告确切失败步骤。

用户可以再次调用此技能，从 current_phase 恢复（如果不存在 current_phase，则按确定性的顺序进行评估）。

范围说明

v1.0 包含：

• Terraform 基础设施发现
• 应用代码扫描（AI 工作负载检测）
• 从 GCP 导入账单数据
• 用户需求澄清（按类别提出自适应问题）
• 多路径设计（基础设施、AI 工作负载、仅账单回退方案）
• AWS 成本估算（使用定价 API 或回退方案）
• 生成迁移产物（Terraform、脚本、AI 适配器、文档）
• 可选的反馈收集与匿名遥测