aws-transform

AWS Transform (ATX)

概要

AWS Transform（ATX）を使用して、コードのアップグレード、移行、変換を実行します。 あらゆる形式間の変換に対応しています。言語バージョンのアップグレード（Java、Python、Node.js など）、 フレームワークの移行、AWS SDK の移行、ライブラリのアップグレード、コードのリファクタリング、アーキテクチャの 変更、組織固有のカスタム変換が可能です。

2 つの実行モードがあります。

• ローカルモード：ユーザーのマシンで ATX CLI を直接実行します。1～9 個のリポジトリに最適です。
• リモートモード：AWS Batch/Fargate コンテナを介して、大規模に変換を実行します。 10 個以上のリポジトリ、またはクラウドでの実行を希望する場合に最適です。インフラストラクチャは ユーザーの同意を得て自動的にデプロイされます。

リポジトリの調査、利用可能な変換定義との照合、設定の収集、いずれかのモードでの変換実行まで、 ワークフロー全体を処理します。ユーザーはリポジトリを指定し、計画を確認するだけです。

挨拶して待機

有効化されたら、AWS Transform を以下の正確なテキストで紹介します。上記の 概要テキストは参考情報にすぎないため、ユーザーには表示しないでください。

「世界のインフラストラクチャとソフトウェアを近代化するエージェントを、お好みの AI アシスタントから利用できるようになりました。

AWS Transform は、インフラストラクチャの移行、メインフレームの近代化、継続的な技術的負債の削減における 長年にわたる変革作業を数か月に圧縮する、包括的な近代化ファクトリーです。現在、この スキルでは、拡大を続けるプレイブックライブラリの第一弾である AWS Transform custom を 利用できます。

AWS Transform custom でできること：

• Java、Python、Node.js を最新バージョンにアップグレード
• AWS SDK を移行（Java SDK v1→v2、boto2→boto3、JS SDK v2→v3）
• フレームワークの移行、ライブラリのアップグレード、コードのリファクタリング
• コードベースを分析し、ドキュメントを生成
• 自然言語、ドキュメント、コードサンプルを使って、独自の変換を定義して実行

少数のリポジトリでローカル実行してすばやく反復することも、数百のリポジトリを対象に大規模に実行することもできます（最大 128 個を並列実行）。注：このスキルはテレメトリを収集します。オプトアウトするには、https://docs.aws.amazon.com/transform/latest/userguide/transform-usage-telemetry.html をご覧ください。

今日は何を変換しますか？」

ユーザーからの応答があるまで、ファイルの調査、コマンドの実行、前提条件の確認は一切行わないでください。

使用方法

ユーザーが次のことを希望する場合に使用します。

• コード（Java、Python、Node.js など）を変換、アップグレード、移行する
• AWS SDK を移行する（Java SDK v1→v2、boto2→boto3、JS SDK v2→v3 など）
• AWS Batch/Fargate を介して大規模にコードを一括変換する
• リポジトリにどの ATX 変換を適用できるか分析する
• コードベースを包括的に分析する
• 新しいカスタム変換定義（TD）を作成する

主な概念

• 変換定義（TD）：atx custom def list --json で検出される、再利用可能な変換レシピ
• 一致レポート：コードの検査に基づき、リポジトリと適用可能な TD の対応付けを自動生成したもの
• ローカルモード：ユーザーのマシンで ATX CLI を実行します（1～9 個のリポジトリ、同時実行は最大 3 個）
• リモートモード：AWS Batch/Fargate で変換を実行します（10 個以上のリポジトリ、またはユーザーの希望による）

基本方針

ユーザーを待ちます。有効化されたら、このスキルでできることを説明し、ユーザーが何を 達成したいか尋ねてください。ユーザーが作業対象のリポジトリを明示するまでは、作業ディレクトリ、 ファイル、リポジトリを自動的に調査しないでください。

ユーザーがリポジトリを指定したら、尋ねるのではなく照合してください。指定されたリポジトリを 調査し、適用できる変換を自動的に提示します。TD の一覧をそのまま見せて ユーザーに選ばせてはいけません。

前提条件

前提条件の確認は、セッション開始時に 1 回だけ実行します。リポジトリごとに繰り返さないでください。 ユーザーが実行したい内容を明示するまでは、前提条件を確認しないでください。

0. プラットフォームの確認（必須 — すべてのモード）

ユーザーのオペレーティングシステムを検出します。Windows（WSL ではない）の場合は、直ちに停止して次の内容をユーザーに伝えます。

AWS Transform custom はネイティブ Windows をサポートしていません。
Windows Subsystem for Linux（WSL）をインストールし、WSL 内から実行する必要があります。

WSL をインストールするには、PowerShell を管理者として実行し、wsl --install を実行してから再起動してください。
その後、WSL ターミナルを開き、そこからこのスキルを再実行してください。

次のコマンドを実行して確認します。

uname -s

• Linux または Darwin → 通常どおり続行します
• MINGW*、MSYS*、CYGWIN*、または Windows と思われる出力 → 処理を中断し、上記の WSL メッセージを表示します
• コマンドが失敗する、エラーになる、または見つからない → ネイティブ Windows と判断し、処理を中断して上記の WSL メッセージを表示します

