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

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

ant apply는 에이전트, 환경, 스킬, 메모리 스토어, 배포를 파일로 선언하고 API의 리소스를 그 파일들과 동기화해 줘요. 리소스가 저장소에 살면서 코드와 같은 검토를 거쳐 바뀌어요. 각 리소스를 파일로 작성하고, ant apply를 실행하고, 표시되는 계획을 승인하면 돼요. 그러면 작성된 claude-lock.json을 커밋해서 다음 실행이 새 리소스를 만들지 않고 같은 리소스를 갱신하게 해요.

출처: 문서

본문

CLI 설치와 인증은 CLI 퀵스타트를 참고하세요. ant apply는 CLI 버전 1.30.0 이상이 필요해요.

첫 에이전트 적용하기

에이전트를 agents/ 아래의 Markdown 파일로 작성하고 적용하세요:

You are a helpful assistant that writes concise summaries.
```

프론트매터는 에이전트의 설정(에이전트 정의하기의 필드)을 담고, 본문은 시스템 프롬프트예요. 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를 다시 실행하세요. 그러면 계획이 create 대신 update를 보여 줘요.

claude-lock.json 커밋하기

첫 ant apply는 실행한 디렉터리에 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가 반환한 것을 지문으로 나타내요. 그래서 이후 실행이 편집된 파일이나 이 파일들 밖에서 바뀐 리소스를 알아차릴 수 있어요.

프로젝트로 키우기

다른 리소스도 선언적으로 파일로 정의할 수 있어요. 파일은 그 종류의 create 엔드포인트에 보낼 요청 본문을 담아요:

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

스킬을 제외한 어떤 리소스든 YAML, JSON, Markdown으로 쓸 수 있어요. Markdown에서는 프론트매터가 본문이고 산문이 그 종류의 텍스트 필드를 채워요: 에이전트의 system, 환경·메모리 스토어의 description, 배포의 첫 메시지.

리소스들은 경로로 서로를 참조해요. API가 다른 리소스의 ID를 기대하는 곳에는 그 리소스 파일의 상대 경로를 쓰세요. 이 프로젝트에서 리뷰어 에이전트는 skills 아래 ../skills/pr-summary를 나열하고, 리드 에이전트는 명단에 ./reviewer.md를 나열하며, 배포는 에이전트·환경·메모리 스토어를 경로로 이름 붙여요. ant apply는 의존성 순서로 만들고 실제 ID를 채워요. 프로젝트는 여섯 개의 파일이에요:

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

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

# PR summary

List what changed, why, and anything a reviewer should look at closely, in three short sections.
```

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로 만든 리소스를 채택할 수 없어요. 락파일에 있는 것만 관리되고, 기존 에이전트를 설명하는 파일을 적용하면 두 번째 것을 만들어요. Console에서 Export as code로 에이전트를 다운로드했다면, 다운로드에 자체 claude-lock.json이 포함되므로 적용하면 거기서 만든 리소스를 갱신해요.

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에 기록된 조직·워크스페이스에 도달하는 자격 증명을 쓰세요. ant apply는 다른 조직·워크스페이스로 해석되는 자격 증명을 거부해요.

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

플래그

다음 단계

더 알아보기 (Learn more)

• 세션 시작하기
• 예약 배포
• CLI 스크립팅과 자동화