Azure Cosmos DB vNext 에뮬레이터를 사용한다면, 아마 다음과 같은 로컬 개발 루프(local development loop)를 알고 계실 것입니다: 에뮬레이터를 시작하고, 여기에 연결하고, 리소스를 생성하고, 테스트 데이터를 로드하고, 쿼리를 실행한 뒤 결과를 검사하는 과정입니다. 각 단계는 간단하지만, 이들을 모두 수행하면 실제로 구축하려는 애플리케이션을 테스트하기 전에 설정 작업이 추가됩니다.

에이전트가 에뮬레이터와 작동하는 방식

에뮬레이터에는 데이터베이스, 컨테이너 및 항목(items)을 다루기 위한 오픈 소스 CLI인 Cosmos DB Shell이 포함되어 있습니다. 이는 에뮬레이터 컨테이너 내부에서 실행되며 로컬 엔드포인트(endpoint)와 잘 알려진 키(well-known key)를 처리하여, 개발자에게 에뮬레이터를 다룰 수 있는 직접적이고 스크립트 가능한 방식을 제공합니다.

CLI는 작업을 명시적인 명령으로 노출하고 에이전트가 검사할 수 있는 결과를 반환하기 때문에 에이전트 워크플로(agent workflows)에 매우 적합합니다. 에이전트는 내장된 도움말을 통해 명령을 찾아내고, 비대화형(non-interactively)으로 명령을 실행하며, 오류에 대응하고, 출력을 사용하여 다음 행동을 선택할 수 있습니다. 이러한 특성 덕분에 CLI는 에이전트를 위한 실용적인 인터페이스가 됩니다. Cosmos DB Shell은 이러한 모델을 로컬 에뮬레이터에 도입합니다.

예를 들어, 에이전트는 에뮬레이터 컨테이너 내부에서 Cosmos DB Shell을 비대화형으로 실행할 수 있습니다:

docker exec <emulator-container> cosmoshell.sh -c '<command>'

이는 GitHub Copilot CLI, Codex, Claude Code와 같은 AI 코딩 에이전트(AI coding agents)에게 에뮬레이터와 작업할 수 있는 간단한 방법을 제공합니다. 개발자는 작업을 일련의 셸 명령(shell commands)으로 변환하는 대신, 필요한 결과만을 설명하면 됩니다. 명령(Command)에 대한 접근 권한은 시작점일 뿐입니다. 에이전트는 여전히 에뮬레이터를 찾고, 적절한 명령을 선택하며, 안전 경계(safety boundaries)를 준수하고, 작업 내용을 검증하기 위한 운영 절차(operating procedure)가 필요합니다.

Agent Skill은 요청과 세션 전반에 걸쳐 재사용할 수 있도록 작업별 지침(task-specific guidance)을 패키징함으로써 그 간극을 메워줍니다. 로컬 에뮬레이터의 경우, cosmosdb-emulator-vnext 스킬을 통해 에이전트가 리소스를 검사하고, 데이터베이스와 컨테이너(containers)를 생성하며, 테스트 데이터를 로드하고, Cosmos DB Shell을 통해 쿼리(queries)를 실행할 수 있도록 지원합니다.

GitHub에서 스킬 살펴보기: cosmosdb-vnext-emulator-skill

프롬프트에서 로컬 테스트 데이터까지

멀티 테넌트(multi-tenant) 주문 처리 애플리케이션을 구축하는 개발자를 가정해 보겠습니다. 통합 테스트(integration tests)를 위해서는 여러 테넌트와 주문 라이프사이클(order lifecycle)의 다양한 단계에 걸친 데이터가 필요합니다. 이러한 데이터를 수동으로 생성하고 유지 관리하는 것은 빠르게 지루한 작업이 될 수 있습니다.

대신, 개발자는 코딩 에이전트에게 다음과 같은 프롬프트(prompt)를 줄 수 있습니다:

멀티 테넌트 주문 처리 앱을 구축 중이며 통합 테스트를 위한 실감 나는 데이터가 필요합니다. 두 개의 테넌트를 포함하고 신규, 배송됨, 취소됨 주문이 혼합된 합성 주문(synthetic orders) 데이터로 로컬 Cosmos DB 에뮬레이터를 설정해 주세요.
...

로컬 에뮬레이터가 이미 실행 중인 상태에서 GitHub Copilot CLI를 사용하여 이 프롬프트를 테스트했습니다. 에이전트는 에뮬레이터를 찾아냈고, 번들로 제공되는 Cosmos DB Shell을 사용하였으며, /tenantId로 파티셔닝된 Orders 컨테이너를 포함하는 OrdersDB를 생성했습니다.

