기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 사용자 지정
## 사용자 지정 AWS 변환이란 무엇입니까?
AWS 사용자 지정 변환은 에이전트 AI를 사용하여 소프트웨어, 코드, 라이브러리 및 프레임워크를 대규모로 현대화하여 기술 부채를 줄입니다. 언어 버전 업그레이드, API 및 서비스 마이그레이션, 프레임워크 업그레이드 및 마이그레이션, 코드 리팩터링, 조직별 변환을 비롯한 다양한 시나리오를 처리합니다.
에이전트는 지속적인 학습을 통해 모든 실행 및 개발자 피드백을 개선하여 특별한 자동화 전문 지식 없이도 고품질의 반복 가능한 변환을 제공합니다.
### 주요 기능
AWS 사용자 지정 변환은 다음과 같은 기능을 제공합니다.
+ **자연어 기반 변환 정의** - 자연어, 설명서 및 코드 샘플을 사용하여 사용자 지정 변환 생성
+ **변환 실행** - 여러 코드베이스에 걸쳐 일관되고 안정적으로 변환 적용
+ **지속적인 학습** - 모든 실행에서 변환 품질 자동 개선
+ **AWS관리형 변환 -** 일반적인 시나리오ready-to-use 수 있는 AWS검증된 변환 사용
### 변환 패턴
AWS 변환 사용자 지정은 현대화 요구 사항을 해결하기 위해 다양한 변환 패턴을 지원합니다. 각 패턴은 필요한 변경 사항의 범위와 특성에 따라 복잡성 특성이 다릅니다.
| 패턴 | 설명 | 복잡성 | 예제 |
| --- | --- | --- | --- |
| API 및 서비스 마이그레이션 | 기능을 유지하면서 API 버전 또는 동등한 서비스 간에 마이그레이션 | 중간 | AWS SDK v1→v2(Java, Python, JavaScript), Boto2→Boto3, JUnit 4→5, javax→jakarta |
| 언어 버전 업그레이드 | 동일한 프로그래밍 언어의 최신 버전으로 업그레이드, 새로운 기능 채택 및 더 이상 사용되지 않는 기능 교체 | Low-Medium | Java 8→17, Python 3.9→3.13, Node.js 12→22, TypeScript 버전 업그레이드 |
| 프레임워크 업그레이드 | 동일한 프레임워크의 최신 버전으로 업그레이드하여 주요 변경 사항 해결 | 중간 | Spring Boot 2.x→3.x, React 17→18, Angular 업그레이드, Django 업그레이드 |
| 프레임워크 마이그레이션 | 유사한 목적을 제공하는 완전히 다른 프레임워크로 마이그레이션 | 높음 | Angular→React, Redux→Zustand, Vue.js→React |
| 라이브러리 및 종속성 업그레이드 | 동일한 언어와 프레임워크를 유지하면서 타사 라이브러리를 최신 버전으로 업그레이드 | Low-Medium | Pandas 1.x→2.x, NumPy 업그레이드, Hadoop/HBase/Hive 라이브러리 업그레이드, Lodash 업그레이드 |
| 코드 리팩터링 및 패턴 현대화 | 외부 기능을 변경하지 않고 코드 패턴 현대화 및 모범 사례 채택 | Low-Medium | 인쇄→로깅 프레임워크, 문자열 연결→f-문자열, 유형 힌트 채택, 관찰성 계측 |
| 스크립트 및 File-by-File 번역 | 파일이 대부분 독립형인 독립 스크립트 또는 구성 파일 번역 | Low-Medium | AWS CDK→Terraform, Terraform→CloudFormation, Excel→Python 노트북, Bash→PowerShell |
| 아키텍처 마이그레이션 | 코드 변경을 최소화하면서 하드웨어 아키텍처 또는 런타임 환경 간에 마이그레이션 | 중간-높음 | x86→AWS Graviton(ARM), 온프레미스→Lambda, 기존 서버→컨테이너 |
| Language-to-Language 마이그레이션 | 한 프로그래밍 언어에서 다른 프로그래밍 언어로 코드베이스 변환 | 매우 높음 | Java→Python, JavaScript→TypeScript, C→Rust, Python→Go |
| 사용자 지정 및 조직별 변환 | 고유한 조직 요구 사항 및 특수 현대화 요구 사항 | 다양 | 사용자 지정 내부 라이브러리 마이그레이션, 조직별 코딩 표준, 독점 프레임워크 마이그레이션 |
**참고**
COBOL/메인프레임 언어의 경우 메인프레임 AWS 변환을 사용합니다. .NET Core로 .NET Framework를 업그레이드하려면 Windows용 AWS 변환을 고려하세요. VMware 마이그레이션의 경우 VMware용 AWS 변환을 AWS고려하세요.
### 사용자 지정 AWS 변환 작동 방식
AWS 변환 사용자 지정은 일반적으로 여러 코드베이스 또는 모듈이 변환되는 대규모 프로젝트에서 사용됩니다. 팀은 일반적으로 4단계 워크플로를 따릅니다.
**변환 정의** - 에이전트에 자연어 프롬프트, 설명서 및 코드 샘플을 제공하여 초기 변환 정의를 생성합니다. 채팅 또는 직접 편집을 통해이 정의를 반복적으로 개선할 수 있습니다. AWS관리형 변환을 사용할 때는이 단계를 건너뛸 수 있습니다.
**파일럿 또는 Proof-of-Concept** 샘플 코드베이스에서 변환을 테스트하고 결과를 기반으로 구체화합니다. 이 검증 단계는 전체 변환의 비용과 노력을 추정하는 데 도움이 됩니다. 지속적인 학습은이 단계에서 품질을 개선합니다.
**확장된 실행** - 개발자가 결과를 검토하고 검증하여 CLI를 사용하여 자동 대량 실행을 설정합니다. 웹 애플리케이션을 사용하여 진행 상황을 모니터링하고 여러 리포지토리에서 변환을 추적합니다.
**모니터링 및 검토** - 지속적인 학습은 변환 품질을 자동으로 개선합니다. 이전 실행에서 추출한 교훈을 검토하여 품질 표준을 충족하는지 확인하고 유용하지 않은 내용을 보관합니다.
## 주요 개념 이해
이 섹션에서는 사용자 지정 AWS 변환 작업을 위한 주요 개념을 설명합니다.
### 변환 정의
**변환 정의**에는 특정 코드 변환을 수행하는 데 필요한 지침과 지식이 포함되어 있습니다. 스킬로 표현되며 다음으로 구성됩니다.
+ `SKILL.md` (필수) - 코어 변환 로직 및 실행 지침이 포함된 YAML 프론트미터(`name` 및 `description` 필드)를 사용한 마크다운의 지침
+ `references/` 폴더(선택 사항) - 변환 실행 중에 필요에 따라 로드된 설명서
+ `scripts/` 폴더(선택 사항) - 실행 중에 변환이 다운로드하고 실행하는 스크립트
AWS 변환 CLI는 실행, 검사 또는 수정에 필요한 경우 변환 정의를 현재 디렉터리에 자동으로 다운로드합니다.
**중요**
변환을 게시할 때 디렉터리에는 `SKILL.md` 선택적으로 `references/` 폴더, `scripts/` 폴더 또는 둘 다만 포함되어야 합니다. 다른 파일 또는 하위 디렉터리는 허용되지 않습니다.
**참고**
CLI 버전 2.0 이상에서는 기술 형식을 사용합니다. 기존 변환 정의는 CLI에서 자동으로 처리됩니다.
### 변환 정의 범주
변환 정의에는 사용 방법을 나타내는 **범주**가 있을 수 있습니다.
+ `analysis` - 코드를 읽고 결과를 보고합니다. 지속적인 현대화는 이러한 변환 정의를 사용자 지정 분석으로 실행합니다.
+ `remediation` - 코드를 변경합니다. 지속적인 현대화는 이러한 변환 정의를 사용하여 결과를 해결합니다.
`atx custom def publish` 또는 `--category` 옵션을 사용하여 범주를 설정합니다`atx custom def save-draft`.
```
atx custom def publish -n --description "Description" --sd --category analysis
atx custom def publish -n --description "Description" --sd --category remediation
atx custom def list # The Category column shows each transformation definition's category
```
AWS 변환은 범주를 사용하여 변환 정의를 사용할 수 있는 위치를 결정합니다.
| 사용 | 허용된 변환 정의 |
| --- | --- |
| 사용자 지정 분석(--type custom) | analysis 범주가 있는 자체 변환 정의 |
| 를 사용한 문제 해결 --transformation-name | remediation 범주가 있는 자체 변환 정의 또는 AWS 관리형 변환 |
사용자 지정 분석, 일정 또는 수정을 제출하기 전에 AWS 변환은 변환 정의의 범주를 확인합니다.
변환 정의의 범주를 변경하려면 다른 `--category` 값으로 다시 게시합니다. 없이 새 버전을 게시하는 경우 새 버전`--category`은 이전 버전의 범주를 유지합니다.
`analysis` 변환 정의를 실행하는 방법은 섹션을 참조하세요[사용자 지정 분석](ct-working-with.md#ct-custom-analysis).
**참고**
범주는 리소스 태그와 다릅니다. 리소스 태그를 관리하려면 섹션을 참조하세요[태그 명령](custom-command-reference.md#custom-tag-commands).
#### 분석을 위한 변환 정의 작성
유용한 결과를 얻으려면 검색해야 할 사항, 각 문제를 분류하는 방법 및 수행하지 말아야 할 사항을 설명하도록 변환 정의를 작성합니다. 에서 다음 섹션을 사용하는 것이 좋습니다`SKILL.md`.
| 섹션 | 포함할 항목 |
| --- | --- |
| 소개 | 분석에서 찾은 내용을 설명하는 문장 하나 또는 두 개. 읽기 전용이며 파일을 수정해서는 안 된다고 명시합니다. |
| 입력 기준 | "리포지토리에 pom.xml 또는 build.gradle 파일이 포함되어 있습니다"와 같이 분석이 적용되는 경우 |
| Scope | 검사할 파일 및 디렉터리와 빌드 출력 및 공급업체 종속성과 같이 건너뛸 파일 및 디렉터리입니다. |
| 보고할 사항 | 문제로 간주되는 특정 패턴 또는 조건입니다. 파일 경로와 줄 번호를 사용하여 문제당 하나의 결과를 요청합니다. |
| Categories | 작고 고정된 범주 값 세트로, 각각에 속하는 문제입니다. |
| 심각도 기준 | 무엇이 high, medium또는 문제를 일으킵니다low. |
| 종료 기준 | 에이전트가이 작업이 완료되었는지 확인하는 방법: 범위 내 모든 파일이 검사되었고, 모든 결과에 파일, 범주 및 심각도가 있으며, 파일이 변경되지 않았습니다. 또한 아무것도 찾을 수 없을 때 보고할 내용을 설명합니다. |
다음 예제에서는 여전히 17 이전의 Java 버전을 대상으로 하는 Java 프로젝트를 찾습니다.
```
---
name: java-version-detector
description: Report where a repository still targets a Java version earlier than 17, in build files, Dockerfiles, toolchain files, and CI workflows. Analysis only - no code is modified.
---
# Java Version Detector
Find where the repository targets a Java version earlier than Java 17. This is a
read-only analysis: report findings, and do not modify any files.
## Entry Criteria
The repository contains a Java build file (`pom.xml`, `build.gradle`,
`build.gradle.kts`, or `gradle.properties`), or a file that selects a JDK
(`.java-version`, `.tool-versions`, `.sdkmanrc`, a `Dockerfile`, or a file under
`.github/workflows/`).
## Scope
- Inspect build files, toolchain files, Dockerfiles, and CI workflow files.
- Skip build output (`build/`, `target/`) and vendored dependencies.
## What to Report
Report one finding for each place that selects a Java version earlier than 17:
1. A compile target, such as `maven.compiler.source`, `maven.compiler.release`,
`java.version`, `sourceCompatibility`, or a Gradle toolchain `languageVersion`.
2. A Dockerfile base image that ships a JDK or JRE earlier than 17, such as
`openjdk:8` or `amazoncorretto:11`.
3. A CI job or toolchain file that selects a JDK earlier than 17.
For each finding, include the file path, the line number, and the version you found.
## Categories
- `outdated-compile-target` - a build file compiles for an old Java version
- `outdated-runtime-image` - a Dockerfile uses an old JDK or JRE image
- `outdated-ci-jdk` - a CI workflow or toolchain file selects an old JDK
## Severity Criteria
- **high** - the project compiles for Java 8 or earlier
- **medium** - the project compiles for Java 9 through 16
- **low** - only the runtime image or CI uses an old JDK, and the compile target is 17 or later
## Exit Criteria
1. Every in-scope file has been inspected.
2. Every finding has a file path, line number, category, and severity from the lists above.
3. No file in the repository has been modified.
4. If nothing is found, state that the repository targets Java 17 or later.
```
이 변환 정의는이 로 `pom.xml` 설정된 프로젝트에 대해 실행`1.8`될 때 수정으로를 `AWS/java-version-upgrade` 사용하여 `outdated-compile-target` 범주에 `high` 심각도 조사 결과를 생성합니다.
**분석 변환 정의 작성 팁**
+ **읽기 전용으로 유지합니다.** 분석을 통해 파일을 수정해서는 안 된다고 명시적으로 명시합니다. 문제 해결은 문제 해결의 작업입니다.
+ **문제로 간주되는 항목에 대해 구체적으로 설명하십시오.** 찾을 파일, 설정 및 패턴의 이름을 지정합니다. 모호한 지침은 일관되지 않은 결과를 생성합니다.
+ **문제당 하나의 결과를 요청합니다.** 각 결과는 개별적으로 검토하고 수정할 수 있도록 특정 파일과 줄을 가리켜야 합니다.
+ **변환 정의에서 심각도와 범주를 정의합니다.** 에이전트는 기준을 사용하여 각 결과를 분류합니다.
+ **범위를 집중적으로 유지합니다.** 사용자 지정 분석은 변환 정의에서 설명하는 내용만 보고합니다. 다양한 종류의 문제를 찾으려면 별도의 변환 정의를 작성하거나 기본 제공 분석 유형을 사용합니다.
+ **아무 것도 찾을 수 없을 때 수행할 작업을 설명합니다.** 문제가 없는 리포지토리는 0개의 결과를 올바르게 생성합니다.
+ **변환 정의에 결과 지침을 포함합니다.** 분석을 실행할 `--configuration` 때 `-g` 또는를 사용하여 구성을 전달하면 AWS 변환은 기본 지침 대신 구성을 사용합니다. 에서 "보고할 사항" 섹션을 유지`SKILL.md`하면 변환 정의가 어느 쪽이든 결과를 생성합니다.
게시하기 전에 문제가 포함된 것으로 알고 있는 리포지토리에서 변환 정의를 테스트합니다. 를 사용하여 초안으로 저장`atx custom def save-draft`하거나를 사용하여 로컬에서 실행합니다`atx ct analysis run`( 참조[사용자 지정 분석](ct-working-with.md#ct-custom-analysis)).
### 변환 레지스트리
**변환 레지스트리**는 변환 정의를 저장하고 관리하기 위한 AWS 계정의 중앙 집중식 리포지토리입니다. 레지스트리의 변환은 다음과 같을 수 있습니다.
+ 를 사용하여 나열됨 `atx custom def list`
+ 여러 코드베이스에서 실행됨
+ AWS 계정의 다른 사용자와 공유
+ 버전 관리형
**중요**
변환 정의는 계정별로 다릅니다. 다른 AWS 계정에서 변환을 사용하려면 해당 계정에 별도로 게시해야 합니다.
### 초안 변환과 게시된 변환 비교
AWS 변환 사용자 지정은 레지스트리의 변환에 대해 두 가지 상태를 지원합니다.
**초안 변환**은 진행 중이거나 테스트되지 않은 변환 정의입니다. 특정 버전으로 저장되며 해당 특정 버전을 참조하는 사용자가 검색, 업데이트 및 실행할 수 있습니다. 초안은 팀과 변환을 공유할 준비가 되기 전에 반복 개발, 테스트 및 개선에 유용합니다. 초안은 특정 대화에도 연결됩니다. CLI를 다시 시작하는 경우를 사용하여 이전 CLI를 복원`atx --conversation-id {id}`할 수 있습니다.
**게시된 변환**은 필요한 IAM 권한이 있는 다른 사용자가 실행할 수 있도록 계정의 변환 레지스트리에서 사용할 수 있습니다. 게시된 변환은를 사용하여 검색할 수 있습니다`atx custom def list`.
일반적인 워크플로는 다음과 같습니다.
1. 로컬에서 변환 생성
1. 테스트를 위해 초안으로 저장(`atx custom def save-draft`)
1. 구체화 및 검증
1. 게시하여 팀과 공유(`atx custom def publish`)
변환을 초안으로 저장하지 않고 직접 게시할 수도 있습니다.
### 참조와 교훈 비교
AWS 변환 사용자 지정은 두 가지 유형의 지식을 사용하여 변환 품질을 개선합니다.
**참조**는 변환 정의의 `references/` 폴더에 저장된 사용자 제공 설명서입니다. 참조는 텍스트 파일(모든 파일의 경우 최대 총 10MB)만 지원하며 일반적으로 설명서, API 사양, 마이그레이션 가이드 및 코드 샘플을 포함합니다. 참조는 변환 실행 중에 필요에 따라 로드됩니다. 대화형 모드에서 변환 정의를 생성하거나 업데이트할 때 참조를 추가합니다.
**단원**은 이전 변환 실행에서 자동으로 추출됩니다. 지속적 학습 시스템은 실행 궤적, 개발자 피드백 및 변환 중에 발생하는 코드 수정에서 이를 생성합니다. 관련 교훈을 범주로 그룹화하여 함께 검토할 수 있습니다. 선결제를 제공하는 참조와 달리, 여러 코드베이스에서 변환을 실행하면 시간이 지남에 따라 교훈이 누적되고 시스템은 이를 자동으로 적용하여 향후 실행을 개선합니다. 를 사용하여 대화형으로 단원을 검토하고 관리합니다`atx custom def learnings`.
### 빌드 및 검증 명령
**빌드 또는 검증 명령**은 변환 프로세스 중에 코드를 검증하는 방법을 지정하는 선택적 파라미터입니다. 이 명령은 코드 무결성을 보장하기 위해 변환 중 다양한 지점에서 실행됩니다.
결과를 검증하고 검증에 실패할 경우 문제를 반환하는 명령을 제공하는 것은 지속적인 학습을 통해 변환 품질을 개선하는 데 매우 중요합니다. 빌드 또는 검증이 필요하지 않은 경우 입력에서를 생략합니다.
예제와 자세한 지침은 워크플로 섹션의 빌드 및 검증 명령을 참조하세요.
### 지속적인 학습
**지속적인 학습**은 모든 변환 실행의 피드백을 자동으로 캡처하고 시간이 지남에 따라 변환 품질을 개선하는 시스템입니다. 시스템은 다음을 통해 정보를 수집합니다.
+ 명시적 피드백 - 대화형 모드에서 제공되는 설명 및 코드 수정
+ 암시적 관찰 - 코드를 변환하고 디버깅하는 동안 에이전트가 발견하는 문제
지속적 학습 시스템은이 정보를 처리하여 향후 변환을 개선하기 위해 변환 정의에 추가하는 **교훈**을 생성합니다. 시스템은 변환이 완료된 후 학습 프로세스를 자동으로 실행하므로 사용자의 추가 입력이 필요하지 않습니다.
**중요**
교훈은 변환별로 다르며 다른 변환 또는 다른 고객 계정 간에 공유되지 않습니다.
#### 단원 관리
시스템은 자동으로 레슨을 생성하지만 향후 실행에 적용되는 레슨은 사용자가 계속 제어할 수 있습니다. `atx custom def learnings` 명령은 변환이 누적한 교훈을 검토하고 큐레이션하기 위한 대화형 터미널 세션을 엽니다.
이 세션에서는 다음을 수행할 수 있습니다.
+ 범주로 그룹화된 단원을 찾아보고 각 범주에 포함된 활성 단원의 수를 확인합니다.
+ 단원을 열어 단원 본문, 단원 본문의 영향, 해당 단원을 참조한 이전 실행 수를 비롯한 전체 세부 정보를 읽습니다.
+ 시스템이 향후 실행에 적용하지 못하도록 단원을 보관하고 필요한 경우 나중에 복원합니다.
+ 더 이상 유용하지 않은 보관된 단원을 영구적으로 삭제합니다.
단계별 지침은 [지속적인 학습](custom-workflows.md#custom-continual-learning)섹션을 참조하세요.
### 클라이언트 측 기술
**클라이언트 측 기술은** 변환 실행 중에 에이전트를 확장하는 추가 기능입니다. 수행할 변환을 정의하는 변환 정의와 달리 클라이언트 측 기술은 에이전트가 변환 중에 내장 기능과 함께 사용할 수 있는 보조 도구, 스크립트 및 지침을 제공합니다.
클라이언트 측 스킬은 프로젝트 수준 및 사용자 수준 디렉터리에서 발견됩니다. 리포지토리에 특정한 표준을 적용할 때는 프로젝트 수준에서, 모든 프로젝트에 적용할 때는 사용자 수준에서 기술을 배치합니다. 프로젝트 수준 스킬은 코드 리포지토리 경로가 제공된 경우에만 사용할 수 있습니다. 자세한 구성 및 사용량은 섹션을 참조하세요[클라이언트 측 기술](custom-workflows.md#custom-client-side-skills).
## 사용자 지정 변환 명령 소개
다음은 사용자 지정 변환에 사용할 수 있는 몇 가지 명령입니다. 명령의 전체 목록은 사용자 [AWS 지정 변환 변환 명령 참조에 있습니다](https://docs.aws.amazon.com/transform/latest/userguide/custom-command-reference.html).
+ `atx custom`
+ **사용자 지정 변환 대화형 환경을 실행하여 변환의 생성, 검색, 실행 및 구체화를 허용합니다.**
+ 의 기본 명령입니다`atx`.
+ `--trust-all-tools` (`-t`)는 선택 사항이며 에이전트가 요청한 모든 도구 요청을 암시적으로 허용합니다. 특히 프로덕션 환경에서는 주의해야 합니다. 신뢰 [설정 파일을 사용하여 특정 도구 및 명령에 대한 도구 신뢰를](https://docs.aws.amazon.com/transform/latest/userguide/custom-workflows.html#custom-advanced-configuration) 구성할 수 있습니다.
+ `atx custom --help` \| `atx custom -h`
+ **도움말 메뉴를 표시합니다.**
+ 각 명령에는와 같은 도움말 메뉴도 포함되어 있습니다`atx custom def exec --help`.
+ `atx --version` \| `atx -v`
+ **버전을 표시합니다.**
+ 버전 번호는 릴리스마다 변경됩니다.
+ `atx custom def list`
+ **변환 레지스트리에서 사용 가능한 변환 목록을 인쇄합니다.**
+ `atx custom def exec`
+ **변환을 실행합니다.**
+ `atx custom def learnings`
+ **대화형 세션을 열어 변환이 이전 실행에서 학습한 교훈을 보고 관리합니다.**
+ `atx mcp`
+ **MCP 서버 구성을 관리하는 데 사용됩니다.**