ant apply로 리소스를 코드로 관리하기

ant apply는 파일로부터 Claude API 리소스(에이전트, 환경, 스킬, 메모리 스토어, 배포)를 생성하고 업데이트합니다. 이러한 리소스는 저장소에 존재하며 코드와 동일한 리뷰 과정을 거쳐 변경됩니다. 각 리소스를 파일로 기술하고, ant apply를 실행한 다음, 표시되는 계획을 승인하면 됩니다. 그런 다음 ant apply가 작성한 claude-lock.json을 커밋하면, 다음 실행 시 새 리소스를 생성하는 대신 동일한 리소스를 업데이트합니다.

CLI를 설치하고 인증하려면 CLI 빠른 시작을 참조하세요. ant apply를 사용하려면 CLI 버전 1.30.0 이상이 필요합니다.

첫 번째 에이전트 적용하기

agents/ 아래에 에이전트를 Markdown 파일로 작성하고 적용합니다:

ant apply agents/summarizer.md

---
name: Summarizer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant that writes concise summaries.

"Frontmatter"(프런트매터)에는 에이전트의 구성(에이전트 정의하기의 필드)이 담기고, 본문은 에이전트의 시스템 프롬프트가 됩니다. ant apply는 파일 경로(여기서는 agents/ 디렉터리)를 통해 해당 파일이 에이전트임을 추론합니다.

대화형 터미널에서 ant apply는 계획을 출력하고 승인을 기다립니다:

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와 리소스가 속한 조직 및 워크스페이스가 기록됩니다:

{
  "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든 다음 실행 시 이 파일을 통해 리소스를 다시 생성하는 대신 기존 리소스를 찾으며, 세션을 시작할 때 에이전트의 ID를 읽어오는 곳이기도 합니다. 두 해시는 마지막으로 전송된 내용과 API가 반환한 내용의 지문입니다. 이를 통해 이후 실행에서 편집된 파일이나 이 파일들 외부에서 변경된 리소스를 감지합니다.

프로젝트로 확장하기

다른 리소스도 파일로 선언적으로 정의할 수 있습니다. 파일에는 해당 종류의 생성 엔드포인트로 보낼 요청 본문이 담깁니다:

• 환경은 environments/에 있는 YAML 파일입니다.
• 메모리 스토어는 memory_stores/에 있는 YAML 파일입니다.
• 배포는 deployments/에 있는 Markdown 파일입니다. 프런트매터는 요청 본문이고, 본문 텍스트는 각 세션을 시작하는 메시지가 됩니다.
• 스킬은 루트에 SKILL.md가 있는 디렉터리로, 관례적으로 skills/ 아래에 두며 하나의 번들로 업로드됩니다.

스킬을 제외한 모든 리소스는 YAML, JSON 또는 Markdown으로 작성할 수 있습니다. Markdown에서는 프런트매터가 요청 본문이 되고, 본문 텍스트는 해당 종류의 텍스트 필드를 채웁니다. 즉, 에이전트의 system, 환경 또는 메모리 스토어의 description, 배포의 첫 번째 메시지입니다.

리소스는 경로로 서로를 참조합니다. API가 다른 리소스의 ID를 요구하는 곳에는 대신 해당 리소스 파일의 상대 경로를 작성하세요. 이 프로젝트에서 reviewer 에이전트는 skills 아래에 ../skills/pr-summary를 나열하고, lead 에이전트는 로스터에 ./reviewer.md를 나열하며, 배포는 에이전트, 환경, 메모리 스토어를 경로로 지정합니다. ant apply는 의존성 순서대로 리소스를 생성하고 실제 ID를 채워 넣습니다. 이 프로젝트에는 6개의 파일이 있습니다:

---
name: Code reviewer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
skills:
  - ../skills/pr-summary
---

You review pull requests for correctness, security, and readability.

---
name: Engineering lead
model: claude-opus-5
multiagent:
  type: coordinator
  agents:
    - ./reviewer.md
---

You coordinate engineering work. Delegate code review to the reviewer.

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

name: review-env
description: Cloud container with unrestricted networking for review sessions.
config:
  type: cloud
  networking:
    type: unrestricted

name: Review notes
description: Recurring issues and house-style decisions the reviewer has recorded between runs.

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

디렉터리 전체를 적용합니다:

ant apply .

그러면 claude-lock.json에 프로젝트의 모든 파일에 대한 항목이 생깁니다.

상대 경로는 이 파일들이 서로를 가리키는 방식입니다. ant apply는 에이전트 및 스킬 참조를 방금 적용한 버전으로 고정하므로, reviewer.md나 스킬을 편집하면 같은 실행에서 이를 참조하는 모든 항목이 업데이트됩니다. 경로는 배포의 resources 항목처럼 객체 내부에서도 작동하며, 이때 access와 같은 다른 키는 그대로 유지됩니다.

이 파일들이 관리하지 않는 리소스를 가리키려면 대신 해당 ID(agent_..., skill_...)를 작성하세요. {type: anthropic, skill_id: xlsx}와 같은 그 밖의 값은 작성된 그대로 API에 전송됩니다. 스킬 참조는 https://github.com/<owner>/<repo>/tree/<branch>/<dir> 형식의 GitHub URL일 수도 있습니다. 예를 들어 Anthropic의 오픈 소스 스킬 저장소의 디렉터리를 지정할 수 있습니다. ant apply는 해당 디렉터리를 다운로드하여 업로드하며, --upgrade로 실행할 때까지 확인된 커밋에 고정됩니다(비공개 저장소의 경우 GITHUB_TOKEN을 설정하세요).

ant apply가 파일의 종류를 추론하는 방법

ant apply가 디렉터리를 탐색할 때, 다음 중 처음으로 일치하는 항목을 기준으로 각 파일의 종류를 결정합니다:

1. 파일의 최상위 type 필드.
2. 파일이 직접 위치한 디렉터리: agents/, environments/, memory_stores/ 또는 deployments/.
3. environment_staging.md처럼 종류 이름으로 시작하는 파일 이름.

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으로 인증하되, claude-lock.json에 기록된 조직 및 워크스페이스에 접근할 수 있는 ID로 인증하세요. ant apply는 다른 조직이나 워크스페이스로 확인되는 자격 증명을 거부합니다.

전체 GitHub Actions 워크플로는 CLI README의 CI 예제를 참조하세요.

플래그

다음 단계