Claude 에이전트 배포를 코드 리뷰로 관리하는 법

2026년 9월 3일, Claude Managed Agents의 운영 방식에 실무적인 변화가 생겼습니다. 이제 ant apply를 사용하면 저장소의 파일을 실제 Claude 에이전트, 환경, 스킬, 메모리 저장소, 배포 리소스로 반영할 수 있습니다. 핵심은 에이전트 설정도 프로덕션에 도달하기 전에 코드와 같은 검토 절차를 거칠 수 있게 됐다는 점입니다.

Claude 에이전트 설정을 검토 가능한 상태로 만드는 변화

Claude Managed Agents는 Anthropic이 장시간 실행 작업과 비동기 작업을 위해 제공하는 호스팅 에이전트 시스템입니다. 에이전트에는 모델, 프롬프트, 툴, 스킬이 정의됩니다. 환경은 에이전트가 실행될 위치를 정하고, 배포 리소스는 해당 에이전트를 일정에 따라 실행할 수 있게 합니다.

이는 .claude/agents/에 두는 Claude Code 서브에이전트와는 별개입니다. 이번 변화의 대상은 Claude API의 Managed Agents 서비스를 구성하는 리소스입니다.

팀이 Console이나 일회성 API 호출로 이런 리소스를 만들면 관리해야 할 상태가 두 곳으로 나뉩니다. 실제 리소스는 원격 서비스에 있지만, 그것이 만들어진 과정은 스크립트나 문서, 혹은 팀원의 기억에 남습니다. 인수인계 때마다 이 둘을 다시 연결해야 합니다.

ant apply는 그 역할을 저장소에 맡깁니다. Markdown, YAML 또는 JSON으로 리소스를 기술하면 CLI가 파일과 원격 리소스를 비교해 변경 계획을 보여주고 승인을 받은 뒤 적용합니다.

이제 시스템 프롬프트, 툴 접근 권한, 환경, 스킬 번들, 메모리 저장소, 실행 일정을 하나의 풀 리퀘스트에 담을 수 있습니다. 배포 자격 증명을 가진 담당자나 CI 작업이 실제 변경을 수행하기 전에 검토자가 무엇이 달라지는지 확인할 수 있습니다.

이 글은 이미 Managed Agents 도입을 검토 중인 팀을 위한 워크플로 가이드입니다. Claude 앱이나 Claude Code만 사용하거나 Messages API로 자체 루프를 운영한다면 ant apply가 기존 구성을 바꾸지는 않습니다.

인수인계의 핵심은 락파일입니다

중요한 것은 에이전트 정의 파일만이 아닙니다. claude-lock.json이 핵심입니다.

첫 적용에 성공하면 명령을 실행한 디렉터리에 이 락파일이 생성됩니다. 저장소 루트에서 실행한 다음 리소스 파일과 함께 락파일도 커밋해야 합니다.

락파일에는 API 오리진, 조직, 워크스페이스와 각 로컬 파일에서 생성된 원격 ID가 기록됩니다. 로컬 해시와 원격 해시도 함께 저장됩니다. 로컬 해시는 파일 변경을 감지하고, 원격 해시는 누군가 Console이나 다른 API 경로에서 리소스를 변경했는지 알아냅니다.

주소록과 영수증을 합친 파일이라고 생각하면 쉽습니다. 리소스 파일은 원하는 상태를 말하고, 락파일은 그 파일이 어느 실제 객체를 관리하는지와 마지막 적용 직후 양쪽의 상태를 알려줍니다.

덕분에 인수인계가 단순해집니다. 다음 담당자나 CI 러너는 agents/reviewer.md에 해당하는 에이전트 ID를 추측할 필요가 없습니다. 매핑을 읽고 같은 리소스를 업데이트하므로 중복 리소스를 만들지 않습니다.

