ワークフロー

変換の実行

このセクションでは、変換を実行するさまざまな方法と、実行動作を制御するためのオプションについて説明します。

実行モード

AWS 変換カスタムは、異なるワークフローに対応するために 3 つの実行モードをサポートしています。

インタラクティブ対話モード

で CLI を起動atxし、自然言語による変換を実行するようにエージェントに依頼します。このモードでは、エージェントと完全に会話し、いつでも実行を中断し、変換プロセス中にフィードバックを提供できます。

このモードは、最大限の制御と、複雑なシナリオでエージェントをガイドする機能が必要な場合に使用します。

直接インタラクティブ実行

atx custom def exec -n <transformation-name> -p <path> を使用して、特定の変換をインタラクティブに開始します。このモードでは、エージェントを最初、最中、または実行終了時に確認して操作できます。エージェントは主要な決定ポイントで一時停止し、入力を求めます。

これは、トランスフォーメーションを自律的に実行する前にテストおよび改良するのに最適です。

非インタラクティブモードまたはヘッドレスモードで変換を実行できます。非インタラクティブモードでは、名前付き変換中のプロンプトが抑制されます。ヘッドレスモードでは、インタラクティブインターフェイスを完全にバイパスして、プレーンテキストのプロンプトでエージェントを実行できます。

非インタラクティブモード

完全な自動化atx custom def exec -n <transformation-name> -p <path> -x -tには を使用します。-x を非インタラクティブモードで実行し、 -t を追加してプロンプトを表示せずにすべてのツールを自動的に信頼します。

このモードは、人間による介入が利用できない、または望ましくない CI/CD パイプライン統合と一括実行用に設計されています。

ヘッドレスモード

エージェントとやり取りせずにタスクを完了するには、 を実行しatx -x "<prompt>" -t、プレーンテキストで指示を提供します。

ヘッドレス変換の実行

このモードを使用して、既存の変換定義をコードベースに適用します。変換は、承認を必要とせずに各ステップを自動的に実行します。

atx -x "apply transformation definition <transformation_definition_name> to <codebase_path>" -t

ヘッドレス変換の開発

変換定義を作成または変更します。

レガシー変換定義を新しいスキル形式 (SKILL.md + references/) に変換するには、次のコマンドを実行します。

atx -x "convert <legacy_transformation_definition_name> transformation definition to skill and save as draft" -t

新しい変換定義を作成するには、次のコマンドを実行します。

atx -x "create a transformation definition to <description> with references docs <reference_docs_path>" -t

一般的なコマンドフラグ

で変換を実行する場合atx custom def exec、一般的に次のフラグが使用されます。

• -n または --transformation-name - 実行する変換の名前を指定します。

• -p または --code-repository-path - コードベースへのパスを指定します (現在のディレクトリには「.」を使用します)

• -c または --build-command - 実行するビルドまたは検証コマンドを指定します

• -x または --non-interactive - 非インタラクティブモードを有効にします (ユーザープロンプトなし)

• -t または --trust-all-tools - プロンプトを表示せずにすべてのツールを自動的に信頼します

• -d または --do-not-learn - この実行からの教訓の抽出を防止します

• --tv または --transformation-version - 変換の特定のバージョンを指定します。

• -g または --configuration - 設定ファイルまたはインライン設定を提供します

重要

-t または --trust-all-toolsフラグは、プロンプトを表示せずにすべてのツール実行を自動的に承認し、ほとんどのセキュリティガードレールをバイパスします ( によって上書きされない限り、alwaysPromptCommandsリストに一致するコマンドには明示的なアクセス許可が必要ですtrustedShellCommands)。完全に自律したエクスペリエンスには --non-interactiveと を渡す--trust-all-tools必要がありますが、変換を実行するためには必要ありません。本番稼働環境での使用には注意が必要です。

設定ファイルの使用

