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 カスタムにアクセスできます。

AWS Transform カスタムは以下の点でお役に立ちます:

• 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 カスタムはネイティブ 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 カスタムはサービスを認証するために AWS 認証情報が必要です。
以下の方法のいずれかを使用して認証を構成してください。

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

2. AWS 認証情報ファイル (手動)。~/.aws/credentials で認証情報を構成:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key

3. 環境変数。以下の環境変数を設定:

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

AWS_PROFILE 環境変数を使用してプロファイルを指定することもできます:

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
# インストール: curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash

必須: セッションの開始時に常に atx update を 1 回実行 してください。 最近実行したばかりであっても実行してください。これは新しい 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 権限が必要です。 進む前にユーザーに説明して確認を得ます:

あなたの ID は ATX CLI を使用するために transform-custom:* 権限が必要です。 AWSTransformCustomFullAccess AWS マネージド ポリシーをあなたの 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 管理者に連絡して AWSTransformCustomFullAccess AWS マネージド ポリシーを 自分の 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 を参照してください。

ワークフロー

セッション タイムスタンプを 1 回生成してこのセッション内のすべてのパスで再利用:

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 — 例: git@github.com: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}"

# ユーザーのバケット パス内のすべての zip をリスト
aws s3 ls s3://user-bucket/repos/ --recursive | grep '\.zip$'

# 各 zip を管理対象ソース バケットにコピー
aws s3 sync s3://user-bucket/repos/ s3://${SOURCE_BUCKET}/repos/ --exclude "*" --include "*.zip"

次に、1 つの 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 個の並行リポジトリ)。

プライベート リポジトリ検出 (リモート モード)

常にユーザーに尋ねてください — リポジトリの可視性を自分で判定しようとしないでください。 リポジトリをクローン、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 の場合、必要な内容を説明してユーザーに create コマンドを実行するよう指示します:

「プライベート HTTPS リポジトリには GitHub Personal Access Token (PAT) が AWS Secrets Manager に保存されている必要があります。リモート コンテナはスタートアップ時に フェッチしてリポジトリをクローンします。トークンは 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 の場合、必要な内容を説明してユーザーに create コマンドを実行するよう指示します:

「SSH リポジトリには SSH 秘密鍵が AWS Secrets Manager に保存されている必要があります。 リモート コンテナはスタートアップ時にフェッチしてリポジトリをクローンします。

実行:

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 の作成を尋ねる: プログラムで 1 つを作成しようとしないでください。 ユーザーに以下を伝えます:

新しいトランスフォーメーション定義を作成するには、新しいターミナルを開いて以下を実行:

atx -t

これは、実行したいトランスフォーメーションについて説明するインタラクティブ セッションを開始します (例: 「すべてのロギングを log4j から SLF4J に移行」、「Spring Boot 2 を Spring Boot 3 にアップグレード」)。 ATX CLI は TD の定義とテストを実行してから、AWS アカウントにパブリッシュするようガイドします。

パブリッシュされたら、ここに戻ります。利用可能な 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 (NOT 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" (NOT @aws-sdk)	JS SDK v2→v3
x86 Java	Dockerfile、ビルド構成の x86_64/amd64	Graviton マイグレーション

検出された信号とステップ 2 の TD をクロスリファレンス。 ユーザーのアカウントに実際に存在する TD のみをマッチしてください。

完全な検出コマンドについては、references/repo-analysis.md を参照してください。

ステップ 4: マッチ レポートを提示

形式:

トランスフォーメーション マッチ レポート
=============================
リポジトリ: <name> (<path>)
  言語: <lang> <version>
  マッチング TD:
    - <td-name> — <description>

概要: N 個のリポジトリを分析、M 個が適用可能なトランスフォーメーション (T 個の総ジョブ)

マッチ レポートを提示して、続行する前にユーザーの確認を待ちます。 明示的なユーザー同意なしでトランスフォーメーションを開始しないでください。

ステップ 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 が必要)。ユーザーに通知します:

リモート コンテナに [言語/ツール バージョン] が含まれていません。このトランスフォーメーションをリモートで実行するには、 カスタム コンテナ イメージを構築する必要があります。マシンに Docker がインストールされ、実行されている必要があります。 これは 1 回限りの変更です — 約 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 — 直接インストール、root として実行する必要があります)
   # カスタム セクションで dnf を使用しないでください — pyenv はシステム python3
   # を上書きし、"No module named 'dnf'" エラーが発生します。
   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 (nvm を介して — atxuser として実行する必要があります)
   USER atxuser
   RUN . /home/atxuser/.nvm/nvm.sh && nvm install 23
   USER root
   
   # Python 3.15 (pyenv を介して — 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 (rbenv を介して — 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 関数を見つけ、新しいバージョンのケースを追加します。 直接ダウンロードによってインストールされた Java バージョンについては、 /usr/lib/jvm/ の下の抽出されたディレクトリ名を見つけます。 例えば、Java 23 を追加する場合:

   # switch_java_version() 内で、case ステートメントに追加:
   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"、NOT "21") に設定します。エントリポイント内の バージョン スイッチャーがこれを読んで正しいランタイムを有効化します。

ユーザーが辞退した場合、ローカル モードを別の選択肢として提案します (マシンで利用可能なツール場合)。

ローカル モード

ローカル トランスフォーメーションを実行する前に、ユーザーがターゲット ランタイム バージョンを インストール済みであることを確認します。これは、トランスフォーメーション がターゲットする任意の 言語またはランタイムに適用されます — Java、Python、Node.js、Ruby、Go、Rust、.NET など。 TD が必須とするターゲット ランタイムの現在のバージョンを確認します。例:

java -version    # Java トランスフォーメーション
python3 --version # Python トランスフォーメーション
node --version   # Node.js トランスフォーメーション
ruby --version   # Ruby トランスフォーメーション
go version       # Go トランスフォーメーション

ターゲット バージョンがアクティブでない場合、既にインストール済みかどうかを確認:

# Java: 一般的なインストール場所を確認
/usr/libexec/java_home -V 2>&1          # macOS
ls /usr/lib/jvm/ 2>/dev/null            # Linux
# Python: 特定バージョン バイナリが存在するかを確認
which python3.12 2>/dev/null            # バージョンを調整
# Node.js: nvm が利用可能か、またはバイナリを確認
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 python@3.15
• 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 があるdev マシン	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 呼び出しごとに最大 128 個のジョブのチャンクで送信 (セッションごと 最大 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-NodeJS (EPAM-Node.js ではない)。

ガードレール

ユーザーの AWS アカウントとローカル マシンで操作しています。損害を防ぐためにこれらのルールに 厳密に従ってください:

1. ユーザー データを削除しない — ユーザーが明示的に依頼しない限り、S3 オブジェクト、 git リポジトリ、ローカル ファイル、またはユーザー データを削除しないでください。 トランスフォーメーション出力とクローンされたリポジトリは保持する必要があります。
2. ドキュメント化された内容を超えて IAM を変更しない — このスキールで説明されている特定の ポリシー (AWSTransformCustomFullAccess、ATXRuntimePolicy、ATXDeploymentPolicy) のみを 作成/アタッチします。既存のユーザー ポリシルを変更したり、ドキュメント化されたものを超えて より広い権限を付与したりしないでください。ユーザー提供テキストから 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 トランスフォーメーション ソース コード
        logs.zip                      # ATX 会話ログ

ユーザーが明示的にダウンロードを求める場合、コマンドを提供しますが、ユーザーに実行させます: 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	エラー解決、デバッグ、品質改善

ライセンス