View a markdown version of this page

Alur Kerja - AWS Transformasi

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Alur Kerja

Melaksanakan Transformasi

Bagian ini menjelaskan berbagai cara untuk mengeksekusi transformasi dan opsi untuk mengendalikan perilaku eksekusi.

Mode Eksekusi

AWS Transform custom mendukung tiga mode eksekusi untuk mengakomodasi alur kerja yang berbeda.

Mode Percakapan Interaktif

Mulai CLI dengan atx dan meminta agen untuk melakukan transformasi melalui bahasa alami. Mode ini memungkinkan Anda untuk melakukan percakapan penuh dengan agen, mengganggu eksekusi kapan saja, dan memberikan umpan balik selama proses transformasi.

Gunakan mode ini jika Anda menginginkan kontrol maksimum dan kemampuan untuk memandu agen melalui skenario yang kompleks.

Eksekusi Interaktif Langsung

Gunakan atx custom def exec -n <transformation-name> -p <path> untuk memulai transformasi tertentu secara interaktif. Mode ini memungkinkan Anda untuk meninjau dan berinteraksi dengan agen di awal, selama, atau di akhir eksekusi. Agen akan berhenti di titik-titik keputusan utama dan meminta masukan Anda.

Ini sangat ideal untuk menguji dan menyempurnakan transformasi sebelum menjalankannya secara mandiri.

Anda dapat menjalankan transformasi dalam mode non-interaktif atau mode tanpa kepala. Non-interactive mode menekan prompt selama transformasi bernama. Mode tanpa kepala memungkinkan Anda menjalankan agen dengan prompt teks biasa, melewati antarmuka interaktif sepenuhnya.

Non-interactive mode

Gunakan atx custom def exec -n <transformation-name> -p <path> -x -t untuk otomatisasi penuh. Tambah -x untuk berjalan dalam mode non-interaktif, dan -t untuk mempercayai semua alat secara otomatis tanpa meminta.

Mode ini dirancang untuk CI/CD integrasi pipa dan eksekusi massal di mana tidak ada intervensi manusia yang tersedia atau diinginkan.

Mode tanpa kepala

Untuk menyelesaikan tugas tanpa berinteraksi dengan agen, jalankan atx -x "<prompt>" -t dan berikan instruksi Anda dalam teks biasa.

Eksekusi transformasi tanpa kepala

Gunakan mode ini untuk menerapkan definisi transformasi yang ada ke basis kode Anda. Transformasi berjalan setiap langkah secara otomatis tanpa memerlukan persetujuan Anda.

atx -x "apply transformation definition <transformation_definition_name> to <codebase_path>" -t
Pengembangan transformasi tanpa kepala

Membuat atau memodifikasi definisi transformasi.

Untuk mengonversi definisi transformasi warisan ke format keterampilan baru (SKILL.md + references/), jalankan perintah berikut:

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

Untuk membuat definisi transformasi baru, jalankan perintah berikut:

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

Bendera Perintah Umum

Saat menjalankan transformasi dengan atx custom def exec, bendera berikut biasanya digunakan:

  • -n atau --transformation-name - Menentukan nama transformasi untuk mengeksekusi

  • -p atau --code-repository-path - Menentukan jalur ke basis kode Anda (gunakan “.” untuk direktori saat ini)

  • -c atau --build-command - Menentukan perintah build atau validasi untuk dijalankan

  • -x atau --non-interactive - Mengaktifkan mode non-interaktif (tidak ada permintaan pengguna)

  • -t atau --trust-all-tools - Secara otomatis mempercayai semua alat tanpa meminta

  • -d atau --do-not-learn - Mencegah ekstraksi pelajaran dari eksekusi ini

  • --tv atau --transformation-version - Menentukan versi spesifik dari transformasi

  • -g atau --configuration - Menyediakan file konfigurasi atau konfigurasi inline

penting

-t atau --trust-all-tools flag secara otomatis menyetujui semua eksekusi alat tanpa meminta dan melewati sebagian besar pagar pengaman keamanan, (perintah yang cocok dengan alwaysPromptCommands daftar masih memerlukan izin eksplisit kecuali diganti oleh trustedShellCommands). Melewati --non-interactive dan --trust-all-tools diperlukan untuk pengalaman yang sepenuhnya otonom tetapi tidak diperlukan untuk melaksanakan transformasi. Gunakan dengan hati-hati di lingkungan produksi.

Menggunakan File Konfigurasi

AWS Transform custom mendukung file konfigurasi opsional dalam format YAML atau JSON. File konfigurasi memungkinkan Anda untuk menentukan parameter eksekusi dan memberikan konteks tambahan untuk agen.