API에서 ID를 요구하는 곳이라도 리소스끼리는 상대 경로로 서로를 참조할 수 있습니다. CLI가 의존성 순서를 계산하고 각 리소스를 생성하거나 업데이트한 뒤 실제 ID를 채웁니다. 에이전트는 스킬 디렉터리를 가리킬 수 있고, 배포 리소스는 에이전트·환경·메모리 저장소를 참조할 수 있습니다.

에이전트와 스킬 참조는 해당 실행에서 적용된 버전에 고정됩니다. GitHub URL에서 가져온 스킬도 --upgrade를 사용하기 전까지 확인된 커밋에 고정됩니다. 따라서 검토 대상은 수시로 바뀌는 브랜치의 최신 상태가 아니라 특정 버전으로 명확해집니다.

비용 판단의 기준은 인수인계 시간입니다

ant apply가 에이전트 운영 비용을 없애 주는 것은 아닙니다. 비용 항목이 달라질 뿐입니다.

기존에는 설정 반복, 검증, 인수인계에 시간이 들었습니다. 새 방식에서는 저장소 구성, 풀 리퀘스트 검토, CI 소유권, 락파일 유지보수에 시간이 듭니다. 어느 쪽이 저렴한지는 설정이 얼마나 자주 바뀌고 같은 변경을 몇 곳에 적용해야 하는지에 달려 있습니다.

아래는 벤치마크도, Anthropic이 주장하는 절감 수치도 아닙니다. 가정을 명시한 예시입니다.

한 팀이 매달 네 차례 설정을 변경하고 이를 세 개 대상 환경에 반영한다고 가정해 보겠습니다. 각 변경을 환경 하나에 수동으로 인계하는 데 15분이 걸립니다.

수동 방식의 월간 작업량은 다음과 같습니다.

4 changes × 3 environments × 15 minutes = 180 minutes

이번에는 저장소 방식에서 변경 한 건을 검토하는 데 30분, 각 환경에 적용하고 확인하는 데 10분이 든다고 가정하겠습니다.

저장소 방식의 월간 작업량은 다음과 같습니다.

4 changes × (30 review minutes + 3 × 10 apply minutes) = 240 minutes

이 조건에서는 저장소 워크플로가 매달 60분 더 느립니다. 기존의 수동 인수인계가 이미 저렴하다면 이것이 제대로 된 결론입니다.

설정과 유지보수 비용을 제외하면 손익분기점은 수동 인수인계 한 번당 20분입니다. 실제 측정한 수동 인수인계 시간이 30분이라면 같은 수동 방식은 360분이 되고, 저장소 방식은 여전히 240분입니다. 차이는 120분이지만, 팀이 직접 작업 시간을 측정하기 전까지는 어디까지나 스프레드시트 계산일 뿐입니다.

이 시간에 간접비를 포함한 인건비 단가를 곱해야 합니다. 여기에 일회성 설정 비용과 실패한 계획 검토, 드리프트 해소, CI 유지보수에 반복해서 드는 비용도 더하십시오. 데모가 깔끔해 보여서가 아니라, 이 전체 비용이 현재 프로세스보다 낮을 때 비로소 도입할 가치가 있습니다.

이 워크플로가 실제 가치를 주는 팀

플랫폼 팀은 하나의 검토 화면을 확보합니다

소프트웨어 회사의 플랫폼 책임자는 에이전트와 그 스킬, 환경, 메모리 저장소, 예약된 배포를 하나의 풀 리퀘스트에 담을 수 있습니다. 검토자는 프롬프트 파일과 원격 Console의 스크린샷을 따로 대조하는 대신 운영 변경 전체를 한 번에 확인할 수 있습니다.

가치는 추적 가능성에 있습니다. 팀은 병합된 변경에서 리소스 적용 계획과 그 뒤에 남은 락파일 상태까지 연결해 볼 수 있습니다.

에이전시는 고객 인수인계를 더 명확하게 만들 수 있습니다