ネイティブ Windows では、ほかの手順に進まないでください。

1. AWS CLI（必須 — すべてのモード）

aws --version

インストールされていない場合は、ユーザーに次の手順を案内します。

• macOS：brew install awscli または curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg" && sudo installer -pkg AWSCLIV2.pkg -target /
• Linux：curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && unzip awscliv2.zip && sudo ./aws/install

aws --version が成功するまで、先に進まないでください。

2. AWS 認証情報（必須 — すべてのモード）

aws sts get-caller-identity

認証情報が設定されていない場合は、ユーザーに設定方法を案内します。

AWS Transform custom requires AWS credentials to authenticate with the service. Configure authentication using one of the following methods.

1. AWS CLI Configure (~/.aws/credentials):
   aws configure

2. AWS Credentials File (manual). Configure credentials in ~/.aws/credentials:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

3. Environment Variables. Set the following environment variables:

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token

You can also specify a profile using the AWS_PROFILE environment variable:

export AWS_PROFILE=your_profile_name

認証情報が検証されるまで、先に進まないでください。設定後に aws sts get-caller-identity を再実行します。

注：export で設定した環境変数は、シェルセッション間で引き継がれません。エージェントが新しいシェルを起動すると、環境変数として設定した認証情報が失われることがあります。永続化するには、aws configure または ~/.aws/credentials を使用してください。

3. ATX CLI（必須 — すべてのモード）

TD の検出（atx custom def list --json）には、すべてのモードで必要です。
ローカルモードでは、変換の実行にも使用します。

atx --version
# Install: curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash

必須：最近実行した場合でも、毎セッションの開始時に必ず atx update を一度実行してください。 これにより、新しい ATX CLI バージョンや新しい TD を検出できます。ほかの ATX コマンド（atx custom def list --json を含む）より先に実行してください。

atx update

この手順を省略しないでください。更新するかどうかをユーザーに尋ねないでください。CLI に更新が「必要」かどうかによって実行するかを判断しないでください。必ず実行してください。

4. IAM 権限（必須 — すべてのモード）

ローカルモードには、最低限 transform-custom:* が必要です。TD の一覧を実行して確認してください。

atx custom def list --json

成功した場合、必要な権限があるため、このセクションの残りはスキップしてください。

権限エラーで失敗した場合、呼び出し元には transform-custom:* の IAM 権限が必要です。必要な権限をユーザーに説明し、続行する前に確認を取ってください。

ATX CLI を使用するには、ユーザーの ID に transform-custom:* 権限が必要です。
AWS 管理ポリシー AWSTransformCustomFullAccess をユーザーの ID にアタッチできます。進めてもよろしいですか？

ユーザーの確認を得た後に限り、管理ポリシーをアタッチします。

CALLER_ARN=$(aws sts get-caller-identity --query Arn --output text)
if echo "$CALLER_ARN" | grep -q ":user/"; then
  IDENTITY_NAME=$(echo "$CALLER_ARN" | awk -F'/' '{print $NF}')
  aws iam attach-user-policy --user-name "$IDENTITY_NAME" \
    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
elif echo "$CALLER_ARN" | grep -Eq ":assumed-role/|:role/"; then
  ROLE_NAME=$(echo "$CALLER_ARN" | sed 's/.*:\(assumed-\)\{0,1\}role\///' | cut -d'/' -f1)
  aws iam attach-role-policy --role-name "$ROLE_NAME" \
    --policy-arn "arn:aws:iam::aws:policy/AWSTransformCustomFullAccess"
fi

アタッチコマンド自体が失敗した場合（IAM 権限が不足している場合や、SSO 管理ロールの場合など）、ユーザーに AWS 管理者へ依頼し、AWS 管理ポリシー AWSTransformCustomFullAccess を自身の ID にアタッチしてもらう必要があることを伝えてください。SSO ユーザー（ロール名が AWSReservedSSO_ で始まる場合）は、IAM Identity Center のアクセス許可セットに追加する必要があります。直接アタッチすることはできません。

atx custom def list --json が成功するまで、先に進まないでください。

リモートモードには、追加の権限（Lambda の呼び出し、S3、KMS、Secrets Manager、CloudWatch）が必要です。これらはデプロイのワークフローの一部として生成され、アタッチされます。詳しくは references/remote-execution.md を参照してください。

権限の一覧については、references/cli-reference.md を参照してください。

5. AWS CDK（リモートモードのみ）

リモートインフラストラクチャのデプロイに必要です。インストールされているか確認してください。

cdk --version

インストールされていない場合は、グローバルにインストールしてください。

npm install -g aws-cdk

cdk --version が成功するまで、リモートデプロイに進まないでください。

6. リモートインフラ（リモートモードのみ — 対応保留）

ユーザーがリモートモードを選択した場合にのみ確認します。インフラストラクチャの CDK スクリプトは、実行時に https://github.com/aws-samples/aws-transform-custom-samples.git をクローンして取得します（ブランチは atx-remote-infra）。このスキルには含まれていません。references/remote-execution.md を参照してください。

ワークフロー

セッションのタイムスタンプを一度生成し、このセッションのすべてのパスで再利用します。