Untuk menggunakan file konfigurasi:

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

Anda juga dapat memberikan konfigurasi sebagai pasangan nilai kunci sebaris:

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

Contoh file konfigurasi (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

Yang additionalPlanContext parameter memberikan konteks tambahan untuk rencana eksekusi agen. Hal ini sangat berguna dengan AWS-transformasi yang dikelola untuk menyesuaikan perilaku mereka untuk kebutuhan spesifik Anda.

Perintah Pembuatan dan Validasi

Perintah build atau validasi adalah parameter opsional yang menentukan cara memvalidasi kode Anda selama proses transformasi. AWS Transform custom akan mencoba menyimpulkan perintah build terbaik berdasarkan transformasi jika tidak ditentukan, meskipun disarankan untuk spesifik untuk kualitas.

Contoh perintah build dan validasi:

  • Jawa: mvn clean install atau gradle build

  • Python: pytest atau python -m py_compile

  • Node.js: npm run build atau npm test

  • Penunjuk: eslint . atau pylint .

Bahkan untuk bahasa atau transformasi yang tidak memerlukan pembangunan, memberikan perintah yang memvalidasi hasil dan mengembalikan masalah jika validasi gagal sangat penting untuk meningkatkan kualitas transformasi.

Jika tidak ada build atau validasi yang diperlukan, hilangkan dari input Anda.

Mengontrol Perilaku Belajar

Secara default, AWS Transform kustom mengekstrak pelajaran dari setiap eksekusi transformasi. Anda dapat mencegah pembelajaran untuk eksekusi tertentu.

Untuk mencegah pembelajaran dari eksekusi:

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

Yang -d atau --do-not-learn flag memilih untuk tidak mengizinkan ekstraksi pelajaran dari eksekusi saat ini.

Melanjutkan Percakapan

AWS Transform custom memungkinkan Anda melanjutkan percakapan sebelumnya dalam waktu 30 hari sejak pembuatan.

Untuk melanjutkan percakapan terbaru:

atx --resume

Untuk melanjutkan percakapan tertentu:

atx --conversation-id <conversation-id>
penting

Percakapan hanya dapat dilanjutkan dalam waktu 30 hari sejak pembuatan. Setelah 30 hari, percakapan tidak dapat lagi dilanjutkan.

Risalah Agen Pelacakan

AWS Ubah trek khusus menit agen dikonsumsi selama sesi transformasi. Menit agen terakumulasi sepanjang siklus percakapan dan ditampilkan saat percakapan berakhir:

Agent minutes used: 12.50

Menit agen tetap ada di seluruh interupsi. Jika Anda mengganggu sesi dengan Ctrl+C dan melanjutkannya nanti, menit yang terakumulasi sebelumnya terbawa dan terus terakumulasi dalam sesi yang dilanjutkan.

Untuk memeriksa Risalah Agen selama sesi interaktif:

Mengetik /usage pada prompt input untuk menampilkan akumulasi Menit Agen saat ini tanpa mengakhiri percakapan.

Untuk menetapkan batas anggaran Agen Minutes:

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

Yang --limit opsi menetapkan maksimum Risalah Agen anggaran untuk sesi. Menit Agen mencerminkan waktu kerja agen aktif, bukan waktu jam dinding. Ketika batas tercapai, CLI menampilkan pesan dan keluar dengan instruksi untuk melanjutkan:

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

Anda dapat melanjutkan percakapan nanti dengan batas yang meningkat:

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

Pembelajaran Berkelanjutan

Bagian ini menjelaskan cara meninjau dan mengelola pelajaran yang dibuat oleh pembelajaran berkelanjutan.

Memahami Pelajaran

Sistem pembelajaran berkelanjutan secara otomatis mengekstrak pelajaran dari proses transformasi sebelumnya. Sistem membuatnya secara asinkron berdasarkan:

  • Umpan balik pengembang diberikan dalam mode interaktif

  • Masalah kode yang dihadapi selama transformasi

Pelajaran terakumulasi dari waktu ke waktu saat Anda menjalankan transformasi di basis kode yang berbeda. Sistem menerapkannya secara otomatis untuk meningkatkan proses di masa mendatang. Setiap pelajaran termasuk dalam kategori yang berisi semua pelajaran dari domain serupa sehingga Anda dapat meninjau pelajaran terkait bersama-sama. Untuk pelajaran yang tidak ingin Anda gunakan, Anda dapat mengarsipkan atau menghapus pelajaran sepenuhnya.

Melihat dan Mengelola Pelajaran

Gunakan learnings perintah untuk membuka sesi interaktif untuk menelusuri dan mengelola pelajaran dari definisi transformasi.

Untuk membuka penampil pelajaran:

atx custom def learnings -n my-transformation

Penampil membuka daftar kategori pelajaran, masing-masing menunjukkan berapa banyak pelajaran aktif yang dikandungnya. Pilih kategori untuk melihat pelajarannya, lalu pilih pelajaran untuk melihat detail lengkapnya, termasuk isi pelajaran, dampaknya, dan berapa banyak proses sebelumnya yang dikonsultasikan.

Pengarsipan dan Memulihkan Pelajaran

Sistem menerapkan pelajaran secara otomatis. Jika Anda tidak ingin sistem menerapkan pelajaran, Anda dapat mengarsipkannya. Sistem menyimpan pelajaran yang diarsipkan tetapi tidak menerapkannya untuk proses di masa mendatang. Semua pelajaran yang diarsipkan dikelompokkan bersama sehingga Anda dapat meninjaunya dan mengembalikannya ke penggunaan aktif.

Menghapus Pelajaran

Hapus pelajaran yang tidak berguna secara permanen. Penghapusan tidak dapat dibatalkan, dan sistem mungkin mempelajari kembali pelajaran yang dihapus dari proses selanjutnya.

Pelajaran harus diarsipkan sebelum dapat dihapus.

Konfigurasi Lanjutan

Bagian ini menjelaskan fitur lanjutan dan opsi konfigurasi untuk AWS Ubah kustom.

Variabel lingkungan

Anda dapat menyesuaikan perilaku CLI menggunakan variabel lingkungan.

catatan

Contoh berikut menunjukkan sintaks Linux dan macOS (export). Di Windows, atur variabel lingkungan di PowerShell memakai $env:NAME="value". Lihat Jendela (PowerShell) tab untuk perintah yang setara.

ATX_SHELL_TIMEOUT

Ganti batas waktu default untuk perintah shell (900 seconds/15 menit).

Linux and macOS
export ATX_SHELL_TIMEOUT=1800 # 30 minutes
Windows (PowerShell)
$env:ATX_SHELL_TIMEOUT=1800 # 30 minutes

Ini berguna untuk basis kode besar atau proses build yang berjalan lama.

ATX_DISABLE_UPDATE_CHECK

Nonaktifkan pemeriksaan versi otomatis dan pembaruan pemberitahuan selama eksekusi perintah.

Linux and macOS
export ATX_DISABLE_UPDATE_CHECK=true
Windows (PowerShell)
$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME dan ATX_GIT_COMMITTER_EMAIL

Konfigurasikan identitas penulis yang digunakan untuk komit pos pemeriksaan AWS Transformasikan pembuatan kustom di repositori Anda karena menerapkan perubahan selama transformasi. Ketika variabel-variabel ini tidak disetel, commit pos pemeriksaan dikaitkan dengan identitas default (ATX Bot <checkpoint@atx.bot>). Atur kedua variabel untuk mengaitkan pos pemeriksaan ke penulis tertentu.

Linux and macOS
export ATX_GIT_COMMITTER_NAME="Jane Developer" export ATX_GIT_COMMITTER_EMAIL="jane@example.com"
Windows (PowerShell)
$env:ATX_GIT_COMMITTER_NAME="Jane Developer" $env:ATX_GIT_COMMITTER_EMAIL="jane@example.com"

Pengaturan Kepercayaan

Pengaturan kepercayaan memungkinkan Anda untuk menyetujui terlebih dahulu alat dan perintah tertentu untuk dieksekusi tanpa petunjuk. Anda juga dapat meminta izin eksplisit untuk perintah shell tertentu terlepas dari tingkat kepercayaan. Pengaturan ini dikonfigurasi di ~/.aws/atx/trust-settings.yaml berkas.

File berisi tiga daftar:

  • trustedTools - Alat yang dapat mengeksekusi tanpa meminta

  • trustedShellCommands - Perintah Shell yang dapat dieksekusi tanpa meminta

  • alwaysPromptCommands - Pola perintah Shell yang memerlukan izin eksplisit kecuali diganti oleh trustedShellCommands, terlepas dari -t tanda atau kepercayaan sesi. Pola-pola ini tidak diterapkan dalam mode non-interaktif (-x).

Alat tepercaya default:

  • file_read

  • get_transformation_from_registry

  • list_available_transformations_from_registry

Mengedit pengaturan kepercayaan:

Anda dapat mengedit file trust-settings.yaml secara manual untuk menambah atau menghapus alat dan perintah tepercaya. Keduanya trustedShellCommands dan alwaysPromptCommands mendukung pola wildcard glob menggunakan *.

catatan

Jika perintah cocok dengan kedua daftar, trustedShellCommands mengambil prioritas.

Berikut ini menjelaskan setiap daftar perintah dan memberikan contoh:

  • trustedShellCommands - Perintah yang cocok dengan pola ini dijalankan tanpa meminta, melewati semua pagar pembatas lainnya. Pola dicocokkan dengan string perintah lengkap.

    Contoh:

    • cd * - Cocokkan perintah majemuk dimulai dengan cd

    • *&&* - Mempercayai semua perintah dengan operator &&

  • alwaysPromptCommands - Perintah yang cocok dengan pola ini memerlukan izin eksplisit kecuali diganti oleh trustedShellCommands, terlepas dari -t tanda atau kepercayaan sesi. Pola-pola ini tidak diterapkan dalam mode non-interaktif (-x). Pola dicocokkan dengan setiap sub-perintah dalam ekspresi majemuk (&&, ||, substitusi perintah).

    Contoh:

    • rm -rf * - Selalu meminta perintah penghapusan paksa rekursif

    • sudo * - Selalu meminta perintah dijalankan dengan sudo

    • find * -exec * - Selalu meminta perintah find dengan -exec

Session-level kepercayaan:

Selama petunjuk interaktif, Anda dapat memilih:

  • (y)es - Jalankan sekali

  • (n)o - Menolak

  • (t)rust - Kepercayaan hanya untuk sesi saat ini

Session-level pengaturan kepercayaan bersifat sementara dan diatur ulang saat CLI dimulai ulang, memberikan persetujuan sementara tanpa mengubah trust-settings.yaml secara permanen.

catatan

Kepercayaan sesi tidak tersedia untuk perintah yang cocok dengan alwaysPromptCommands daftar.

Server Protokol Konteks Model (MCP)

Yang AWS Transform CLI mendukung server Model Context Protocol (MCP), yang memperluas fungsinya dengan alat tambahan.

Konfigurasi:

Konfigurasikan server MCP di ~/.aws/atx/mcp.json berkas. The AWS Transform CLI mendukung dua jenis server MCP: server berbasis perintah lokal dan server HTTP jarak jauh.

Server berbasis perintah lokal:

Server lokal berjalan sebagai proses anak pada mesin Anda. Konfigurasikan mereka dengan command properti:

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

Server HTTP jarak jauh:

Server jarak jauh terhubung ke server MCP yang dihosting di URL HTTP atau HTTPS. Konfigurasikan mereka dengan url properti:

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

Yang headers properti bersifat opsional dan mendukung ekspansi variabel lingkungan menggunakan ${VAR_NAME} sintaks. Ini memungkinkan Anda untuk menyimpan nilai sensitif seperti token API di variabel lingkungan daripada di file konfigurasi.

Properti konfigurasi:

Server berbasis perintah lokal mendukung properti berikut:

  • command (wajib) - Perintah untuk menjalankan server

  • args (opsional) - Array argumen baris perintah

  • env (opsional) - Variabel lingkungan untuk diteruskan ke proses server

Server HTTP jarak jauh mendukung properti berikut:

  • url (wajib) - URL HTTP atau HTTPS dari server MCP jarak jauh

  • headers (opsional) - header HTTP untuk disertakan dalam permintaan, dengan dukungan untuk ${VAR_NAME} ekspansi variabel lingkungan

Mengelola server MCP:

Lihat daftar server MCP yang dikonfigurasi:

atx mcp tools

Daftar alat yang tersedia yang ditawarkan oleh server MCP tertentu:

atx mcp tools --server <server-name>

Pelacakan penggunaan:

CLI secara otomatis melacak penggunaan alat MCP selama eksekusi transformasi. Statistik penggunaan dipertahankan sebagai mcp_usage.json di direktori percakapan di samping metadata.json. File mencatat metrik per alat untuk setiap eksekusi, termasuk:

  • Jumlah pemanggilan per alat

  • Jumlah kesalahan per alat

  • Total waktu eksekusi per alat

  • Detail kesalahan terakhir (jika ada)

Client-Side Keterampilan

Client-side keterampilan adalah kemampuan tambahan yang memperluas agen selama eksekusi transformasi. Mereka memungkinkan Anda untuk menyediakan alat khusus, skrip, dan instruksi yang dapat digunakan agen di samping kemampuan bawaannya.

Direktori penemuan keterampilan:

Keterampilan ditemukan dari empat direktori dalam urutan prioritas. Jika skill dengan nama yang sama ada di beberapa direktori, direktori pertama dalam daftar akan diprioritaskan:

  1. <project>/.aws/atx/skills/ - Project-level, AWS Transformasi CLI-specific

  2. <project>/.agents/skills/ - Project-level, lintas klien (tersedia untuk perkakas agen yang kompatibel)

  3. ~/.aws/atx/skills/ - User-level, AWS Transformasi CLI-specific

  4. ~/.agents/skills/ - User-level, lintas klien (tersedia untuk perkakas agen yang kompatibel)

Yang .aws/atx/skills/ Direktori khusus untuk AWS Ubah CLI. Yang .agents/skills/ direktori bersifat lintas klien, artinya keterampilan yang ditempatkan di sana tersedia untuk perkakas agen yang kompatibel di luar AWS Ubah CLI.

Struktur direktori keterampilan:

Setiap keterampilan adalah direktori yang berisi SKILL.md file dengan frontmatter YAML:

~/.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 format:

--- name: my-skill description: When to use this skill --- # Skill Title Instructions for the agent...

Yang name bidang harus cocok dengan nama direktori induk.

Menonaktifkan keterampilan:

Untuk mencegah skill dimuat tanpa menghapus file-nya, tambahkan disable-model-invocation: true ke materi depan:

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

Ketika properti ini disetel, CLI melewatkan keterampilan selama penemuan. Agen tidak dapat melihat atau menggunakan keterampilan kecuali definisi transformasi secara eksplisit menginstruksikannya untuk membaca file keterampilan. Gunakan ini untuk menonaktifkan keterampilan sementara, menandainya sebagai pekerjaan dalam proses, atau menyimpan materi referensi yang ditujukan untuk pembaca manusia saja.

catatan

File skill yang dinonaktifkan tetap ada di disk. Jika definisi transformasi menginstruksikan agen untuk membaca jalur file tertentu, agen masih dapat mengakses konten. Yang disable-model-invocation properti mencegah penemuan otomatis dan injeksi konteks, bukan akses sistem file.

Ketersediaan keterampilan berdasarkan mode eksekusi:

  • Mode eksekusi (atx custom def exec bersama --code-repository-path) - Menemukan keterampilan dari direktori tingkat pengguna dan tingkat proyek.

  • Mode interaktif (atx) - Hanya keterampilan tingkat pengguna yang ditemukan pada awalnya. Saat Anda menyediakan jalur repositori kode selama sesi, keterampilan tingkat proyek juga dimuat.

Memverifikasi penemuan keterampilan:

Periksa log debug CLI setelah dijalankan untuk memverifikasi keterampilan mana yang ditemukan:

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

Keterampilan yang gagal validasi dilewati dengan peringatan di log debug.

catatan

Client-side keterampilan membutuhkan CLI versi 2.0 atau lebih baru.

Memilih Antara Project-Level dan User-Level Keterampilan

Di mana Anda menempatkan keterampilan menentukan siapa yang mendapat manfaat darinya dan kapan itu aktif.

Project-level keterampilan (<project>/.aws/atx/skills/):

Komitmen ini ke kontrol versi sehingga setiap anggota tim yang menjalankan transformasi terhadap repositori secara otomatis menemukannya. Gunakan keterampilan tingkat proyek untuk:

  • Repository-specific pemeriksaan kepatuhan (aturan Dockerfile, kebijakan Terraform, validator keamanan migrasi)

  • Standar pengkodean organisasi yang berlaku untuk basis kode ini (pola pengamatan, penanganan kesalahan, konvensi penamaan)

  • Membangun atau menguji skrip yang unik untuk proyek (linters khusus, fungsi kebugaran arsitektur)

  • Panduan migrasi API untuk pustaka internal yang digunakan dalam repositori ini

User-level keterampilan (~/.aws/atx/skills/):

Ini tetap ada di mesin Anda dan aktif selama semua transformasi terlepas dari repositori mana yang Anda targetkan. Gunakan keterampilan tingkat pengguna untuk:

  • Alat alur kerja pribadi (generator changelog, pemformat pesan komit)

  • Cross-project preferensi (pola pengujian yang disukai, pengingat gaya dokumentasi)

  • Pemeriksaan kepatuhan lisensi yang diperlukan organisasi Anda di semua repositori

  • Ambang batas cakupan atau gerbang kualitas yang Anda terapkan pada setiap basis kode yang Anda gunakan

Kiat untuk keterampilan yang efektif:

  • Tulis jelas description bidang di Anda SKILL.md materi depan. Agen menggunakan bidang ini untuk memutuskan kapan keterampilan relevan.

  • Keluar dari skrip validasi dengan kode 0 saat berhasil dan bukan nol pada kegagalan. Agen menafsirkan kode keluar untuk menentukan kepatuhan.

  • Cetak pesan kesalahan yang jelas dan dapat ditindaklanjuti dalam skrip. Agen membaca output untuk memahami apa yang harus diperbaiki.

  • Tempatkan keterampilan di direktori lintas klien (.agents/skills/) di kedua tingkat untuk membagikannya dengan alat pengembangan AI lainnya di luar AWS Ubah CLI.

Client-Side Contoh Keterampilan

Contoh-contoh ini menunjukkan dua pola umum: keterampilan validasi berbasis skrip dan keterampilan referensi saja.

Contoh: Pemeriksa Kepatuhan Dockerfile (Script-Based)

Keterampilan ini memvalidasi Dockerfiles terhadap praktik terbaik keamanan dan operasional. Ini menggunakan skrip validasi yang dijalankan agen sebelum dan sesudah membuat perubahan.

Struktur direktori:

.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.

Skrip validasi memeriksa tag gambar dasar yang tidak disematkan, berjalan sebagai root, rahasia hardcode di ENV arahan, dan hilang HEALTHCHECK definisi. Agen menjalankan skrip, memperbaiki pelanggaran menggunakan pola dari file referensi, dan menjalankan ulang skrip untuk mengonfirmasi kepatuhan.

Contoh: API Deprecation Helper (Reference-Only)

Keterampilan ini memandu agen melalui penggantian panggilan API yang tidak digunakan lagi selama transformasi peningkatan. Ini hanya menggunakan file referensi tanpa skrip.

Struktur direktori:

.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

File referensi berisi contoh kode sebelum dan sesudah. Misalnya, aws-sdk-v2-to-v3.md peta pola seperti s3.putObject(params).promise() ke setara v3 modular menggunakan S3Client dan PutObjectCommand.

Tag dan Organisasi

Anda dapat mengatur definisi transformasi milik pelanggan dengan tag untuk kontrol akses, kategorisasi, dan alokasi biaya.

Anda dapat menambahkan, memperbarui, atau menghapus tag hanya pada definisi transformasi milik pelanggan. Anda tidak dapat mengelola tag pada AWS-Transformasi yang dikelola.

catatan

Beberapa perintah ini memerlukan penentuan Nama Sumber Daya Amazon (ARN) untuk Definisi Transformasi. Struktur ARN adalah: arn:aws:transform-custom:<region>:<account-id>:package/<td-name>

Untuk membuat daftar tag untuk transformasi:

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

Untuk menambahkan tag ke transformasi:

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

Untuk menghapus tag dari transformasi:

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

Tag dapat digunakan untuk kontrol akses yang dikelompokkan dalam kebijakan IAM. Anda dapat membuat kebijakan yang memberikan izin ke semua transformasi dengan tag tertentu (misalnya, semua transformasi yang ditandai dengan team:frontend atau environment:production).

Gunakan tag untuk alokasi biaya

Anda dapat menggunakan tag pada definisi transformasi milik pelanggan untuk mengatur AWS tagihan. AWS Transformasi rekaman kustom definisi transformasi sebagai sumber penagihan untuk Risalah Agen eksekusi mengkonsumsi. Setiap eksekusi mewarisi tag dari definisi transformasi yang dijalankannya. Jika beberapa tim atau proyek berbagi satu AWS akun, beri tag setiap definisi milik pelanggan dengan pemilik biayanya. Anda kemudian dapat memisahkan biaya transformasi untuk setiap tim atau proyek.

Setelah Anda menandai definisi transformasi milik pelanggan, aktifkan kunci tag tersebut di AWS Konsol Penagihan dan Manajemen Biaya. Nilai tag tidak muncul dalam data biaya Anda sampai kunci tag diaktifkan. Aktivasi berlaku untuk penggunaan ke depan. Untuk mengaitkan penggunaan dari bulan-bulan sebelumnya, minta pengisian ulang tag alokasi biaya. Untuk informasi lebih lanjut, lihat Alokasi biaya dan penandaan di AWS Panduan Pengguna Manajemen Penagihan dan Biaya.

Setelah kunci tag aktif, Anda dapat mengelompokkan AWS Ubah biaya dengan kunci itu di Cost Explorer. Anda juga dapat menyertakan ID sumber daya di AWS Laporan Biaya dan Penggunaan untuk melihat definisi transformasi ARN dan nilai tagnya pada setiap item baris. Untuk kolom yang membawa nilai-nilai tersebut, lihat Kolom tag sumber daya di AWS Panduan Pengguna Ekspor Data. Contoh berikut mengembalikan AWS Mengubah biaya dan Menulis Agen selama satu hari, dikelompokkan berdasarkan CostCenter tag.

aws ce get-cost-and-usage \ --time-period Start=2026-09-01,End=2026-09-02 \ --granularity DAILY \ --metrics UnblendedCost UsageQuantity \ --filter '{"Dimensions":{"Key":"SERVICE","Values":["AWS Transform"]}}' \ --group-by Type=TAG,Key=CostCenter

Cost Explorer mengembalikan biaya tanpa nilai untuk kunci sebagai grup tunggal dengan nilai kosong. Ini menunjukkan berapa banyak pengeluaran yang tetap tidak dikaitkan.

Apa yang tidak dapat Anda atributkan dengan tag

Tag-based atribusi beroperasi pada definisi transformasi. Konfirmasikan hal berikut terhadap model biaya Anda sebelum Anda mengandalkan tag untuk tagihan balik.

Penggunaan Mengapa itu tidak dikaitkan, dan apa yang harus dilakukan sebagai gantinya
AWS-transformasi yang dikelola Anda tidak dapat menambahkan, memperbarui, atau menghapus tag pada AWS-definisi transformasi yang dikelola. Biaya Agen Minutes mereka tidak mewarisi tag alokasi biaya yang ditentukan pelanggan.
Sesi yang tidak menjalankan definisi transformasi Menit Agen dikonsumsi dalam atx sesi yang tidak menjalankan definisi transformasi direkam tanpa ID sumber daya, jadi tidak ada sumber daya untuk mewarisi tag. Jalankan pekerjaan melalui definisi transformasi yang ditandai saat pengeluaran harus dikaitkan.
Eksekusi individu dari satu definisi Tag adalah properti dari definisi transformasi, bukan eksekusi, dan atx custom def exec tidak menerima tag. Semua eksekusi definisi berbagi nilai tagnya. Untuk memisahkan dua pemilik biaya, berikan masing-masing definisi transformasi sendiri.
Pengguna individu atau prinsipal IAM Biaya dikaitkan dengan definisi transformasi dan akun pelaksana, bukan dengan identitas yang memulai eksekusi. Per-user atribusi tidak tersedia melalui tag alokasi biaya.

Beberapa catatan

AWS Transform CLI memelihara tiga jenis log untuk pemecahan masalah dan debugging.

Log percakapan:

Linux and macOS
~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log
Windows
%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\<timestamp>-conversation.log

Log ini berisi riwayat percakapan lengkap untuk sesi tertentu.

Log subagen:

Linux and macOS
~/.aws/atx/custom/<conversation_id>/logs/subagents/<name>.log
Windows
%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\subagents\<name>.log

Log ini berisi output dari subagen yang muncul oleh agen utama selama transformasi. Anda tidak perlu mengelola subagen secara langsung.

Log debug pengembang:

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

Log ini menyediakan informasi pemecahan masalah lanjutan untuk CLI itu sendiri.

catatan

Mungkin ada beberapa file log debug di direktori log (yaitu debug1.log, debug2.log). Tinjau dan berikan semua log yang relevan misalnya, ~/.aws/atx/custom//<conversation-id>* dan ~/.aws/atx/logs/ *, saat membuka tiket dukungan untuk resolusi yang lebih cepat.

Pembaruan CLI

Perbarui CLI Anda untuk mengakses fitur dan peningkatan baru.

Untuk memeriksa pembaruan:

atx update --check

Untuk memperbarui ke versi terbaru:

atx update

Untuk memperbarui ke versi tertentu:

atx update --target-version <version>

Buat Transformasi Kustom

Bagian ini menjelaskan cara membuat, memodifikasi, dan mengelola definisi transformasi kustom.

Membuat Transformasi Baru

Gunakan CLI interaktif untuk membuat definisi transformasi baru.

Untuk membuat definisi transformasi

  1. Mulai AWS Ubah CLI:

    atx
  2. Beri tahu agen Anda ingin membuat transformasi baru.

  3. Berikan deskripsi yang jelas dan terperinci tentang tujuan transformasi. Termasuk:

    • Status sumber dan target (misalnya, “upgrade dari versi X ke versi Y”)

    • Diperlukan perubahan spesifik (misalnya, “perbarui pernyataan impor, ganti metode yang tidak digunakan lagi”)

    • Pertimbangan atau kendala khusus

  4. Ketika agen meminta klarifikasi atau informasi tambahan, berikan contoh spesifik dan bahan referensi.

  5. Tinjau definisi transformasi awal yang dibuat oleh agen.

  6. Uji transformasi pada basis kode sampel.

  7. Iterasi dengan memberikan umpan balik, perbaikan kode, atau contoh tambahan.

  8. Simpan transformasi secara lokal atau publikasikan ke registri.

Praktik terbaik untuk membuat transformasi:

  • Mulailah dengan transformasi sederhana dan terdefinisi dengan baik sebelum mencoba yang kompleks

  • Menyediakan bahan referensi yang komprehensif termasuk panduan migrasi dan sampel kode

  • Uji pada beberapa basis kode sampel sebelum menerbitkan

  • Gunakan perintah build atau validasi deterministik untuk memungkinkan pembelajaran berkelanjutan

  • Pertimbangkan memecah transformasi kompleks menjadi beberapa langkah yang lebih kecil

  • Tandai informasi penting dengan “KRITIS:” atau “PENTING:” dalam definisi transformasi Anda untuk memastikan agen memprioritaskan persyaratan ini

  • Ketika Anda memerlukan persyaratan yang tepat diikuti (seperti menggunakan perintah atau nilai string tertentu), secara eksplisit tentukan string lengkap dalam definisi transformasi Anda. Anda dapat membungkusnya dalam tanda kutip bash untuk menunjukkan dengan jelas bahwa itu adalah perintah terminal atau string literal, yang mengurangi variabilitas dan memastikan eksekusi yang konsisten

Menyediakan Bahan Referensi

Anda dapat memberikan file referensi ke AWS Ubah kustom dengan menentukan jalur file selama percakapan. File-file ini disimpan di references/ folder definisi transformasi.

Jenis file referensi yang direkomendasikan:

  • Before/after contoh kode

  • Dokumentasi untuk API, pustaka, atau fitur yang terlibat

  • Human-readable panduan migrasi

Untuk menyediakan file referensi:

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

Anda juga dapat menyediakan direktori yang berisi beberapa file referensi:

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

Hanya file berbasis teks (.md, .html, .txt, file kode) yang didukung. File biner, gambar, dan file teks kaya (mis., .pdf, .png, .docx) saat ini tidak didukung. Seringkali dimungkinkan untuk mengekstrak konten teks dan menggunakannya sebagai referensi. Jika Anda memiliki banyak file teks kecil, pertimbangkan untuk menggabungkannya menjadi beberapa file dengan nama deskriptif. Ada batas total 10MB untuk semua file.

Memodifikasi Transformasi yang Ada

Anda dapat memodifikasi transformasi kustom sebelum dan sesudah menyimpannya sebagai draf atau menerbitkannya. Anda tidak dapat memodifikasi AWS-Transformasi yang dikelola. Jika Anda perlu menyesuaikannya, Anda dapat memberikan konteks tambahan menggunakan file konfigurasi.

Untuk memodifikasi transformasi yang ada

  1. Mulai AWS Ubah CLI:

    atx
  2. Beri tahu agen Anda ingin memodifikasi transformasi yang ada.

  3. Pilih apakah akan:

    • Menyediakan jalur file ke transformasi yang disimpan secara lokal (yaitu bukan draf yang disimpan atau diterbitkan)

    • Minta daftar transformasi dari registri

  4. Jika memilih dari registri, pilih transformasi yang ingin Anda modifikasi.

  5. Bekerja dengan agen untuk menjelaskan perubahan yang ingin Anda buat.

  6. Uji transformasi yang diperbarui pada basis kode sampel.

  7. Publikasikan pembaruan Anda ke registri jika diinginkan.

Menerbitkan dan Mengelola Transformasi

Anda dapat mempublikasikan dan mengelola transformasi Anda menggunakan pengalaman interaktif atau dengan perintah berikut.

Untuk menyimpan transformasi sebagai draf:

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

Untuk menerbitkan transformasi:

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

Untuk daftar transformasi yang tersedia:

atx custom def list

Untuk mengunduh definisi transformasi:

atx custom def get -n my-transformation

Ini mengunduh definisi transformasi ke direktori kerja Anda saat ini. Anda dapat menentukan direktori target dengan --td bendera dan versi dengan --tv bendera.

Untuk menghapus definisi transformasi:

atx custom def delete -n my-transformation
penting

Ini secara permanen menghapus definisi transformasi yang ditentukan dari akun Anda.

Mengelola Versi Transformasi

AWS Transform custom mempertahankan versi definisi transformasi Anda. Anda dapat menentukan versi saat menjalankan atau mengunduh transformasi.

Untuk mengeksekusi versi tertentu:

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

Untuk mengunduh versi tertentu:

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

Jika tidak ada versi yang ditentukan, versi terbaru digunakan.