그 다음, 두 테넌트(tenant) 모두에 대해 균형 잡힌 합성 주문(synthetic orders) 세트를 생성했습니다. 각 주문에는 고객 상세 정보, 중첩된 품목(nested line items), 타임스탬프(timestamps), 배송 정보 및 총액이 포함되었습니다. 또한 배송된 주문에 대한 추적 정보나 취소된 주문에 대한 취소 사유와 같이 상태별 특정 필드도 추가되었습니다.

설정 요약(setup summary)에는 에이전트가 생성한 내용이 표시되었습니다:

Database: OrdersDB
Container: Orders
Partition key: /tenantId
...

데이터를 확인하기 위해 에이전트는 컨테이너를 쿼리(query)했습니다. 12개의 주문 중 6개는 다음과 같습니다:

요청이 개방형(open-ended)이기 때문에 이름, 값 및 문서 수는 달라질 수 있습니다. 워크플로(workflow)는 동일합니다: 리소스를 생성하고, 데이터를 로드한 다음, 이를 다시 쿼리하는 것입니다. 저장된 주문을 보여줌으로써 데이터가 에뮬레이터(emulator)에 있으며 애플리케이션에서 사용할 준비가 되었음을 확인합니다.

이 시점에서 개발자는 시드 스크립트(seed script)를 작성하거나 문서를 수동으로 조립할 필요 없이, 통합 테스트(integration testing)를 위한 영속화(persisted) 및 파티셔닝(partitioned)된 데이터를 확보했습니다.

프롬프트(prompt)가 운영 절차가 아닌 애플리케이션의 요구 사항을 설명하고 있다는 점에 주목하십시오. 에뮬레이터를 찾는 법, 번들로 제공되는 셸(shell)을 사용하는 법, 비대화형 명령(non-interactive commands)을 선택하는 법, 또는 변경 사항을 확인하는 법에 대해서는 아무것도 언급하지 않습니다.

에이전트 스킬(Agent Skill)을 사용하는 이유

이러한 모든 운영 지침을 매 프롬프트에 포함할 수도 있습니다. 일회성 작업에는 효과적이지만, 동일한 안내를 반복하는 것은 곧 지루해집니다. 또한 중요한 제약 조건이 누락되거나 다르게 표현될 경우 결과가 달라질 수도 있습니다.

안내 사항을 전역 지침(global instructions)으로 이동하면 이러한 반복을 피할 수 있으며, 관련 없는 작업을 수행하는 동안에도 에뮬레이터 전용 컨텍스트(context)를 사용할 수 있게 됩니다.

에이전트 스킬 (Agent Skill)은 두 가지 트레이드오프 (tradeoffs)를 모두 피할 수 있게 해줍니다. cosmosdb-emulator-vnext 스킬은 에뮬레이터 가이드를 한곳에 유지하며, 관련 요청이 감지되었을 때 이를 사용할 수 있도록 합니다. 마크다운 (Markdown) 파일 형태인 이 스킬은 공유, 검토, 테스트, 버전 관리 (versioned)가 가능하며, 팀의 컨벤션 (conventions)이나 테스트 워크플로 (testing workflow)에 맞춰 조정할 수 있습니다.

동일한 접근 방식은 Cosmos DB 개발의 다른 부분에도 확장됩니다. Azure Cosmos DB 팀은 Cosmos DB와 함께 작업하는 AI 코딩 에이전트를 위한 스킬 모음인 Cosmos DB Agent Kit를 유지 관리하고 있습니다. 여기에는 데이터 모델링 (data modeling), 파티션 키 (partition-key) 설계, 쿼리 최적화 (query optimization), SDK 사용법, 인덱싱 (indexing), 처리량 (throughput), 보안 (security) 및 모니터링 (monitoring)에 대한 가이드가 포함되어 있습니다.

에뮬레이터 스킬은 Agent Kit에 통합되어 다른 Cosmos DB 스킬들과 함께 그곳에서 유지 관리될 수도 있습니다.

직접 시도해 보세요

에이전트 스킬 (Agent Skills)은 코딩 에이전트 전반에 걸쳐 동일한 스킬을 재사용할 수 있게 해주는 가볍고 개방된 표준 (open standard)입니다.

스킬을 설치하고 로컬 에뮬레이터와 함께 사용해 보세요:

npx skills add abhirockzz/cosmosdb-vnext-emulator-skill

그런 다음 위에서 언급한 주문 처리 (order-processing) 프롬프트를 실행하여 첫 번째 테스트 데이터셋을 생성하세요. 그 후, 애플리케이션에 필요한 데이터와 워크플로에 맞춰 요청을 조정하면 됩니다.

로컬 에뮬레이터, Cosmos DB Shell, 그리고 스킬이 결합되면, 작업이 수행되는 방식을 숨기지 않으면서도 이러한 종류의 설정을 반복 가능하게 (repeatable) 만듭니다. 개발자는 에이전트가 명시적인 명령을 실행하고, 결과를 검증하며, 검사 가능한 실행 흔적 (execution trail)을 남기는 동안 필요한 데이터를 설명할 수 있습니다.