AWS 変換カスタムは、YAML または JSON 形式のオプションの設定ファイルをサポートしています。設定ファイルを使用すると、実行パラメータを指定し、エージェントに追加のコンテキストを提供できます。

設定ファイルを使用するには:

atx custom def exec --configuration file://config.yaml

設定をインラインキーと値のペアとして指定することもできます。

atx custom def exec --configuration "key=value,key2=value2"

設定ファイルの例 (config.yaml):

codeRepositoryPath: ./my-project
transformationName: my-transformation
buildCommand: mvn clean install
additionalPlanContext: |
  The target Java version to upgrade to is Java 17.
  Ensure compatibility with our internal logging framework version 2.3.
validationCommands: |
  mvn test
  mvn verify

additionalPlanContext パラメータは、エージェントの実行プランに追加のコンテキストを提供します。これは、 AWSマネージド変換で特定のニーズに合わせて動作をカスタマイズするために特に役立ちます。

ビルドおよび検証コマンド

ビルドまたは検証コマンドは、変換プロセス中にコードを検証する方法を指定するオプションのパラメータです。 AWS Transform custom は、指定しない場合、変換に基づいて最適なビルドコマンドを推測しようとしますが、品質に固有であることが推奨されます。

ビルドコマンドと検証コマンドの例:

• Java: mvn clean installまたは gradle build

• Python: pytestまたは python -m py_compile

• Node.js: npm run buildまたは npm test

• Linters: eslint .または pylint .

構築を必要としない言語や変換であっても、結果を検証し、検証が失敗した場合に問題を返すコマンドを提供することは、変換の品質を向上させるために非常に重要です。

ビルドまたは検証が必要ない場合は、入力から を省略します。

学習動作の制御

デフォルトでは、 AWS Transform custom はすべての変換実行から教訓を抽出します。特定の実行の学習を防ぐことができます。

実行からの学習を防ぐには:

atx custom def exec -n my-transformation -p ./my-project -d

-d または --do-not-learnフラグは、現在の実行からの教訓抽出の許可をオプトアウトします。

会話を再開する

AWS 変換カスタムを使用すると、作成から 30 日以内に以前の会話を再開できます。

最新の会話を再開するには:

atx --resume

特定の会話を再開するには:

atx --conversation-id <conversation-id>

重要

会話は、作成後 30 日以内にのみ再開できます。30 日後、会話を再開できなくなります。

エージェント分の追跡

AWS 変換カスタムは、変換セッション中に消費されたエージェントの分を追跡します。エージェントの分は会話のライフサイクル全体で累積され、会話が終了すると表示されます。

Agent minutes used: 12.50

エージェント分は中断後も保持されます。Ctrl+C を使用してセッションを中断し、後で再開すると、以前に蓄積された分が引き継がれ、再開されたセッションで蓄積し続けます。

インタラクティブセッション中にエージェント分を確認するには:

入力プロンプト/usageに と入力して、会話を終了せずに現在蓄積されているエージェント分を表示します。

エージェント分予算制限を設定するには:

atx custom def exec -n my-transformation -p ./my-project --limit 30

--limit オプションは、セッションのエージェント分予算の上限を設定します。エージェント分は、ウォールクロック時間ではなく、アクティブなエージェントの作業時間を反映します。制限に達すると、CLI はメッセージを表示し、再開する手順で終了します。

⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting.

制限を引き上げて後で会話を再開できます。

atx --conversation-id <conversation_id> -t --limit <increased_limit>

継続的な学習

このセクションでは、継続的学習によって作成された教訓を確認して管理する方法について説明します。

教訓を理解する

継続的な学習システムは、変換の以前の実行から教訓を自動的に抽出します。システムは、以下に基づいて非同期的にそれらを作成します。

• インタラクティブモードで提供される開発者フィードバック

• 変換中に発生したコードの問題

