기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

워크플로

변환 실행

이 섹션에서는 변환을 실행하는 다양한 방법과 실행 동작을 제어하는 옵션에 대해 설명합니다.

실행 모드

AWS 사용자 지정 변환은 서로 다른 워크플로를 수용하기 위해 세 가지 실행 모드를 지원합니다.

대화형 대화 모드

로 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을 실행할 때 일반적으로 다음 플래그가 사용됩니다.

구성 파일 사용

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 변환 사용자 지정은 지정되지 않은 경우 변환을 기반으로 최상의 빌드 명령을 추론하려고 시도하지만 품질에 특정한 것이 좋습니다.

빌드 및 검증 명령의 예:

빌드가 필요하지 않은 언어 또는 변환의 경우에도 결과를 검증하고 검증에 실패할 경우 문제를 반환하는 명령을 제공하는 것이 변환 품질을 개선하는 데 매우 중요합니다.

빌드 또는 검증이 필요하지 않은 경우 입력에서를 생략합니다.

학습 동작 제어

기본적으로 AWS 변환 사용자 지정은 모든 변환 실행에서 교훈을 추출합니다. 특정 실행에 대한 학습을 방지할 수 있습니다.

실행에서 학습하지 않으려면:

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

-d 또는 --do-not-learn 플래그는 현재 실행에서 레슨 추출을 허용하지 않도록 옵트아웃합니다.

대화 재개

AWS 사용자 지정 변환을 사용하면 생성 후 30일 이내에 이전 대화를 재개할 수 있습니다.

가장 최근 대화를 재개하려면:

atx --resume

특정 대화를 재개하려면:

atx --conversation-id <conversation-id>

추적 에이전트 분

AWS 사용자 지정 변환은 변환 세션 중에 사용된 에이전트 시간을 추적합니다. 에이전트 시간은 대화 수명 주기 동안 누적되며 대화가 종료될 때 표시됩니다.

Agent minutes used: 12.50

에이전트 시간은 중단 후에도 지속됩니다. Ctrl+C로 세션을 중단했다가 나중에 재개하는 경우 이전에 누적된 분은 이월되어 재개된 세션에서 계속 누적됩니다.

대화형 세션 중에 Agent Minutes를 확인하려면:

입력 프롬프트/usage에를 입력하여 대화를 종료하지 않고 현재 누적된 Agent Minutes를 표시합니다.

에이전트 분 예산 한도를 설정하려면:

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 동작을 사용자 지정할 수 있습니다.

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

AWS 변환 중에 변경 사항을 적용할 때 변환 사용자 지정이 리포지토리에 생성하는 체크포인트 커밋에 사용되는 작성자 자격 증명을 구성합니다. 이러한 변수를 설정하지 않으면 체크포인트 커밋은 기본 자격 증명()에 귀속됩니다ATX Bot <checkpoint@atx.bot>. 체크포인트를 특정 작성자로 속성 지정하도록 두 변수를 설정합니다.

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"

신뢰 설정

신뢰 설정을 사용하면 프롬프트 없이 실행할 특정 도구 및 명령을 사전 승인할 수 있습니다. 신뢰 수준에 관계없이 특정 셸 명령에 대한 명시적 권한을 요구할 수도 있습니다. 이러한 설정은 ~/.aws/atx/trust-settings.yaml 파일에서 구성됩니다.

파일에는 다음 세 가지 목록이 포함되어 있습니다.

신뢰할 수 있는 기본 도구:

신뢰 설정 편집:

trust-settings.yaml 파일을 수동으로 편집하여 신뢰할 수 있는 도구 및 명령을 추가하거나 제거할 수 있습니다. trustedShellCommands 및 모두를 사용하여 glob 와일드카드 패턴을 alwaysPromptCommands 지원합니다*.

다음은 각 명령 목록을 설명하고 예제를 제공합니다.

세션 수준 신뢰:

대화형 프롬프트 중에 다음을 선택할 수 있습니다.

세션 수준 신뢰 설정은 일시적이며 CLI가 다시 시작될 때 재설정되므로 trust-settings.yaml을 영구적으로 수정하지 않고 임시 승인을 제공합니다.

모델 컨텍스트 프로토콜(MCP) 서버

AWS 변환 CLI는 추가 도구를 사용하여 기능을 확장하는 모델 컨텍스트 프로토콜(MCP) 서버를 지원합니다.

구성:

~/.aws/atx/mcp.json 파일에서 MCP 서버를 구성합니다. AWS 변환 CLI는 로컬 명령 기반 서버와 원격 HTTP 서버의 두 가지 유형의 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 토큰과 같은 민감한 값을 저장할 수 있습니다.

구성 속성:

로컬 명령 기반 서버는 다음 속성을 지원합니다.

원격 HTTP 서버는 다음 속성을 지원합니다.

MCP 서버 관리:

구성된 MCP 서버 목록 보기:

atx mcp tools

