app-platform-migration

App Platform 移行スキル

機能を誠実に評価しながら、既存のアプリケーションを DigitalOcean App Platform に移行します。

方針

このスキルは魔法の杖ではなく、誠実なパートナーです。次のことを行います。

1. 変更を提案する前に徹底的に分析します
2. 自信を持って対応できるものをマッピングします
3. 不足している点を明確かつ具体的に示します
4. 不確かな場合は、作業を進める前に確認します
5. 推測したり、互換性の問題を無視したりしません

ヒント：複雑な複数手順の移行では、まず planner スキルを使用してください。利用可能なすべてのスキルについては、ルートの SKILL.md を参照してください。

---

クイック判断

What's your source platform?
├── Heroku (Procfile, app.json, heroku.yml) → See Heroku Deep Chapter below
├── Docker Compose → See Quick Start below
├── Render/Railway/Fly.io → See Quick Start below
├── AWS ECS/App Runner → Complex migration, see reference
└── Just Dockerfile → See Quick Start below

---

対応プラットフォーム

プラットフォーム	設定ファイル	対応レベル
Heroku	Procfile, app.json, heroku.yml	完全対応（詳細な章を参照）
Docker Compose	docker-compose.yml	完全対応
Render	render.yaml	完全対応
Railway	railway.json, railway.toml	完全対応
Fly.io	fly.toml	完全対応
AWS ECS	Task Definition JSON	部分対応
AWS App Runner	apprunner.yaml	部分対応
一般的な Docker	Dockerfile のみ	完全対応

---

移行ワークフロー

Phase 1: DISCOVERY
├── Clone/access repository
├── Detect source platform
├── Analyze architecture
└── Inventory all services

Phase 2: MAPPING
├── Map services → App Platform components
├── Map databases → Managed databases
├── Map storage → Spaces
├── Map secrets → GitHub Secrets
└── Identify unmappable items → REPORT TO USER

Phase 3: REFACTORING
├── Create target branch(es)
├── Update environment variables
├── Remove platform-specific code
├── Update Dockerfile if needed
└── Generate app spec

Phase 4: VALIDATION
├── Validate: doctl apps spec validate
├── Review changes with user
└── Generate migration checklist

Phase 5: HANDOFF
├── Push branches to repo
├── Provide manual steps checklist
└── Suggest deployment skill

---

クイックスタート

基本的な移行

# User provides repo URL
"Migrate this app to App Platform: https://github.com/myorg/myapp"

# AI will:
# 1. Clone and analyze
# 2. Detect platform
# 3. Present mapping proposal
# 4. Ask for approval
# 5. Create branch with refactored code + app spec

ブランチを指定する場合

"Migrate my Heroku app. Put test config in 'migrate/test', prod in 'migrate/prod'"

ワークフローの全例：workflow-examples.md を参照してください。

---

Heroku からの移行（詳細な章）

Heroku 固有の移行については、Procfile、app.json、heroku.yml、ビルドパック、パイプライン、アドオン、CLI のマッピングに関する詳しい知識をまとめた包括的な章を用意しています。

最初に読むもの：heroku-overview.md を読み、移行モード（Q&A、ガイド付き、自動移行）を確認してから、案内に従って次の資料を参照してください。

• heroku-concepts.md — Heroku 設定ファイルのスキーマ、CLI コマンド、ビルドパックの検出、パイプライン構成
• heroku-mapping.md — コンポーネントの種類、ビルド設定、環境変数、インスタンスサイズ、ネットワーク、リージョン
• heroku-addons.md — app.json からのアドオン検出、DO マネージドサービスに相当するもの、外部の代替サービス
• heroku-workflows.md — Q&A、ガイド付き、自動移行モードの手順

クイックマッピング（Heroku）

Heroku	App Platform
web プロセス	services
worker プロセス	workers
release フェーズ	jobs（PRE_DEPLOY）
heroku-postgresql	Managed Postgres
heroku-redis	Managed Valkey
Config Vars	GitHub Secrets
Pipelines	GitHub Actions
Review Apps	プレビュー環境
Heroku Scheduler	jobs（CRON_TRIGGER）

マッピングの全容：heroku-mapping.md を参照してください。

---

クイックマッピングリファレンス

Docker Compose

Docker Compose	App Platform
services.<name>.ports	services
services.<name>（ポートなし）	workers
services.postgres	Managed Postgres
services.redis	Managed Valkey
volumes	Spaces（永続ボリュームはありません）

マッピング表の全容：platform-mappings.md を参照してください。

---

マッピングできない項目（クイックリファレンス）

移行元	問題	選択肢
CloudFront CDN	DO CDN なし	外部 CDN（Cloudflare）を使用するか、スキップ
AWS Secrets Manager	モデルが異なる	GitHub Secrets
永続ボリューム	非対応	ファイルには Spaces、データにはマネージド DB
ARM コンテナ	AMD64 のみ	AMD64 向けに再ビルド

全項目の一覧：platform-mappings.md を参照してください。

---

出力アーティファクト

ファイル	用途
.do/app.yaml	App Platform の仕様
.do/deploy.template.yaml	DO へデプロイボタン
MIGRATION.md	移行チェックリストとステータス
.env.example	環境変数テンプレート

アプリ仕様テンプレート：app-spec-generation.md を参照してください。

---

スクリプト

スクリプト	用途
scripts/detect_platform.py	ファイルから移行元プラットフォームを検出
scripts/analyze_architecture.py	アプリケーションアーキテクチャを分析
scripts/generate_app_spec.py	.do/app.yaml を生成
scripts/generate_checklist.py	移行チェックリストを生成

---

リファレンスファイル

Heroku（詳細編）

• heroku-overview.md - 入り口：Heroku から移行する場合は最初にお読みください
• heroku-concepts.md - Procfile、app.json、heroku.yml、パイプライン、CLI
• heroku-mapping.md - Heroku から App Platform への機能マッピングの詳細
• heroku-addons.md - アドオンエコシステムのマッピング（Postgres、Redis など）
• heroku-workflows.md - 移行ワークフロー：Q&A、ガイド付き、自動移行

一般

• platform-mappings.md - すべてのプラットフォームの検出、マッピングテーブル、注意点
• code-refactoring.md - 環境変数の更新、S3／Valkey の移行、データ移行
• workflow-examples.md - Docker Compose、AWS ECS の手順
• app-spec-generation.md - テスト／本番環境の仕様テンプレート、デフォルト設定

---

よくある問題（簡単な修正方法）

問題	原因	修正方法
アプリ仕様の検証に失敗する	無効な YAML	インデントと doctl apps spec validate を確認してください
データベース接続に失敗する	URL 形式が正しくない	${db.DATABASE_URL} バインディングを使用してください
ビルドに失敗する	依存関係が不足している	Dockerfile のビルド依存関係を確認してください
ポートのバインドに失敗する	PORT の処理が正しくない	$PORT または 0.0.0.0:8080 にバインドしてください
ヘルスチェックに失敗する	パスが正しくない	/health エンドポイントが存在することを確認してください

トラブルシューティングの詳細：code-refactoring.md を参照してください。

---

他のスキルとの連携

• → deployment：移行後の GitHub Actions ワークフロー
• → postgres：複雑なデータベース設定、スキーマの分離
• → devcontainers：移行後のローカル開発環境
• → troubleshooting：移行に関する問題をデバッグするためのコンテナ

---

ドキュメントへのリンク

• アプリ仕様リファレンス
• Heroku 移行ガイド
• DO へデプロイボタン