異なるコードベース間で変換を実行すると、時間の経過とともに教訓が蓄積されます。システムはそれらを自動的に適用して、今後の実行を改善します。各教訓は、関連する教訓を一緒に確認できるように、類似ドメインのすべての教訓を含むカテゴリに属します。使用したくない教訓については、その教訓を完全にアーカイブまたは削除できます。

教訓の表示と管理

learnings コマンドを使用して、変換定義の教訓を参照および管理するためのインタラクティブセッションを開きます。

教訓ビューワーを開くには:

atx custom def learnings -n my-transformation

ビューワーは、教訓カテゴリのリストで開き、それぞれにアクティブな教訓の数が表示されます。カテゴリを選択してその教訓を表示し、次に教訓を選択して、教訓本文、その影響、それを参照した以前の実行の数など、その詳細全体を表示します。

教訓のアーカイブと復元

システムは教訓を自動的に適用します。システムに教訓を適用させたくない場合は、その教訓をアーカイブできます。アーカイブされた教訓は保持されますが、今後の実行には適用されません。アーカイブされたすべての教訓はグループ化されているため、それらを確認してアクティブな使用に復元できます。

教訓の削除

役に立たない教訓を完全に削除します。削除を元に戻すことはできず、システムは今後の実行から削除された教訓を再学習する可能性があります。

教訓は、削除する前にアーカイブする必要があります。

高度な設定

このセクションでは、 AWS 変換カスタムの高度な機能と設定オプションについて説明します。

環境可変

環境変数を使用して CLI の動作をカスタマイズできます。

注記

次の例は、Linux および macOS 構文 () を示していますexport。Windows では、 を使用して PowerShell で環境変数を設定します$env:NAME="value"。同等のコマンドについては、Windows (PowerShell) タブを参照してください。

ATX_SHELL_TIMEOUT