특정 MCP 서버에서 제공하는 사용 가능한 도구를 나열합니다.

atx mcp tools --server <server-name>

사용량 추적:

CLI는 변환 실행 중에 MCP 도구 사용을 자동으로 추적합니다. 사용 통계는와 함께 대화 디렉터리mcp_usage.json에서 로 유지됩니다metadata.json. 파일은 다음을 포함하여 각 실행에 대한 도구별 지표를 기록합니다.

클라이언트 측 기술

클라이언트 측 기술은 변환 실행 중에 에이전트를 확장하는 추가 기능입니다. 이를 통해 에이전트가 내장 기능과 함께 사용할 수 있는 사용자 지정 도구, 스크립트 및 지침을 제공할 수 있습니다.

스킬 검색 디렉터리:

스킬은 네 개의 디렉터리에서 우선적으로 검색됩니다. 이름이 같은 스킬이 여러 디렉터리에 있는 경우 목록의 첫 번째 디렉터리가 우선합니다.

.aws/atx/skills/ 디렉터리는 AWS 변환 CLI에 고유합니다. 디렉터리는 교차 클라이언트이므로 AWS Transform CLI 이외의 호환되는 에이전트 도구에서 해당 .agents/skills/ 디렉터리에 배치된 기술을 사용할 수 있습니다.

Skill 디렉터리 구조:

각 스킬은 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으로 표시하거나, 인적 독자 전용 참조 자료를 유지할 수 있습니다.

실행 모드별 스킬 가용성:

스킬 검색 확인:

실행 후 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

검증에 실패한 스킬은 디버그 로그의 경고와 함께 건너뜁니다.

프로젝트 수준 스킬과 사용자 수준 스킬 중에서 선택

스킬을 배치하는 위치에 따라 스킬의 이점과 활성화 시기가 결정됩니다.

프로젝트 수준 기술(<project>/.aws/atx/skills/):

리포지토리에 대해 변환을 실행하는 모든 팀원이 자동으로 검색할 수 있도록 버전 관리로 커밋합니다. 다음을 위해 프로젝트 수준 기술을 사용합니다.

사용자 수준 기술(~/.aws/atx/skills/):

이는 시스템에 남아 있으며 대상 리포지토리에 관계없이 모든 변환 중에 활성화됩니다. 다음에 대해 사용자 수준 기술을 사용합니다.

효과적인 기술을 위한 팁:

클라이언트 측 스킬 예제

이 예제에서는 스크립트 기반 검증 스킬과 참조 전용 스킬이라는 두 가지 일반적인 패턴을 보여줍니다.

예: Dockerfile 규정 준수 검사기(스크립트 기반)

이 기술은 보안 및 운영 모범 사례를 기준으로 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 코드 예제가 포함되어 있습니다. 예를 들어 aws-sdk-v2-to-v3.md는 S3Client 및 s3.putObject(params).promise()를 사용하여와 같은 패턴을 모듈식 v3에 매핑합니다PutObjectCommand.

태그 및 조직

액세스 제어 및 분류를 위해 태그를 사용하여 변환을 구성할 수 있습니다.

변환에 대한 태그를 나열하려면:

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 변환 CLI는 문제 해결 및 디버깅을 위해 세 가지 유형의 로그를 유지합니다.

대화 로그:

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 자체에 대한 고급 문제 해결 정보를 제공합니다.

CLI 업데이트

CLI를 최신 상태로 유지하여 새로운 기능 및 개선 사항에 액세스합니다.

업데이트를 확인하려면:

atx update --check

최신 버전으로 업데이트하려면:

atx update

특정 버전으로 업데이트하려면:

atx update --target-version <version>

사용자 지정 변환 생성

이 섹션에서는 사용자 지정 변환 정의를 생성, 수정 및 관리하는 방법을 설명합니다.

새 변환 생성

대화형 CLI를 사용하여 새 변환 정의를 생성합니다.

변환 정의를 생성하려면

변환 생성 모범 사례:

참조 자료 제공

대화 중에 파일 경로를 지정하여 사용자 지정 AWS 변환에 참조 파일을 제공할 수 있습니다. 이러한 파일은 변환 정의의 references/ 폴더에 저장됩니다.

권장되는 참조 파일 유형:

참조 파일을 제공하려면:

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

여러 참조 파일이 포함된 디렉터리를 제공할 수도 있습니다.

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

기존 변환 수정

사용자 지정 변환을 초안으로 저장하거나 게시하기 전과 후에 모두 수정할 수 있습니다. AWS관리형 변환은 수정할 수 없습니다. 사용자 지정해야 하는 경우 구성 파일을 사용하여 추가 컨텍스트를 제공할 수 있습니다.

기존 변환을 수정하려면

변환 게시 및 관리

대화형 환경을 사용하거나 다음 명령을 사용하여 변환을 게시하고 관리할 수 있습니다.

변환을 초안으로 저장하려면:

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

버전을 지정하지 않으면 최신 버전이 사용됩니다.