--- title: ant apply로 리소스를 코드로 관리하기 url: https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply description: 에이전트, 환경, 스킬, 메모리 스토어, 배포, 볼트를 저장소의 파일로 선언하고 ant apply를 사용하여 API의 리소스를 해당 파일과 동기화된 상태로 유지합니다. --- `ant apply`는 파일로부터 Claude API 리소스를 생성하고 업데이트합니다. 대상 리소스는 에이전트, 환경, 스킬, 메모리 스토어, 배포, 볼트입니다. 이 리소스들은 저장소에 존재하며 코드와 동일한 리뷰 과정을 거쳐 변경됩니다. 각 리소스를 파일에 기술하고, `ant apply`를 실행한 다음, 표시되는 계획을 승인하면 됩니다. 그런 다음 `ant apply`가 작성한 `claude-lock.json`을 커밋하면, 다음 실행 시 새 리소스를 생성하는 대신 동일한 리소스를 업데이트합니다. CLI를 설치하고 인증하려면 [CLI 빠른 시작](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/quickstart)을 참조하세요. `ant apply`를 사용하려면 CLI 버전 1.30.0 이상이 필요합니다. ## 첫 번째 에이전트 적용하기 `agents/` 아래에 에이전트를 Markdown 파일로 작성하고 적용합니다: ```bash CLI ant apply agents/summarizer.md ``` ```markdown --- name: Summarizer model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful assistant that writes concise summaries. ``` "Frontmatter"(프런트매터)에는 에이전트의 구성([에이전트 정의하기](https://platform.claude.com/docs/ko/managed-agents/agent-setup)의 필드)이 담기고, 본문은 에이전트의 시스템 프롬프트가 됩니다. `ant apply`는 파일 경로(여기서는 `agents/` 디렉터리)를 통해 해당 파일이 에이전트임을 [추론](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply#kind-inference)합니다. 대화형 터미널에서 `ant apply`는 계획을 출력하고 승인을 기다립니다: ```text Output wrap First apply ./claude-lock.json does not exist yet and will be created Resources will be created with credentials API key (--api-key / ANTHROPIC_API_KEY) host api.anthropic.com organization 1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f workspace wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ Preview ./claude-lock.json (new) ± Name Plan + ./agents/summarizer.md create Resources + 1 to create Apply these changes? (y)es / (n)o / (d)etails y Apply ./claude-lock.json ± Name Status + ./agents/summarizer.md created agent_011CYm1BLqPXpQRk5khsSXrs Resources + 1 created State written to ./claude-lock.json ``` 먼저 세부 정보를 보려면 `d`를 입력하세요. 각 새 리소스의 필드 또는 각 업데이트의 필드별 diff를 확인할 수 있습니다. `--dry-run`은 이 상세 계획을 출력하고 아무것도 변경하지 않은 채 종료합니다. 에이전트를 변경하려면 파일을 편집하고 `ant apply`를 다시 실행하세요. 그러면 계획에 생성 대신 업데이트가 표시됩니다. ## claude-lock.json 커밋하기 첫 번째 `ant apply`는 실행한 디렉터리에 "lockfile"(잠금 파일)인 `claude-lock.json`을 작성하므로, 저장소 루트에서 실행하세요. 이 파일에는 각 파일이 생성한 리소스의 ID와 리소스가 속한 조직 및 워크스페이스가 기록됩니다: ```json claude-lock.json { "version": 1, "origin": { "base_url": "https://api.anthropic.com", "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f", "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }, "resources": { "./agents/summarizer.md": { "kind": "agent", "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": "1", "hash": "d23251c8d99b3613a64f3f8d87f5fad4", "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94" } } } ``` 이 파일을 다른 파일과 함께 커밋하세요. 로컬 머신이든 CI든 다음 실행 시 이 파일을 통해 리소스를 다시 생성하는 대신 기존 리소스를 찾으며, [세션을 시작](https://platform.claude.com/docs/ko/managed-agents/sessions)할 때 에이전트의 ID를 읽어오는 곳이기도 합니다. 두 해시는 마지막으로 전송된 내용과 API가 반환한 내용의 지문입니다. 이를 통해 이후 실행에서 편집된 파일이나 이 파일들 외부에서 변경된 리소스를 감지합니다. ## 프로젝트로 확장하기 다른 리소스도 파일로 선언적으로 정의할 수 있습니다. 파일에는 해당 종류의 생성 엔드포인트로 보낼 요청 본문이 담깁니다: * [환경](https://platform.claude.com/docs/ko/managed-agents/environments)은 `environments/`에 있는 YAML 파일입니다. * [메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/memory)는 `memory_stores/`에 있는 YAML 파일입니다. * [배포](https://platform.claude.com/docs/ko/managed-agents/scheduled-deployments)는 `deployments/`에 있는 Markdown 파일입니다. 프런트매터는 요청 본문이고, 본문 텍스트는 각 세션을 시작하는 메시지가 됩니다. * [스킬](https://platform.claude.com/docs/ko/managed-agents/skills)은 루트에 `SKILL.md`가 있는 디렉터리로, 관례적으로 `skills/` 아래에 두며 하나의 번들로 업로드됩니다. * [볼트](https://platform.claude.com/docs/ko/managed-agents/vaults)는 `vaults/`에 있는 YAML 파일로, 필드는 `display_name`과 선택적인 `metadata`뿐입니다. 볼트 파일에는 CLI 버전 1.34.0 이상이 필요합니다. 스킬을 제외한 모든 리소스는 YAML, JSON 또는 Markdown으로 작성할 수 있습니다. Markdown에서는 프런트매터가 요청 본문이 되고, 본문 텍스트는 해당 종류의 텍스트 필드를 채웁니다. 즉 에이전트의 `system`, 환경 또는 메모리 스토어의 `description`, 배포의 첫 번째 메시지입니다. 볼트에는 텍스트 필드가 없으므로, `ant apply`는 본문 텍스트가 있는 볼트 Markdown 파일을 거부합니다. 리소스는 경로로 서로를 참조합니다. API가 다른 리소스의 ID를 요구하는 곳에는 대신 해당 리소스 파일의 상대 경로를 작성하세요. 이 프로젝트에서 reviewer 에이전트는 `skills` 아래에 `../skills/pr-summary`를 나열하고, lead 에이전트는 로스터에 `./reviewer.md`를 나열하며, 배포는 에이전트, 환경, 메모리 스토어를 경로로 지정합니다. `ant apply`는 의존성 순서대로 리소스를 생성하고 실제 ID를 채워 넣습니다. 이 프로젝트에는 6개의 파일이 있습니다: ```markdown --- name: Code reviewer model: claude-opus-5-5 tools: - type: agent_toolset_20260401 skills: - ../skills/pr-summary --- You review pull requests for correctness, security, and readability. ``` ```markdown --- name: Engineering lead model: claude-opus-5-5 multiagent: type: coordinator agents: - ./reviewer.md --- You coordinate engineering work. Delegate code review to the reviewer. ``` ```markdown --- name: pr-summary description: Summarize a pull request's changes and risks in the team's review format. --- # PR summary List what changed, why, and anything a reviewer should look at closely, in three short sections. ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: review-env description: Cloud container with limited networking for review sessions. config: type: cloud networking: type: limited allow_package_managers: true ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json name: Review notes description: Recurring issues and house-style decisions the reviewer has recorded between runs. ``` ```markdown --- name: Nightly review agent: ../agents/reviewer.md # the API's agent field: sent as {type: agent, id, version} environment_id: ../environments/cloud.yaml # sent as the environment's ID resources: - path: ../memory_stores/review-notes.yaml access: read_write schedule: type: cron expression: "0 3 * * *" timezone: America/Los_Angeles --- Review any open pull requests. Start with the oldest. ``` 디렉터리 전체를 적용합니다: ```bash CLI ant apply . ``` 그러면 `claude-lock.json`에 프로젝트의 모든 파일에 대한 항목이 생깁니다. 상대 경로는 이 파일들이 서로를 가리키는 방식입니다. `ant apply`는 에이전트 및 스킬 참조를 방금 적용한 버전으로 고정하므로, `reviewer.md`나 스킬을 편집하면 같은 실행에서 이를 참조하는 모든 항목이 업데이트됩니다. 경로는 배포의 `resources` 항목처럼 객체 내부에서도 작동하며, 이때 `access`와 같은 다른 키는 그대로 유지됩니다. 이 파일들이 관리하지 않는 리소스를 가리키려면 대신 해당 ID(`agent_...`, `skill_...`)를 작성하세요. `{type: anthropic, skill_id: xlsx}`와 같은 그 밖의 값은 작성된 그대로 API에 전송됩니다. 스킬 참조는 `https://github.com///tree//` 형식의 GitHub URL일 수도 있습니다. 예를 들어 Anthropic의 오픈 소스 [스킬 저장소](https://github.com/anthropics/skills)의 디렉터리를 지정할 수 있습니다. `ant apply`는 해당 디렉터리를 다운로드하여 업로드하며, `--upgrade`로 실행할 때까지 확인된 커밋에 고정됩니다(비공개 저장소의 경우 `GITHUB_TOKEN`을 설정하세요). ### ant apply가 파일의 종류를 추론하는 방법 `ant apply`가 디렉터리를 탐색할 때, 다음 중 처음으로 일치하는 항목을 기준으로 각 파일의 종류를 결정합니다: 1. 파일의 최상위 `type` 필드. 2. 파일이 직접 속한 디렉터리: `agents/`, `environments/`, `memory_stores/`, `deployments/` 또는 `vaults/`. 3. `environment_staging.md`처럼 종류로 시작하는 파일 이름. * 볼트는 예외입니다. 다른 도구들이 시크릿 파일 이름을 `vault.yml`로 짓기 때문에, `ant apply`는 `vault_staging.yaml` 같은 이름에서 종류를 가져오지 않습니다. 볼트 파일은 `vaults/`에 두거나 `type: vault`를 지정하세요. README나 CI 구성처럼 이 중 어느 것에도 일치하지 않는 파일은 명령줄에서 직접 지정하지 않는 한 건너뜁니다. 직접 지정한 Markdown 파일이 어느 것에도 일치하지 않으면 에이전트로 처리되며, 직접 지정한 YAML 또는 JSON 파일이 어느 것에도 일치하지 않으면 오류가 발생합니다. ## 편집 후 다시 적용하기 인수 없이 `ant apply`를 실행하면 잠금 파일이 추적하는 모든 파일을 조정합니다. 터미널에서는 잠금 파일 디렉터리 아래에 있는 추적되지 않은 리소스 파일도 나열하고 추가할지 묻습니다. 파일에서 필드를 삭제하면, API가 해당 필드의 초기화를 허용하는 경우 리소스에서도 해당 필드가 초기화됩니다. 설정한 적이 없는 필드나 API가 초기화할 수 없는 필드는 현재 값을 유지합니다. 리소스가 이 파일들 외부(예: Claude Console)에서 편집, 보관 또는 삭제된 경우, 계획은 `This plan cannot be applied:`와 그 이유로 끝납니다. 그런 다음 명령은 `refusing to apply`와 함께 종료됩니다. 해당 편집을 덮어쓰거나 대체 리소스를 생성하려면 `--force`를 전달하세요. 파일을 삭제하면 경고와 함께 해당 리소스는 그대로 남으며, `--prune`을 사용하면 리소스가 제거됩니다(보관되며, 스킬의 경우 삭제됩니다). 따라서 파일 이름을 변경하면 새 리소스를 선언하는 것이 되며, prune할 때까지 이전 리소스는 그대로 남습니다. `ant apply`는 Console에서 생성했거나 `ant beta:agents create`로 생성한 리소스를 가져올 수 없습니다. 잠금 파일에 있는 것만 관리되며, 기존 에이전트를 기술하는 파일을 적용하면 두 번째 에이전트가 생성됩니다. **Export as code**로 Console에서 에이전트를 다운로드한 경우, 다운로드에 자체 `claude-lock.json`이 포함되어 있으므로 이를 적용하면 Console에서 만든 리소스가 업데이트됩니다. ## CI에서 ant apply 실행하기 터미널이 없으면 `ant apply`는 계획을 출력하고 `cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only`와 함께 중지됩니다. CI는 다음과 같이 설정하세요: * 병합 후 기본 브랜치에서 프로젝트 디렉터리를 지정하여 `ant apply --yes .`를 실행하세요. 인수 없는 `ant apply --yes`는 잠금 파일이 이미 추적하는 파일만 조정하며 새로 추가된 파일은 건너뜁니다. * 풀 리퀘스트에서는 `ant apply --dry-run .`을 실행하여 리뷰어를 위한 계획을 출력하세요. 이는 정보 제공용일 뿐이며 계획이 차단된 경우에도 0으로 종료됩니다. * 적용 단계가 도중에 실패하더라도 작업이 끝날 때 업데이트된 `claude-lock.json`을 커밋하세요. 부분적으로 적용된 경우에도 생성된 항목이 기록되기 때문입니다. * 잠금 파일을 잠그는 장치가 없으므로 한 번에 하나의 적용만 실행하세요. * 저장된 API 키 대신 [Workload Identity Federation](https://platform.claude.com/docs/ko/manage-claude/workload-identity-federation)으로 인증하되, `claude-lock.json`에 기록된 조직 및 워크스페이스에 접근할 수 있는 ID로 인증하세요. `ant apply`는 다른 조직이나 워크스페이스로 확인되는 자격 증명을 거부합니다. 전체 GitHub Actions 워크플로는 [CLI README의 CI 예제](https://github.com/anthropics/anthropic-cli#in-ci)를 참조하세요. ## 플래그 | 플래그 | 효과 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--dry-run` | 계획을 출력하고 적용하거나 잠금 파일을 작성하지 않고 종료합니다. 계획이 차단된 경우에도 0으로 종료됩니다. | | `--yes` | 확인을 요청하지 않고 적용합니다. 터미널이 없을 때 필요합니다. | | `--force` | 리소스가 이 파일들 외부에서 변경, 보관 또는 삭제된 경우에도 적용합니다. | | `--prune` | 잠금 파일에는 있지만 더 이상 파일에 선언되지 않은 리소스를 제거합니다. | | `--upgrade` | GitHub URL로 참조된 스킬을 다시 확인합니다. 그렇지 않으면 잠금 파일에 기록된 커밋에 고정된 상태로 유지됩니다. | | `--lock-file ` | 현재 디렉터리에서 위쪽으로 검색하는 대신 이 잠금 파일을 사용합니다. 조직 또는 워크스페이스마다 하나씩 유지하세요. `ant apply`는 조직 또는 워크스페이스가 자격 증명과 일치하지 않는 잠금 파일을 거부합니다. | | `--verbose`, `-v` | 계획에 변경되지 않은 리소스와 전체 필드 값을 표시합니다. | ## 다음 단계 CLI 또는 SDK에서 적용한 에이전트를 실행합니다 배포 필드, 실행 기록 및 일시 중지 스크립팅 패턴 및 Claude Code에서의 사용