シェルコマンドのデフォルトのタイムアウトを上書きします (900 秒/15 分）。

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

これは、大規模なコードベースや長時間実行されるビルドプロセスに役立ちます。

ATX_DISABLE_UPDATE_CHECK

コマンドの実行中に自動バージョンチェックを無効にし、通知を更新します。

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME および ATX_GIT_COMMITTER_EMAIL

Transform がリポジトリに作成するチェックポイントコミットに使用される作成者 ID AWS を設定して、変換中に変更を適用します。これらの変数が設定されていない場合、チェックポイントコミットはデフォルトの ID () に属性付けられますATX Bot <[e-mail]>。チェックポイントを特定の作成者に属性するように両方の変数を設定します。

Linux and macOS

export ATX_GIT_COMMITTER_NAME="Jane Developer"
export ATX_GIT_COMMITTER_EMAIL="[e-mail]"

Windows (PowerShell)

$env:ATX_GIT_COMMITTER_NAME="Jane Developer"
$env:ATX_GIT_COMMITTER_EMAIL="[e-mail]"

信頼設定

信頼設定を使用すると、プロンプトなしで実行する特定のツールやコマンドを事前に承認できます。信頼レベルに関係なく、特定のシェルコマンドに明示的なアクセス許可を要求することもできます。これらの設定は ~/.aws/atx/trust-settings.yaml ファイルで行われます。

ファイルには 3 つのリストが含まれています。

• trustedTools - プロンプトを表示せずに実行できるツール

• trustedShellCommands - プロンプトを表示せずに実行できるシェルコマンド

• alwaysPromptCommands - -tフラグまたはセッションの信頼に関係なく、 によって上書きされない限りtrustedShellCommands、明示的なアクセス許可を必要とするシェルコマンドパターン。これらのパターンは、非インタラクティブモード () では強制されません-x。

デフォルトの信頼されたツール:

• file_read

• get_transformation_from_registry

• list_available_transformations_from_registry

信頼設定の編集:

trust-settings.yaml ファイルを手動で編集して、信頼できるツールやコマンドを追加または削除できます。trustedShellCommands と はどちらも、 を使用した glob ワイルドカードパターンalwaysPromptCommandsをサポートしています*。

注記

コマンドが両方のリストと一致する場合、 が優先trustedShellCommandsされます。

以下に、各コマンドリストと例を示します。

• trustedShellCommands - これらのパターンに一致するコマンドは、プロンプトを表示せずに実行され、他のすべてのガードレールをバイパスします。パターンは完全なコマンド文字列と照合されます。

  例:

  • cd * - cd で始まる複合コマンドに一致

  • *&&* - && 演算子を使用してすべてのコマンドを信頼します

• alwaysPromptCommands - これらのパターンに一致するコマンドには、-tフラグまたはセッションの信頼に関係なく、 によって上書きされない限りtrustedShellCommands、明示的なアクセス許可が必要です。これらのパターンは、非インタラクティブモード () では強制されません-x。パターンは、複合式 (&&、||、コマンド置換) の各サブコマンドと照合されます。

  例:

  • rm -rf * - 再帰的な強制削除コマンドを常に求める

  • sudo * - sudo で実行されるコマンドを常にプロンプトする

  • find * -exec * - 常に -exec で検索コマンドを要求する

セッションレベルの信頼:

インタラクティブプロンプトでは、以下を選択できます。

• (y)es - 1 回実行する

• (n)o - 拒否

• (t)rust - 現在のセッションのみを信頼する

セッションレベルの信頼設定は一時的なもので、CLI の再起動時にリセットされるため、 trust-settings.yaml を完全に変更することなく一時的な承認が得られます。

注記

セッション信頼は、alwaysPromptCommandsリストに一致するコマンドでは使用できません。

モデルコンテキストプロトコル (MCP) サーバー

AWS Transform CLI は、モデルコンテキストプロトコル (MCP) サーバーをサポートしています。MCP サーバーは、追加のツールで機能を拡張します。

設定:

~/.aws/atx/mcp.json ファイルで MCP サーバーを設定します。 AWS Transform CLI は、ローカルコマンドベースのサーバーとリモート HTTP サーバーの 2 種類の MCP サーバーをサポートしています。

ローカルコマンドベースのサーバー:

ローカルサーバーは、マシンで子プロセスとして実行されます。command プロパティを使用して設定します。

{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

リモート HTTP サーバー:

リモートサーバーは、HTTP または HTTPS URL でホストされている MCP サーバーに接続します。url プロパティを使用して設定します。

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_API_TOKEN}"
      }
    }
  }
}

headers プロパティはオプションで、${VAR_NAME}構文を使用した環境変数の拡張をサポートしています。これにより、API トークンなどの機密値を設定ファイルではなく環境変数に保存できます。

設定プロパティ:

ローカルコマンドベースのサーバーは、次のプロパティをサポートしています。

• command (必須) - サーバーを実行するコマンド

• args (オプション) - コマンドライン引数の配列

• env (オプション) - サーバープロセスに渡す環境変数

リモート HTTP サーバーは、次のプロパティをサポートしています。

• url (必須) - リモート MCP サーバーの HTTP または HTTPS URL

• headers (オプション) - ${VAR_NAME}環境変数の拡張をサポートするリクエストに含める HTTP ヘッダー

MCP サーバーの管理:

設定された MCP サーバーのリストを表示します。

atx mcp tools

特定の MCP サーバーが提供する利用可能なツールを一覧表示します。

atx mcp tools --server <server-name>

使用状況の追跡:

CLI は、変換の実行中に MCP ツールの使用を自動的に追跡します。使用状況統計は、 とともに会話ディレクトリmcp_usage.jsonの として保持されますmetadata.json。ファイルには、以下を含む各実行のツールごとのメトリクスが記録されます。

• ツールあたりの呼び出し数

• ツールあたりのエラー数

• ツールあたりの合計実行時間

• 最後のエラーの詳細 (存在する場合)

クライアント側のスキル