에이전시의 기술 책임자는 각 고객의 파일을 해당 고객 조직 및 워크스페이스용 락파일과 함께 보관할 수 있습니다. 다른 담당자가 업무를 넘겨받아도 매핑이 저장소와 함께 전달됩니다.

인수인계 과정에서 어떤 리소스인지 추측할 일이 줄어드는 것이 장점입니다. 그렇다고 하나의 락파일을 여러 고객에게 돌려 쓸 수 있는 것은 아닙니다. 자격 증명이 다른 조직이나 워크스페이스를 가리키면 CLI가 실행을 거부합니다. 에이전시라면 반드시 지켜야 할 경계입니다.

운영 팀은 명시적인 배포 단계를 갖게 됩니다

운영 책임자는 풀 리퀘스트에서 변경을 미리 확인하고, 병합된 디렉터리를 기본 브랜치에서 ant apply --yes .로 적용할 수 있습니다. 마지막 점은 중요합니다. 대상을 지정하지 않고 실행하면 락파일이 이미 추적하는 리소스만 조정하므로 새로 추가한 파일을 놓칠 수 있습니다.

장점은 반복 가능한 배포 단계입니다. 다만 CLI는 락파일 자체를 잠그지 않으므로 실행 시점의 소유자는 한 명이어야 합니다. 두 작업이 동시에 실행되면 같은 상태를 두고 경합할 수 있습니다.

보안 책임자는 드리프트가 생기면 배포를 멈출 수 있습니다

보안 책임자는 원격 해시를 이용해 저장소 상태가 덮어쓰기 전에 Console에서 발생한 변경을 드러낼 수 있습니다. 파일 밖에서 관리 리소스가 수정되거나 보관 처리되거나 삭제되면 CLI가 중단됩니다.

장점은 명시적으로 판단할 기회를 얻는다는 것입니다. 원격 변경을 조사해 조정하거나, --force로 덮어쓰기를 의도적으로 선택할 수 있습니다. Zero Data Retention이나 HIPAA Business Associate Agreement 적용이 필요한 팀은 Managed Agents 자체를 기다려야 합니다. 현재 이 서비스는 두 요건 모두 지원 대상이 아닙니다.

바로 적용할 수 있는 최소 저장소 구성

ant apply를 사용하려면 CLI 1.30.0 이상이 필요합니다. 공식 빠른 시작 문서에는 Homebrew 설치와 브라우저 기반 로그인 절차가 안내돼 있습니다.

1. 1

   설치하고 인증하기

   CLI를 설치하고 버전을 확인한 뒤 로그인합니다.

   brew install anthropics/tap/ant
   ant --version
   ant auth login

2. 2

   에이전트 파일 하나 만들기

   문서에 나온 최소 정의로 agents/summarizer.md를 만듭니다.

   ---
   name: Summarizer
   model: claude-opus-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant that writes concise summaries.

3. 3

   저장소 루트에서 한 번 적용하기

   문서에 안내된 단일 파일 명령을 실행합니다.

   ant apply agents/summarizer.md

   적용 계획을 검토하고, 필드별 차이가 필요하면 상세 내용을 요청한 뒤 승인합니다. 성공하면 원격 에이전트가 생성되고 프로젝트에 claude-lock.json이 기록됩니다.

4. 4

   미리보기와 적용을 서로 다른 작업으로 나누기

   풀 리퀘스트에서는 문서에 안내된 미리보기 명령을 사용합니다.

   ant apply --dry-run .

   병합 후에는 배포 작업이 동시에 실행되지 않게 하고 지정한 디렉터리를 적용합니다.

   ant apply --yes .

   부분적인 적용 실패 뒤에도 마지막에는 업데이트된 락파일을 커밋해야 합니다. 일부만 실행됐더라도 이미 리소스가 생성되고 락파일에 기록됐을 수 있기 때문입니다.

CI 상태 코드에서 놓치기 쉬운 함정