SESSION_TS=$(date +%Y%m%d-%H%M%S)

ステップ 1：リポジトリを収集する

ユーザーにローカルパスまたは Git URL を尋ねます。1 つでも複数でも受け付けます。現在の作業ディレクトリやエディターで開いているファイルが対象だと決めつけず、ユーザーが明示的にリポジトリを指定するまで待ちます。

受け付けるソース形式：

• ローカルパス — ユーザーのマシン上のディレクトリ（例：/home/user/my-project）
• HTTPS Git URL — パブリックまたはプライベート（例：https://github.com/org/repo.git）
• SSH Git URL — 例：[email protected]:org/repo.git
• zip ファイルを含む S3 バケットパス — 例：s3://my-bucket/repos/。リポジトリの zip ファイルを含みます。各 zip が 1 つの変換ジョブになります。

S3 バケット入力

ユーザーが zip ファイルを含む S3 パスを指定した場合、（まだ指定されていなければ）希望する実行モードを尋ねます。S3 入力はどちらのモードでも使用できます。

リモートモード： ユーザーのバケットから管理対象のソースバケットに zip ファイルをコピーし、管理対象のコピーを指定してジョブを送信します。

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
SOURCE_BUCKET="atx-source-code-${ACCOUNT_ID}"

# List all zips in the user's bucket path
aws s3 ls s3://user-bucket/repos/ --recursive | grep '\.zip$'

# Copy each zip to the managed source bucket
aws s3 sync s3://user-bucket/repos/ s3://${SOURCE_BUCKET}/repos/ --exclude "*" --include "*.zip"

その後、zip ごとに 1 つのジョブを含むバッチジョブを送信し、それぞれで s3://${SOURCE_BUCKET}/repos/<filename>.zip を指定します。コンテナが zip ファイルを自動的に展開します。バッチ送信については、references/multi-transformation.md を参照してください。管理対象のソースバケットには 7 日間のライフサイクルが設定されており、コピーした zip ファイルは自動的に削除されます。

ローカルモード： 各 zip ファイルをローカルにダウンロードして展開します。