クライアント側のスキルは、変換の実行中にエージェントを拡張する追加機能です。これにより、エージェントが組み込み機能とともに使用できるカスタムツール、スクリプト、および手順を提供できます。

スキル検出ディレクトリ:

スキルは、4 つのディレクトリから優先順位で検出されます。同じ名前のスキルが複数のディレクトリに存在する場合、リストの最初のディレクトリが優先されます。

1. <project>/.aws/atx/skills/ - プロジェクトレベル、 AWS 変換 CLI 固有

2. <project>/.agents/skills/ - プロジェクトレベル、クロスクライアント (互換性のある任意のエージェントツールで使用可能)

3. ~/.aws/atx/skills/ - ユーザーレベル、CLI 固有の AWS 変換

4. ~/.agents/skills/ - ユーザーレベル、クロスクライアント (互換性のある任意のエージェントツールで使用可能)

.aws/atx/skills/ ディレクトリは AWS Transform CLI に固有です。.agents/skills/ ディレクトリはクロスクライアントです。つまり、そこに配置されたスキルは、 AWS Transform CLI 以外の互換性のあるエージェントツールで使用できます。

スキルディレクトリ構造:

各スキルは、YAML フロントマターを持つSKILL.mdファイルを含むディレクトリです。

~/.aws/atx/skills/
└── my-skill/
    ├── SKILL.md          # Required: frontmatter + instructions
    ├── references/       # Optional: reference docs the agent can read
    │   └── guide.md
    └── scripts/          # Optional: scripts the agent can execute
        └── validate.py

SKILL.md 形式:

---
name: my-skill
description: When to use this skill
---
# Skill Title

Instructions for the agent...

name フィールドは親ディレクトリ名と一致する必要があります。

スキルの無効化:

ファイルを削除せずにスキルがロードされないようにするには、 disable-model-invocation: true をフロントマターに追加します。

---
name: my-skill
description: When to use this skill
disable-model-invocation: true
---

このプロパティを設定すると、CLI は検出中にスキルをスキップします。変換定義がスキルファイルを読み取るように明示的に指示しない限り、エージェントはスキルを表示または使用することはできません。これを使用して、スキルを一時的に無効にしたり、work-in-progressとしてマークしたり、人間の読者のみを対象とした参考資料を保持したりできます。

注記

無効なスキルのファイルはディスクに残ります。変換定義によって特定のファイルパスを読み取るようにエージェントに指示された場合でも、エージェントはコンテンツにアクセスできます。disable-model-invocation プロパティは、ファイルシステムアクセスではなく、自動検出とコンテキストインジェクションを防ぎます。

実行モード別のスキルの可用性:

• Exec モード (atx custom def exec と --code-repository-path) - ユーザーレベルとプロジェクトレベルの両方のディレクトリからスキルを検出します。

• インタラクティブモード (atx) - ユーザーレベルのスキルのみが最初に検出されます。セッション中にコードリポジトリパスを指定すると、プロジェクトレベルのスキルもロードされます。

スキル検出の検証:

実行後に CLI のデバッグログをチェックして、検出されたスキルを確認します。

Linux and macOS

grep -i "skill" ~/.aws/atx/logs/debug.log | tail -20

Windows (PowerShell)

Select-String -Pattern "skill" "$env:USERPROFILE\.aws\atx\logs\debug.log" | Select-Object -Last 20

検証に失敗したスキルは、デバッグログに警告とともにスキップされます。

注記

クライアント側のスキルには CLI バージョン 2.0 以降が必要です。

プロジェクトレベルとユーザーレベルのスキルの選択

スキルを配置する場所によって、そのスキルの利点とアクティブ化時期が決まります。

プロジェクトレベルのスキル (<project>/.aws/atx/skills/):

これらをバージョン管理にコミットして、リポジトリに対して変換を実行しているすべてのチームメンバーがそれらを自動的に検出できるようにします。以下のプロジェクトレベルのスキルを使用します。