원격 드리프트는 정상적인 운영 과정에서도 생길 수 있으므로 이 차이가 중요합니다. 검토와 병합 사이에 누군가 Console에서 에이전트를 수정할 수 있습니다. 이때 미리보기는 배포 작업이 나중에 문제를 발견하게 두는 초록색 성공 표시가 아니라, 판단이 필요한 변경으로 보여줘야 합니다.

적용 작업에는 저장된 API 키 대신 Workload Identity Federation을 사용하십시오. 작업은 락파일에 기록된 조직과 워크스페이스에 연결하고, 한 번에 하나의 적용만 허용해야 합니다.

파일 기반 관리에도 분명한 한계가 있습니다

파일로 관리한다고 해서 모든 원격 리소스를 가져와 관리할 수 있는 것은 아닙니다.

ant apply는 Console이나 ant beta:agents create로 별도 생성된 에이전트를 기존 관리 대상으로 편입할 수 없습니다. Console의 Export as code 기능으로 파일과 락파일을 만들었다면 CLI가 그렇게 내보낸 리소스를 업데이트할 수 있습니다. 그렇지 않다면 내용이 같은 파일을 적용해도 새 리소스가 만들어집니다.

삭제도 보수적으로 처리됩니다. 파일을 지워도 원격 리소스는 남고 경고가 출력됩니다. --prune을 사용해야 원격 리소스가 삭제되며, 파일 이름을 바꾸면 새 리소스로 선언되기 때문에 기존 리소스는 따로 삭제하기 전까지 남습니다.

따라서 --force와 --prune은 단순한 정리 옵션이 아니라 프로덕션 제어 장치입니다. 둘 다 검토 절차 뒤에 두어야 합니다. 잘못된 이름 변경 뒤 자동 삭제가 실행되면 배포가 여전히 기대하는 리소스를 지울 수 있습니다.

락파일 역시 팀이 공유하는 운영 상태가 됩니다. 적용할 때마다 커밋하고, 해당 브랜치를 보호하며, 쓰기 작업은 직렬화해야 합니다. 실행이 중간에 실패했더라도 작업이 실패 상태라는 이유로 락파일 변경을 버리면 안 됩니다.

마지막으로 이 서비스는 아직 베타입니다. Claude Managed Agents는 Claude API 계정에서 기본으로 활성화됩니다. 그러나 Zero Data Retention이나 HIPAA BAA가 필요한 팀에는 저장소 검토만으로 해결할 수 없는 제품 차원의 제약이 있습니다.

월요일에 바로 할 일

같은 Managed Agents 리소스를 두 명 이상이 변경하거나, 동일한 설정이 여러 환경을 거치거나, 예약 배포에 담당자와 검토 이력이 필요하다면 이번 주에 시작할 만합니다.

한 명의 담당자가 안정적인 실험을 맡고 있거나, 측정한 인수인계 비용이 새 검토 비용보다 낮거나, 데이터 정책상 Zero Data Retention 또는 HIPAA BAA가 필요하다면 기다리는 편이 맞습니다.

Claude Code, Claude 앱 또는 Claude Managed Agents 리소스를 사용하지 않는 자체 Messages API 루프에서만 에이전트를 실행한다면 이번 변화의 영향을 받지 않습니다.

월요일에는 비프로덕션 에이전트 하나를 고르십시오. 정의 파일과 락파일을 실제 풀 리퀘스트에 올립니다. 현재 인수인계 방식과 검토 방식에 각각 몇 분이 드는지 기록하십시오. 그런 다음 안전한 환경에서 원격 변경을 만들고, 풀 리퀘스트 검사가 차단된 계획을 통과시키지 않는지 확인합니다. 이 검증이 끝난 뒤에만 병합 후 ant apply --yes .가 실행되도록 구성해야 합니다.

실무형 AI 워크플로 분석을 뉴스레터로 계속 받아보세요.