ant apply 운영법: Claude 에이전트 리소스를 코드로 관리하는 방법

요약: ant apply는 Claude API의 agents, environments, skills, memory stores, deployments를 파일로 선언하고 API 리소스와 동기화하는 CLI 기능입니다. 에이전트를 콘솔에서 수동 관리하던 팀이라면 Terraform 같은 운영 방식을 Claude 리소스에도 적용할 수 있습니다.

문제: 에이전트 설정이 콘솔 안에만 있으면 재현이 어렵다

AI 에이전트 운영에서 자주 생기는 문제가 있습니다. 누군가 Claude Console에서 agent prompt를 고치고, 다른 사람이 skill을 업데이트하고, 배포 스케줄은 또 다른 곳에서 바꿉니다. 결과적으로 “지금 운영 중인 에이전트가 어떤 설정으로 돌고 있나?”를 코드 리뷰로 확인하기 어렵습니다. 장애가 나도 언제 어떤 변경이 원인인지 추적하기 어렵습니다.

ant apply는 이 문제를 코드 관리 방식으로 풀려는 기능입니다. Anthropic CLI 1.30.0 이상에서 agents, environments, skills, memory stores, deployments를 저장소 안 파일로 선언하고, 실행 시 API 리소스와 맞춥니다. 적용 후에는 claude-lock.json에 실제 리소스 ID와 hash가 기록됩니다. 다음 실행에서는 새로 만들지 않고 같은 리소스를 업데이트합니다.

개발자에게 익숙한 비유로는 Terraform, Kubernetes manifest, Pulumi의 작은 버전에 가깝습니다. 차이는 대상이 클라우드 인프라가 아니라 Claude Platform 리소스라는 점입니다.

기본 흐름: 파일 작성, plan 확인, lockfile 커밋

가장 단순한 예는 agents/summarizer.md 파일 하나를 만드는 것입니다. frontmatter에는 모델과 tool 설정을 넣고, 본문에는 system prompt를 씁니다. 그 다음 ant apply agents/summarizer.md를 실행하면 CLI가 어떤 리소스를 만들지 plan을 보여줍니다. 사용자가 승인하면 agent가 생성되고 claude-lock.json이 쓰입니다.

중요한 운영 포인트는 lockfile입니다. 처음 apply할 때 만들어지는 claude-lock.json은 파일 경로와 원격 리소스 ID를 연결합니다. 이 파일을 커밋하지 않으면 다음 실행이 같은 agent를 업데이트하지 못하고 새 리소스를 만들 수 있습니다. 따라서 agent 파일과 lockfile은 한 세트로 리뷰하고 머지해야 합니다.

팀 규칙은 단순해야 합니다. Console에서 직접 고치지 말고 repo에서 수정합니다. PR에서 prompt diff와 tool diff를 리뷰합니다. 머지 후 CI에서 ant apply --yes .를 실행합니다. 이렇게 해야 운영 중인 에이전트 설정이 Git history에 남습니다.

어떤 리소스를 코드로 관리할 수 있나

Anthropic 문서 기준으로 ant apply는 여러 리소스를 파일로 선언할 수 있습니다. agents/ 아래 Markdown 파일은 agent로 추론됩니다. environments/ 아래 YAML은 실행 환경입니다. memory_stores/는 memory store를 정의합니다. deployments/ Markdown은 예약 실행 배포를 정의하고, skill은 skills/<name>/SKILL.md 디렉터리 번들로 업로드됩니다.

리소스끼리 참조할 때는 실제 ID 대신 상대 경로를 쓸 수 있습니다. 예를 들어 deployment가 agent를 참조할 때 ../agents/reviewer.md처럼 적으면 ant apply가 생성 순서를 계산하고 실제 ID로 연결합니다. 이 부분이 운영 효율을 크게 높입니다. 새 환경에 배포할 때마다 콘솔에서 ID를 복사해 붙이는 작업을 줄일 수 있기 때문입니다.

다만 모든 것을 한 번에 코드화하려고 하면 실패합니다. 먼저 운영에 중요한 agent와 skill부터 시작하고, 그 다음 environment와 deployment로 넓히는 편이 좋습니다.

CI에서 쓸 때 조심할 점

CI에는 터미널이 없기 때문에 ant apply가 승인 질문을 할 수 없습니다. 문서에서는 기본 브랜치 머지 후 ant apply --yes .를 실행하라고 안내합니다. PR에서는 ant apply --dry-run .으로 plan만 출력해 리뷰어가 볼 수 있게 만들 수 있습니다.

여기서 자주 놓치는 부분이 있습니다. ant apply --yes만 실행하면 lockfile이 이미 추적하는 파일만 맞출 수 있고, 새로 추가된 파일을 놓칠 수 있습니다. 새 리소스까지 포함하려면 프로젝트 경로를 명시하는 방식이 안전합니다. 예를 들어 ant apply --yes .처럼 실행합니다.

또 하나는 동시 실행입니다. 문서에서도 apply를 한 번에 하나씩 실행하라고 합니다. lockfile에 대한 분산 락이 없기 때문에 여러 CI job이 동시에 돌면 상태가 꼬일 수 있습니다. GitHub Actions라면 concurrency group을 잡아 같은 브랜치나 같은 environment에 대해 한 job만 실행되게 해야 합니다.

외부 변경과 drift 대응

리소스가 Console이나 다른 스크립트에서 수정되면 ant apply는 plan을 적용할 수 없다고 멈출 수 있습니다. 이때 --force로 덮어쓸 수 있지만, 기본값이 멈춤인 것은 좋은 설계입니다. 운영 리소스가 코드 밖에서 바뀌었다는 신호이기 때문입니다.

drift 대응 규칙을 미리 정해야 합니다. 긴급 장애 대응으로 콘솔에서 바꿨다면, 나중에 반드시 repo에 같은 변경을 반영합니다. 의도치 않은 변경이라면 apply를 멈추고 누가 왜 바꿨는지 확인합니다. 무조건 --force를 자동화하면 코드 관리의 장점이 사라집니다.

파일 삭제도 주의해야 합니다. 파일을 지웠다고 원격 리소스가 바로 삭제되는 것은 아니며, --prune을 써야 제거됩니다. rename은 새 리소스를 만들고 기존 리소스를 남길 수 있으므로, 리소스 이름과 파일 경로를 안정적으로 유지하는 편이 좋습니다.

운영 체크리스트

Anthropic CLI 버전이 1.30.0 이상인지 확인합니다.
agent, skill, environment, deployment 파일을 저장소에 선언합니다.
첫 apply 후 생성된 claude-lock.json을 반드시 커밋합니다.
PR에서는 ant apply --dry-run . 결과를 리뷰에 노출합니다.
머지 후 기본 브랜치에서 ant apply --yes .를 한 번만 실행합니다.
CI concurrency를 설정해 apply 동시 실행을 막습니다.
Console 직접 수정은 예외로 두고, 발생 시 repo에 되돌려 반영합니다.
--force와 --prune은 자동 기본값으로 쓰지 말고 의도적으로만 사용합니다.
리소스 파일 rename은 새 리소스 생성으로 이어질 수 있으니 신중히 처리합니다.

ant apply의 가치는 편의 기능이 아니라 운영 습관을 바꾸는 데 있습니다. 에이전트가 제품 기능의 일부가 되면 prompt와 tool 설정도 코드처럼 리뷰, 테스트, 배포되어야 합니다. 콘솔에서 잘 돌아가는 데모를 Git으로 관리되는 운영 리소스로 옮기는 것이 다음 단계입니다.