• リポジトリ固有のコンプライアンスチェック (Dockerfile ルール、Terraform ポリシー、移行安全バリデータ)

• このコードベースに適用される組織のコーディング標準 (オブザーバビリティパターン、エラー処理、命名規則)

• プロジェクトに固有のスクリプトを構築またはテストする (カスタム linters、アーキテクチャのフィットネス機能)

• このリポジトリで使用される内部ライブラリの API 移行ガイド

ユーザーレベルのスキル (~/.aws/atx/skills/):

これらはマシンに残り、ターゲットとするリポジトリに関係なく、すべての変換中にアクティブ化されます。ユーザーレベルのスキルは、以下に使用します。

• 個人用ワークフローツール (変更ログジェネレーター、コミットメッセージフォーマッター)

• クロスプロジェクト設定 (推奨テストパターン、ドキュメントスタイルのリマインダー)

• すべてのリポジトリで組織が必要とするライセンスコンプライアンスチェック

• 使用するすべてのコードベースに適用されるカバレッジしきい値または品質ゲート

効果的なスキルのヒント:

• SKILL.md フロントマターにクリアdescriptionフィールドを書き込みます。エージェントはこのフィールドを使用して、スキルがいつ関連しているかを決定します。

• 成功の場合はコード 0、失敗の場合はゼロ以外の検証スクリプトを終了します。エージェントは終了コードを解釈してコンプライアンスを判断します。

• 明確で実用的なエラーメッセージをスクリプトに出力します。エージェントは出力を読み取り、修正する内容を理解します。

• いずれかのレベルでクロスクライアントディレクトリ (.agents/skills/) にスキルを配置し、 AWS Transform CLI 以外の他の AI 開発ツールと共有します。

クライアント側のスキルの例

これらの例は、スクリプトベースの検証スキルと参照のみのスキルの 2 つの一般的なパターンを示しています。

例: Dockerfile Compliance Checker (スクリプトベース)

このスキルは、セキュリティと運用のベストプラクティスに照らして Dockerfiles を検証します。変更の前後にエージェントが実行する検証スクリプトを使用します。

ディレクトリ構造:

.aws/atx/skills/
└── dockerfile-compliance/
    ├── SKILL.md
    ├── scripts/
    │   └── lint_dockerfile.sh
    └── references/
        └── dockerfile-best-practices.md

SKILL.md:

---
name: dockerfile-compliance
description: Validates Dockerfiles against security and operational best practices
---
# Dockerfile Compliance Checker

When a transformation creates or modifies Dockerfiles, run the compliance checker.

## When to use

- After creating a new Dockerfile
- After modifying FROM, RUN, USER, or EXPOSE directives
- When containerizing an application as part of a transformation

## How to use

Run: `bash scripts/lint_dockerfile.sh <path-to-Dockerfile>`

If violations are found, consult `references/dockerfile-best-practices.md`
for compliant patterns.

検証スクリプトは、ピン留めされていないベースイメージタグ、ルートとして実行されているタグ、ENVディレクティブでハードコードされたシークレット、HEALTHCHECK定義の欠落をチェックします。エージェントはスクリプトを実行し、参照ファイルのパターンを使用して違反を修正し、スクリプトを再実行してコンプライアンスを確認します。

例: API 非推奨ヘルパー (参照のみ)

このスキルは、アップグレード変換中に非推奨の API コールを置き換えることを通じてエージェントをガイドします。スクリプトのない参照ファイルのみを使用します。

ディレクトリ構造:

.aws/atx/skills/
└── api-deprecation-helper/
    ├── SKILL.md
    └── references/
        ├── aws-sdk-v2-to-v3.md
        └── react-class-to-hooks.md

SKILL.md:

---
name: api-deprecation-helper
description: Guides the agent through replacing deprecated API calls with modern equivalents
---
# API Deprecation Helper