mkdir -p ~/.aws/atx/custom/atx-agent-session/repos
aws s3 sync s3://user-bucket/repos/ ~/.aws/atx/custom/atx-agent-session/repos/ --exclude "*" --include "*.zip"
for zip in ~/.aws/atx/custom/atx-agent-session/repos/*.zip; do
  name=$(basename "$zip" .zip)
  unzip -qo "$zip" -d "$HOME/.aws/atx/custom/atx-agent-session/repos/${name}-$SESSION_TS/"
done

展開したディレクトリを、ローカル実行時の <repo-path> として使用します。標準のローカルモードの制限が適用されます（同時に実行できるリポジトリは最大 3 つです）。

プライベートリポジトリの検出（リモートモード）

必ずユーザーに確認してください。リポジトリが公開か非公開かを自分で判断しようとしてはいけません。URL をクローン、curl、またはプローブして、公開か非公開かを確認しようとしてはいけません。ユーザーに尋ねるだけにしてください。ユーザーが git URL を提示し、リモートモードが選択された場合（または選択される可能性が高い場合）は、すぐに次のように尋ねてください。

"これらのリポジトリの中にプライベートなものはありますか？ある場合、リモートコンテナでクローンするには認証情報が必要です。設定方法をご案内します。"

この質問を省略してはいけません。クローン、curl、その他のネットワークリクエストを試して、公開か非公開かを推測してはいけません。尋ねるだけにしてください。

ユーザーがリポジトリはプライベートだと確認した場合は、URL の形式に基づいて認証情報の種類を判断します。

まず、リージョンを確認します（以下の Secrets Manager コマンドすべてで使用します）。

REGION=${AWS_REGION:-${AWS_DEFAULT_REGION:-$(aws configure get region 2>/dev/null)}}
REGION=${REGION:-us-east-1}

HTTPS URL の場合 — GitHub PAT がすでに設定されているか確認します。

aws secretsmanager describe-secret --secret-id "atx/github-token" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

CONFIGURED の場合は、ユーザーに「GitHub PAT はすでに保存されています。このまま使用しますか、それとも新しいものに置き換えますか？」と尋ねてください。置き換える場合は、次のコマンドを実行するよう伝えてください。

aws secretsmanager put-secret-value --secret-id "atx/github-token" --region "$REGION" --secret-string "YOUR_TOKEN_HERE"

NOT_CONFIGURED の場合は、必要なものを説明し、作成コマンドを実行するよう伝えてください。

"プライベートな HTTPS リポジトリには、AWS Secrets Manager に保存された GitHub Personal Access Token（PAT）が必要です。リモートコンテナは起動時にこれを取得して、リポジトリをクローンします。トークンは AWS アカウント内に保存され、いつでも削除できます。

プライベートリポジトリには、PAT に repo スコープが必要です。https://github.com/settings/tokens で作成し、次のコマンドを実行してください。

aws secretsmanager create-secret --name "atx/github-token" --region "$REGION" --secret-string "YOUR_TOKEN_HERE"

削除する場合：aws secretsmanager delete-secret --secret-id atx/github-token --region "$REGION" --force-delete-without-recovery"

チャットにトークンを貼り付けるようユーザーに求めてはいけません。コマンドはユーザー自身に実行してもらいます。 完了したことをユーザーが確認するまで待ってから、次のコマンドで検証します。

aws secretsmanager describe-secret --secret-id "atx/github-token" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

SSH URL の場合（git@... または ssh://...）— SSH キーが設定されているか確認します。

aws secretsmanager describe-secret --secret-id "atx/ssh-key" --region "$REGION" 2>/dev/null \
  && echo "CONFIGURED" || echo "NOT_CONFIGURED"

CONFIGURED の場合は、ユーザーに「SSH キーはすでに保存されています。このまま使用しますか、それとも新しいものに置き換えますか？」と尋ねてください。置き換える場合は、次のコマンドを実行するよう伝えてください。

aws secretsmanager put-secret-value --secret-id "atx/ssh-key" --region "$REGION" --secret-string "$(cat <path-to-your-private-key>)"

NOT_CONFIGURED の場合は、必要なものを説明し、作成コマンドを実行するよう伝えてください。

"SSH リポジトリには、AWS Secrets Manager に保存された SSH 秘密鍵が必要です。リモートコンテナは起動時にこれを取得して、リポジトリをクローンします。

次のコマンドを実行してください。

aws secretsmanager create-secret --name "atx/ssh-key" --region "$REGION" --secret-string "$(cat <path-to-your-private-key>)"

削除する場合：aws secretsmanager delete-secret --secret-id atx/ssh-key --region "$REGION" --force-delete-without-recovery"

チャットに SSH キーを貼り付けるようユーザーに求めてはいけません。コマンドはユーザー自身に実行してもらいます。

ローカルモードでは、プライベートリポジトリの認証情報は不要です。ユーザーのローカル git 設定で認証できます。ローカルモードでは、この確認を完全に省略してください。

ステップ 2：TD を検出する（サイレント）

サイレントに実行します。出力をユーザーに表示してはいけません。

atx custom def list --json

JSON 出力を直接確認し、利用可能な TD の内部参照情報を作成します。 出力を python、jq、その他の解析スクリプトにパイプしてはいけません。JSON は自分で読み取ってください。 TD 名をハードコードしてはいけません。

新しい TD の作成

ユーザーが明示的に TD の作成を依頼した場合： プログラムで作成しようとしてはいけません。ユーザーに次のように伝えてください。

新しい Transformation Definition を作成するには、新しいターミナルを開いて次を実行してください。

atx -t

これにより、作成したい変換内容（例：「すべてのロギングを log4j から SLF4J に移行する」、「Spring Boot 2 を Spring Boot 3 にアップグレードする」）を説明する対話セッションが開始されます。ATX CLI が TD の定義とテストを案内し、その後 AWS アカウントに公開します。

公開が完了したら、ここに戻ってきてください。利用可能な TD をスキャンした際に、自動的に取り込みます。

ユーザーの目的に一致する既存の TD がない場合： TD の作成に黙って誘導してはいけません。一致判定が不完全な場合もあります。代わりに、まずユーザーに確認してください。

「[ユーザーの目的を説明] に対応する既存の TD が見つかりませんでした。新しい TD を作成しますか？」

ユーザーが確認した場合にのみ、atx -t の手順を示してください。ユーザーが断った場合は、探しているものを明確にするよう尋ねてください。ユーザーが TD 名を知っているか、別の方法を希望している可能性があります。

atx -t を自分で実行してはいけません。エージェントが操作できない対話型ターミナルセッションが必要です。ユーザー自身が別のターミナルで手動実行する必要があります。

ユーザーが TD の作成後に戻ってきたら、atx custom def list --json を再実行して新たに公開された TD を取得し、通常のワークフローを続行してください。

ステップ 3：各リポジトリを調査する

軽量な調査のみを実行してください。主要な兆候について設定ファイルを確認します。

兆候	確認するファイル	推定される TD の種類
Python のバージョン	.python-version、pyproject.toml、setup.cfg、requirements.txt	Python バージョンのアップグレード
Java のバージョン	pom.xml（<java.version>）、build.gradle（sourceCompatibility）、.java-version	Java バージョンのアップグレード
Node.js のバージョン	package.json（engines.node）、.nvmrc、.node-version	Node.js バージョンのアップグレード
Python boto2	import boto（boto3 ではない）	boto2→boto3 の移行
Java SDK v1	com.amazonaws のインポート、pom.xml 内の aws-java-sdk	Java SDK v1→v2
Node.js SDK v2	package.json 内の "aws-sdk"（@aws-sdk ではない）	JS SDK v2→v3
x86 Java	Dockerfile、ビルド設定内の x86_64／amd64	Graviton への移行

検出した兆候をステップ 2 の TD と照合します。ユーザーのアカウントに実際に存在する TD のみを一致対象にしてください。

検出コマンドの詳細は、references/repo-analysis.md を参照してください。

ステップ 4：一致レポートを提示する

形式：

Transformation Match Report
=============================
Repository: <name> (<path>)
  Language: <lang> <version>
  Matching TDs:
    - <td-name> — <description>

Summary: N repos analyzed, M have applicable transformations (T total jobs)

一致レポートを提示し、続行前にユーザーの確認を待ってください。ユーザーの明示的な同意なしに、変換を開始してはいけません。

ステップ 5：設定を収集する

計画に関する追加の背景情報（アップグレード TD の対象バージョンなど）をユーザーに尋ねてください。これは必須です。TD で設定が厳密には必要ない場合でも、必ず尋ねてください。エージェントが把握していない希望や制約がユーザーにある可能性があります。ユーザーが追加情報は不要だと明示した場合にのみ省略してください。

ステップ 6：ランタイムの互換性を検証する（リモートとローカル）

リモートモード

リモートジョブを送信する前に、事前ビルド済みイメージが対象のランタイムをカバーしているか、カスタム Docker ビルドが必要かを判断してください。

事前ビルド済みイメージに含まれるもの：

• Java：8、11、17、21、25（Amazon Corretto）、Maven、Gradle 9.4
• Python：3.8、3.9、3.10、3.11、3.12、3.13、3.14（dnf + pyenv）
• Node.js：16、18、20、22、24（nvm）、yarn、pnpm、TypeScript、ts-node
• ビルドツール：gcc、g++、make、patch
• CLI ツール：AWS CLI v2、ATX CLI、git、jq、curl、unzip、tar
• OS：Amazon Linux 2023（x86_64）

判断方法：

1. 変換要件（ソースランタイム、ターゲットランタイム、ビルドツール、その他の依存関係）に基づいて、必要なものがすべて上記の事前ビルド済みイメージで利用できるか判断します。
2. はいの場合 → 事前ビルド済みイメージのパスを使用します（Docker は不要です）。references/remote-execution.md にある事前ビルド済みイメージの手順に従って、デプロイに進みます。
3. いいえの場合 → カスタムイメージのパスを使用します（Docker が必要です）。ユーザーに次のように伝えます。

リモートコンテナには [language/tool version] が含まれていません。この変換をリモートで実行するには、カスタムコンテナイメージをビルドする必要があります。お使いのマシンに Docker がインストールされ、実行されている必要があります。一度だけの変更で、所要時間は約 5～10 分です。進めてもよろしいですか？

ユーザーが承諾した場合は、references/remote-execution.md のカスタムイメージのパスに従います。prebuiltImageUri をクリアし、Dockerfile をカスタマイズして、デプロイします。

ユーザーが断った場合は、代替案としてローカルモードを提案します（必要なツールがそのマシンで利用できる場合）。

Dockerfile のカスタマイズ（カスタムイメージのパスのみ）：

まず、Dockerfile を読み、インストール済みのものを確認します。

ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra"
cat "$ATX_INFRA_DIR/container/Dockerfile" 2>/dev/null

1. インフラストラクチャリポジトリがクローン済みで、最新の状態であることを確認します。

   ATX_INFRA_DIR="$HOME/.aws/atx/custom/remote-infra"
   if [ -d "$ATX_INFRA_DIR" ]; then
     git -C "$ATX_INFRA_DIR" add -A
     git -C "$ATX_INFRA_DIR" commit -m "Local customizations" -q 2>/dev/null || true
     git -C "$ATX_INFRA_DIR" pull -q
   else
     git clone -b atx-remote-infra --single-branch https://github.com/aws-samples/aws-transform-custom-samples.git "$ATX_INFRA_DIR"
   fi
   

   git pull でマージの競合が報告された場合は、Dockerfile の CUSTOM LANGUAGES AND TOOLS セクションで、上流の変更とユーザーのカスタマイズの両方を維持して競合を解決し、マージをコミットします。

2. $ATX_INFRA_DIR/container/Dockerfile を編集します。# CUSTOM LANGUAGES AND TOOLS というマークのあるセクションを見つけ、コメントブロックの後、USER root 行の前に RUN コマンドを挿入します。

   すでにインストールされている言語の不足バージョンについては、カスタムセクションにバージョンを追加します。例：

   # Java 23 (Amazon Corretto — direct install, must run as root)
   # Do NOT use dnf in the custom section — pyenv overrides the system python3
   # that dnf depends on, causing "No module named 'dnf'" errors.
   USER root
   RUN curl -fsSL "https://corretto.aws/downloads/latest/amazon-corretto-23-x64-linux-jdk.tar.gz" -o /tmp/corretto23.tar.gz && \
       mkdir -p /usr/lib/jvm && \
       tar -xzf /tmp/corretto23.tar.gz -C /usr/lib/jvm && \
       rm /tmp/corretto23.tar.gz && \
       ln -sfn /usr/lib/jvm/amazon-corretto-23.* /usr/lib/jvm/corretto-23
   
   # Node.js 23 (via nvm — must run as atxuser)
   USER atxuser
   RUN . /home/atxuser/.nvm/nvm.sh && nvm install 23
   USER root
   
   # Python 3.15 (via pyenv — must run as atxuser)
   USER atxuser
   RUN eval "$(/home/atxuser/.pyenv/bin/pyenv init -)" && \
       MAKE_OPTS="-j$(nproc)" /home/atxuser/.pyenv/bin/pyenv install 3.15.0
   USER root
   

   新しい言語を追加する場合は、カスタムセクションで dnf を使用しないでください。pyenv が、dnf が依存するシステムの python3 を上書きするためです。代わりに、言語固有のインストーラーを使用します。

   # Go
   RUN curl -fsSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -C /usr/local -xz
   ENV PATH="/usr/local/go/bin:$PATH"
   
   # Ruby (via rbenv — must run as atxuser)
   USER atxuser
   RUN git clone --depth 1 https://github.com/rbenv/rbenv.git /home/atxuser/.rbenv && \
       git clone --depth 1 https://github.com/rbenv/ruby-build.git /home/atxuser/.rbenv/plugins/ruby-build && \
       /home/atxuser/.rbenv/bin/rbenv install 3.3.0 && \
       /home/atxuser/.rbenv/bin/rbenv global 3.3.0
   ENV PATH="/home/atxuser/.rbenv/shims:/home/atxuser/.rbenv/bin:$PATH"
   USER root
   
   # Rust
   USER atxuser
   RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
   ENV PATH="/home/atxuser/.cargo/bin:$PATH"
   USER root
   

3. $ATX_INFRA_DIR/container/entrypoint.sh のバージョンスイッチャーを更新します。該当する switch_*_version 関数を見つけ、新しいバージョンの case を追加します。直接ダウンロードでインストールした Java バージョンの場合は、/usr/lib/jvm/ にある展開先ディレクトリ名を確認します。たとえば、Java 23 を追加するには次のようにします。

   # In switch_java_version(), add to the case statement:
   23) java_home="/usr/lib/jvm/corretto-23" ;;
   

   実際のディレクトリ名を確認します：ls /usr/lib/jvm/ — インストールしたバージョンに一致するディレクトリを使用します。

   Node.js の場合、nvm が任意のバージョンを自動的に処理するため、エントリーポイントの変更は不要です。Python の場合、pyenv が任意のバージョンを処理するため、エントリーポイントの変更は不要です（既存の pyenv のフォールバックロジックが見つけます）。

4. デプロイ（または再デプロイ）します：cd "$ATX_INFRA_DIR" && ./setup.sh CDK は container/ ディレクトリのハッシュを計算します。ファイルに変更があると、自動的に再ビルドされ、ECR にプッシュされます。

再デプロイ後、ジョブの environment フィールドに対象バージョンを正確に設定します（例："JAVA_VERSION":"23"。"21" ではありません）。エントリーポイントのバージョンスイッチャーはこの値を読み取り、適切なランタイムを有効にします。

ユーザーが断った場合は、代替案としてローカルモードを提案します（必要なツールがそのマシンで利用できる場合）。

ローカルモード

ローカルで変換を実行する前に、ユーザーが対象のランタイムバージョンをインストール済みであることを確認してください。これは、変換対象となるあらゆる言語やランタイム（Java、Python、Node.js、Ruby、Go、Rust、.NET など）に適用されます。TD が必要とするランタイムの現在のバージョンを確認してください。例：

java -version    # Java transformations
python3 --version # Python transformations
node --version   # Node.js transformations
ruby --version   # Ruby transformations
go version       # Go transformations

対象のバージョンが有効になっていない場合は、すでにインストールされているか確認してください。

# Java: check common install locations
/usr/libexec/java_home -V 2>&1          # macOS
ls /usr/lib/jvm/ 2>/dev/null            # Linux
# Python: check if the specific version binary exists
which python3.12 2>/dev/null            # adjust version as needed
# Node.js: check if nvm is available, or look for the binary
command -v nvm &>/dev/null && nvm ls 2>/dev/null
which node 2>/dev/null && node --version

対象のバージョンが見つかった場合は、そのバージョンに切り替えます。

• Java：export JAVA_HOME=<path to JDK> && export PATH="$JAVA_HOME/bin:$PATH"
• Python：pyenv shell 3.15.0
• Node.js：nvm use 23

対象のバージョンがインストールされていない場合に限り、インストール前にユーザーの許可を求めてください。ユーザーの明示的な確認なしにランタイムをインストールしてはいけません。 適切なバージョンマネージャーを提案してください。

• Java：brew install --cask corretto23（macOS）、sudo yum install java-23-amazon-corretto-devel（RHEL/AL2）、または sudo apt install java-23-amazon-corretto-jdk（Debian/Ubuntu）
• Python：pyenv install 3.15.0 && pyenv shell 3.15.0、または brew install [email protected]
• Node.js：nvm install 23 && nvm use 23

ビルドとテストを正しく実行できるよう、アクティブなランタイムは変換の対象バージョンと一致している必要があります。正しいバージョンが有効になるまで、変換を進めてはいけません。

ステップ 7：変換計画の確認

リポジトリ、TD、設定、実行モードを含む最終計画を提示してください。ユーザーが確認するまで、先に進んではいけません。

ステップ 8：実行

atx custom def exec を実行する際は、必ず --telemetry を含めてください（テレメトリーのセクションを参照）。

リモートモードでは、まず CloudFormation を使用してインフラストラクチャのデプロイ状況を確認してください（references/remote-execution.md の「インフラストラクチャの確認」セクションを参照）。Lambda 関数名を調べてデプロイ状況を確認してはいけません。

• 1 つのリポジトリ：references/single-transformation.md を参照
• 複数のリポジトリ：references/multi-transformation.md を参照

実行モード

モード	最適な用途	前提条件
ローカル（1～9 個のリポジトリでのデフォルト）	素早い変換、ATX を導入済みの開発マシン	ATX CLI のインストール
リモート（10 個以上のリポジトリで推奨）	一括変換、最大 512 個のリポジトリ（バッチあたり同時実行 128 個）	AWS アカウント、自動デプロイされるインフラストラクチャ

モードの推定：

• ユーザーが「local」／「here」／「on my machine」と言った場合 → ローカル（リポジトリ数に関係なく要望に従います）
• ユーザーが「remote」／「cloud」／「AWS」／「batch」／「at scale」と言った場合 → リモート
• リポジトリが 10 個以上で希望の指定がない場合 → リモートを推奨し、ローカルの同時実行上限が 3 個であることを説明します
• リポジトリが 1～9 個で希望の指定がない場合 → ローカルを選び、リモートも利用可能であることを伝えます

インフラストラクチャのセットアップについては、references/remote-execution.md を参照してください。

重要なルール

1. TD を動的に検出する — 常に atx custom def list --json を実行してください。TD 名をハードコードしないでください。
2. 確認を求めずに一致するものを提示する — リポジトリを調べ、一致するものを提示してください。TD の一覧をそのまま表示しないでください。
3. 軽量な調査にとどめる — 設定ファイルと主要なシグナルを確認してください。詳細な分析は行わないでください。
4. 実行前に確認する — TD、リポジトリ、設定について、必ず先にユーザーの確認を得てください。
5. 所要時間を見積もらない — 所要時間の予測を含めないでください。
6. 並列実行 — ローカルでは同時に実行するリポジトリは最大 3 件です。リモートでは、Lambda 呼び出し 1 回につき最大 128 件のジョブに分けて送信してください（1 セッションあたり最大 512 リポジトリ）。
7. 出力を保持する — 生成された出力フォルダーを削除しないでください。
8. リポジトリが 10 件以上ならリモートを推奨する — リポジトリが 1～9 件の場合はローカルをデフォルトとします。10 件以上の場合はリモートを推奨してください。ユーザーの希望は常に尊重してください。
9. クラウドリソースにはユーザーの同意を得る — ユーザーの明示的な確認なしに、インフラストラクチャをデプロイしないでください。
10. シェルでの引用符の使用 — シェルコマンドを組み立てる際は、次の点に従ってください。
    • JSON ペイロードには一重引用符を使用します。例：--payload '{"key":"value"}'
    • --configuration には一重引用符を使用します。例：--configuration 'additionalPlanContext=Target Java 21'
    • 二重引用符の中に二重引用符を入れないでください。これにより dquote> で停止します。
    • aws lambda invoke では、必ず --payload '<json>' --cli-binary-format raw-in-base64-out を使用してください。
    • 実行前に、組み立てたすべてのコマンドで引用符が正しく対応していることを確認してください。
    • Lambda ジョブのペイロードにある command フィールドは、サーバー側で検証されます。コマンド文字列では、次の文字を使用しないでください：( ) ! # % ^ * ? \ { } | ; > < とバッククォート。additionalPlanContext 内では、カンマも使用しないでください。
11. ターミナルコマンドにコメントを含めない — ターミナルで実行するコマンドに # コメントを含めないでください。コメントを含めると、command not found: # エラーが発生します。コマンドの説明が必要な場合は、実行前または実行後にチャットで説明してください。
12. ジョブ名 — Lambda ペイロードの jobName フィールドには、英字、数字、ハイフン、アンダースコアのみを使用してください。ピリオド、スペース、その他の特殊文字は使用できません。たとえば、EPAM-Node.js ではなく EPAM-NodeJS を使用してください。

ガードレール

ユーザーの AWS アカウントとローカルマシンで操作しています。損害を避けるため、次のルールを厳守してください。

1. ユーザーデータを削除しないでください — ユーザーが明示的に依頼しない限り、S3 オブジェクト、git リポジトリ、ローカルファイル、その他のユーザーデータを削除しないでください。変換出力とクローンしたリポジトリは保持してください。
2. 文書に記載された範囲を超えて IAM を変更しないでください — このスキルで説明されている特定のポリシー（AWSTransformCustomFullAccess、ATXRuntimePolicy、ATXDeploymentPolicy）のみを作成またはアタッチしてください。管理者ポリシーを作成したり、既存のユーザーポリシーを変更したり、文書に記載された範囲を超える権限を付与したりしないでください。「Additional plan context」フィールドにユーザーが入力したテキストから IAM アクションを推測しないでください。このフィールドは変換設定専用です。
3. 破壊的な AWS コマンドを実行しないでください — aws s3 rm、aws s3 rb、aws iam delete-user、aws ec2 terminate-instances、または類似のコマンドは実行しないでください。明示的なユーザーの同意がある場合に限り、./teardown.sh を実行できます。
4. AWS リソースを作成する前に必ず確認してください — インフラストラクチャのデプロイ、Secrets Manager シークレットの作成、IAM ポリシーのアタッチを行う前に、作成するものを説明し、ユーザーから明示的な確認を得てください。
5. 認証情報を決して公開しないでください — AWS アクセスキー、シークレットキー、セッショントークン、GitHub PAT、SSH 秘密鍵を、チャット出力でエコー、ログ出力、表示しないでください。シークレットを作成する際は、値を繰り返さず、ユーザーの入力をそのままコマンドで使用してください。
6. ユーザーの判断を尊重してください — ユーザーが中止、スキップ、または拒否を伝えた場合は、直ちに従ってください。拒否された操作を再試行したり、ユーザーの選択に異議を唱えたりしないでください。
7. 料金について断定しないでください — 具体的な料金や費用の見積もりを提示しないでください。ユーザーから料金について尋ねられた場合は、次のページを案内してください：https://aws.amazon.com/transform/pricing/
8. コマンドの対象は ATX リソースに限定してください — すべての AWS コマンドは、ATX 固有のリソース（atx- で始まるバケット、ATX で始まるロール、atx- で始まる Lambda 関数など）を対象としてください。無関係な AWS リソースを操作しないでください。

テレメトリ

すべての atx custom def exec 呼び出し（ローカルまたはリモート）に、必ず --telemetry を指定してください。ファイルの確認、プロンプト、オプトインの手順は不要です。

フラグの形式は次のとおりです：--telemetry "client=<client>,agent=<agent>,executionMode=<local|remote>"

フィールドの値：

• client — このセッションをホストする MCP クライアントまたはツールを示す短い識別子（小文字、スペースなし）です。IDE（例：kiro、vscode、cursor、windsurf）、CLI ツール（例：claudecode、amazonqcli）、またはその他の MCP 互換ホストを指定できます。このセッションで実際に使用しているツール名を使ってください。単一の例を既定値として使わないでください。これらは例であり、網羅的な一覧ではありません。
• agent — このセッションを進行する AI アシスタントを示す短い識別子（小文字、スペースなし）です。例：kiro、amazonq、claude、copilot、cline、codex。このセッションで実際に使用しているアシスタント名を使ってください。単一の例を既定値として使わないでください。
• executionMode — ATX CLI を直接実行する場合は local、Lambda 経由で送信する場合は remote です。

唯一の例外は、ユーザーがセッション中のテレメトリ無効化（例：「disable telemetry」、「opt out of telemetry」、「no telemetry」など）を明示的に依頼した場合です。その場合は直ちに従い、セッションの残りの間は --telemetry を省略してください。反論したり、確認を求めたり、テレメトリを含める理由を説明したりしないでください。この設定は保存されません。次のセッションでは、再びテレメトリが有効になります。

出力構造

ローカルモード: 変換されたコードはリポジトリディレクトリにあります。

リモートモードの結果は S3 に残ります — 自動的にダウンロードしないでください。S3 パスをユーザーに提示します:

s3://atx-custom-output-{account-id}/
  transformations/
    {job-name}/
      {conversation-id}/
        code.zip                      # Zipped transformed source code
        logs.zip                      # ATX conversation logs

ユーザーが明示的にダウンロードを依頼した場合は、コマンドを提示しますが、実行はユーザーに任せてください: aws s3 cp s3://atx-custom-output-{account-id}/transformations/{job-name}/{conversation-id}/code.zip ./code.zip

一括結果のサマリー: ~/.aws/atx/custom/atx-agent-session/transformation-summaries/ — references/results-synthesis.md を参照してください。

リファレンス

リファレンス	使用するタイミング
repo-analysis.md	検出コマンド、シグナルマッチング、マッチレポート形式
single-transformation.md	1 つの TD を 1 つのリポジトリに適用 (ローカルまたはリモート)
multi-transformation.md	複数の TD を複数のリポジトリに並行して適用
remote-execution.md	インフラストラクチャのデプロイ、ジョブの送信、モニタリング
results-synthesis.md	一括変換後の統合レポートの生成
cli-reference.md	ATX CLI のフラグ、コマンド、環境変数、IAM 権限
troubleshooting.md	エラーの解決、デバッグ、品質の改善

ライセンス

AWS サービス利用規約。このスキルは AWS によって提供され、AWS カスタマー契約および適用される AWS サービス利用規約に従います。

変更履歴

ユーザーが何が変わったか、何が新しいかなどを尋ねた場合は共有してください。

[1.0.0] - 2026-04-30

• AWS Transform Agent Skill の初回リリース
• サポート対象の TD:
  • AWS/java-version-upgrade
  • AWS/python-version-upgrade
  • AWS/nodejs-version-upgrade
  • AWS/java-aws-sdk-v1-to-v2
  • AWS/nodejs-aws-sdk-v2-to-v3
  • AWS/python-boto2-to-boto3
  • AWS/comprehensive-codebase-analysis
  • AWS/java-performance-optimization
  • AWS/angular-version-upgrade
  • AWS/vue.js-version-upgrade
  • AWS/early-access-java-x86-to-graviton
  • AWS/early-access-angular-to-react-migration
  • AWS/early-access-log4j-to-slf4j-migration