When performing upgrade transformations, use this skill to identify and replace
deprecated API calls with their modern equivalents.

## When to use

- During any version upgrade transformation
- When build warnings mention deprecated APIs
- When transforming code that uses legacy patterns

## Process

1. Identify deprecated API calls in the codebase
2. For each deprecated call, find the replacement in `references/`
3. Apply the replacement, preserving the original behavior
4. Verify the replacement compiles and tests pass

リファレンスファイルにはbefore-and-afterコード例が含まれています。例えば、 は S3Clientと を使用して、 のようなパターンs3.putObject(params).promise()をモジュラー v3 に相当する にaws-sdk-v2-to-v3.mdマッピングしますPutObjectCommand。

タグと組織

アクセスコントロールと分類のタグを使用して変換を整理できます。

注記

これらのコマンドの一部では、変換定義の Amazon リソースネーム (ARN) を指定する必要があります。ARN 構造は次のとおりです。 arn:aws:transform-custom:<region>:<account-id>:package/<td-name>

変換のタグを一覧表示するには:

atx custom def list-tags --arn <transformation-arn>

変換にタグを追加するには:

atx custom def tag --arn <transformation-arn> --tags '{"env":"prod","team":"backend"}'

変換からタグを削除するには:

atx custom def untag --arn <transformation-arn> --tag-keys "env,team"

タグは、IAM ポリシーのグループ化されたアクセスコントロールに使用できます。特定のタグを持つすべての変換 (例: team:frontendまたは でタグ付けされたすべての変換environment:production) にアクセス許可を付与するポリシーを作成できます。

ログ

AWS Transform CLI は、トラブルシューティングとデバッグのために 3 種類のログを保持します。

会話ログ:

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\<timestamp>-conversation.log

これらのログには、特定のセッションの完全な会話履歴が含まれます。

サブエージェントログ:

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/subagents/<name>.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\subagents\<name>.log

これらのログには、変換中にメインエージェントがスポーンするサブエージェントからの出力が含まれています。サブエージェントを直接管理する必要はありません。

開発者デバッグログ:

Linux and macOS

~/.aws/atx/logs/debug*.log
~/.aws/atx/logs/error.log

Windows

%USERPROFILE%\.aws\atx\logs\debug*.log
%USERPROFILE%\.aws\atx\logs\error.log

これらのログは、 CLI 自体の高度なトラブルシューティング情報を提供します。

注記

Logs ディレクトリに複数のデバッグログファイルがある場合があります (debug1.log、debug2.log など）。サポートチケットを開いてより迅速に解決する場合は、~/.aws/atx/custom/<conversation-id>/* や ~/.aws/atx/logs/* など、関連するすべてのログを確認して提供します。

CLI 更新

CLI を最新の状態に保つことで、新機能や改善点にアクセスできます。

更新を確認するには:

atx update --check

を最新バージョンに更新するには:

atx update

特定のバージョンに更新するには:

atx update --target-version <version>

カスタム変換を作成する

このセクションでは、カスタム変換定義を作成、変更、管理する方法について説明します。

新しい変換の作成

インタラクティブ CLI を使用して、新しい変換定義を作成します。

変換定義を作成するには

1. AWS 変換 CLI を起動します。

   atx

2. 新しい変換を作成することをエージェントに伝えます。

3. 変換目標の明確で詳細な説明を入力します。以下が含まれます:

   • ソースとターゲットの状態 (例：「バージョン X からバージョン Y へのアップグレード」)

   • 必要な特定の変更 (「インポートステートメントの更新、廃止されたメソッドの置き換え」など)

   • 特別な考慮事項または制約事項

4. エージェントが明確化や追加情報をリクエストする場合は、具体的な例と参考資料を提供します。

5. エージェントによって作成された最初の変換定義を確認します。

6. サンプルコードベースで変換をテストします。

7. フィードバック、コード修正、または追加の例を提供して反復します。

8. 変換をローカルに保存するか、レジストリに公開します。

変換を作成するためのベストプラクティス:

• 複雑な変換を試みる前に、シンプルで明確に定義された変換から始める

• 移行ガイドやコードサンプルを含む包括的な参考資料を提供する

• 公開前に複数のサンプルコードベースでテストする

• 決定論的なビルドコマンドまたは検証コマンドを使用して継続的な学習を有効にする

• 複雑な変換を複数の小さなステップに分割することを検討する

• エージェントがこれらの要件を優先するように、変換定義に「CRITICAL:」または「IMPORTANT:」で重要な情報をマークします。

• 正確な要件に従う必要がある場合 (特定のコマンドや文字列値を使用するなど）、変換定義で完全な文字列を明示的に指定します。これらをバッシュ引用符で囲んで、それらがターミナルコマンドまたはリテラル文字列であることを明確に示すことができます。これにより、ばらつきが軽減され、一貫した実行が保証されます。

参考資料の提供

会話中にファイルパスを指定することで、 AWS 変換カスタムにリファレンスファイルを提供できます。これらのファイルは、変換定義の references/フォルダに保存されます。

推奨されるリファレンスファイルのタイプ:

• 前後のサンプルコード

• 関連する APIs、ライブラリ、または機能のドキュメント

• 人間が読める移行ガイド

リファレンスファイルを指定するには:

Take a look at the documentation here: /path/to/migration-guide.md

複数の参照ファイルを含むディレクトリを指定することもできます。

Take a look at the docs we have here: /path/to/docs/

注記

テキストベースのファイル (.md、.html、.txt、コードファイル) のみがサポートされています。バイナリファイル、イメージ、リッチテキストファイル (.pdf、.png、.docx など) は現在サポートされていません。多くの場合、テキストコンテンツを抽出し、それをリファレンスとして使用できます。小さなテキストファイルが多数ある場合は、記述名付きファイルに連結することを検討してください。すべてのファイルの合計は 10MB に制限されています。

既存の変換の変更

カスタム変換は、ドラフトとして保存するか公開する前と後に変更できます。 AWSマネージド変換は変更できません。カスタマイズする必要がある場合は、 設定ファイルを使用して追加のコンテキストを指定できます。

既存の変換を変更するには

1. AWS 変換 CLI を起動します。

   atx

2. 既存の変換を変更することをエージェントに伝えます。

3. 以下を行うかどうかを選択します。

   • ローカルに保存された変換へのファイルパスを指定する (つまり、保存されたドラフトや公開されていない)

   • レジストリから変換のリストをリクエストする

4. レジストリから選択する場合は、変更する変換を選択します。

5. エージェントと協力して、行う変更を記述します。

6. サンプルコードベースで更新された変換をテストします。

7. 必要に応じて、更新をレジストリに発行します。

変換の発行と管理

インタラクティブエクスペリエンスまたは次のコマンドを使用して、変換を発行および管理できます。

変換をドラフトとして保存するには:

atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

変換を公開するには:

atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

使用可能な変換を一覧表示するには:

atx custom def list

変換定義をダウンロードするには:

atx custom def get -n my-transformation

これにより、変換定義が現在の作業ディレクトリにダウンロードされます。ターゲットディレクトリは --tdフラグで指定でき、バージョンは --tvフラグで指定できます。

変換定義を削除するには:

atx custom def delete -n my-transformation

重要

これにより、指定された変換定義がアカウントから完全に削除されます。

変換バージョンの管理

AWS 変換カスタムは、変換定義のバージョンを維持します。変換を実行またはダウンロードするときにバージョンを指定できます。

特定のバージョンを実行するには:

atx custom def exec -n my-transformation --tv v1 -p ./my-project

特定のバージョンをダウンロードするには:

atx custom def get -n my-transformation --tv v1

バージョンが指定されていない場合は、最新バージョンが使用されます。