들어가며: 광고 API, 강력하지만 너무 먼 그대

스포티파이 Ads API v3는 30개가 넘는 리소스 타입과 중첩된 타겟팅 구조, 캠페인 → 광고 세트 → 광고로 이어지는 다단계 엔티티 계층을 가지고 있습니다. "코네티컷 주 리스너를 타겟으로 한 오디오 캠페인을 만들고 싶다"는 단순한 의도를 실행으로 옮기기까지의 인지적 거리는 상당합니다.

스포티파이 엔지니어링 팀은 이 간극을 메우기 위해 Claude Code 플러그인을 개발했습니다. 사용자가 평범한 영어(또는 한국어)로 원하는 바를 설명하면 시스템이 나머지를 알아서 처리하는 구조입니다. 단일 자연어 요청이 완전하고 올바른 캠페인 구조로 변환됩니다.

이 플러그인은 Markdown 파일, bash 스크립트, 두 개의 작은 Python 헬퍼로 구성되어 있으며, 완전히 오픈소스로 공개되어 있습니다. 이 글에서는 그 아키텍처와 기술적 선택, 그리고 LLM 기반 에이전트 위에서 개발자 도구를 구축하면서 배운 점을 공유합니다.

Claude Code terminal showing natural language campaign creation for Spotify Ads API Software Concept Art

핵심 아키텍처: Markdown이 전부다

이 플러그인의 가장 놀라운 점은 컴파일된 코드가 하나도 없다는 것입니다. 빌드 단계, 패키지 매니저, 번들러, 트랜스파일러가 전혀 없습니다. 모든 구성 요소가 .md 파일로 작성되어 있습니다.

네 가지 구성 요소

| 구성 요소 | 역할 | 구현 방식 ||-----------|------|-----------|| Skills | 슬래시 명령어 정의 | 각 명령어의 동작, API 엔드포인트, 요청 포맷, 출력 처리를 설명하는 Markdown 파일 || Agents | 자유형 자연어 처리 | 사용자가 광고 작업을 대화식으로 설명하면 이를 API 호출로 분해하는 Markdown 파일 || Hooks | 도구 호출 전 가로채기 | OAuth 토큰 갱신, HTTP 헤더 주입을 투명하게 처리 || Settings | 사용자별 설정 저장 | 자격 증명, 광고 계정, 환경 설정을 gitignored 로컬 파일에 저장 |### 자연어 에이전트: 도메인 전문가 번역기agents/spotify-ads-request-builder.md 하나의 Markdown 파일이 LLM을 스포티파이 Ads API 전문가로 변신시킵니다. 이 시스템 프롬프트는 다음과 같은 지식을 포함합니다:- 값 변환: 달러 → 마이크로 단위, 날짜 설명 → ISO 8601, 플랫폼 이름 → API enum 값- 다단계 오케스트레이션: "전체 캠페인 생성"을 캠페인 → 광고 세트 → 광고의 3단계 API 호출로 분해, 단계 간 ID 전달- 지오타겟팅 조회: "코네티컷 타겟"이라고 하면 지오타겟팅 검색 엔드포인트를 호출해 지역 ID를 찾고 올바른 구조로 geo_targets 객체 구성- 사전 검증: 광고 세트 생성 전에 오디언스 예상 엔드포인트를 호출해 타겟팅이 최소 임계값을 충족하는지 확인- 실행 제어: 사용자의 auto_execute 설정에 따라 curl 명령어를 보여주고 확인을 받거나 직접 실행

# 예시: 자연어 요청이 API 호출로 변환되는 과정 (개념 코드)
# 사용자: "25-44세 미국인 대상, 하루 100달러 예산의 Back to School Promo 오디오 캠페인 생성"

# 1단계: 지오타겟팅 ID 조회
# curl -X GET "https://api.spotify.com/v1/targets/geos?q=US"
# → 응답에서 "US" 지역 ID 추출

# 2단계: 통화 변환 (100 USD → 10000000 마이크로 단위)
# 3단계: 캠페인 생성 POST
# 4단계: 광고 세트 생성 POST (캠페인 ID, 타겟팅, 예산 포함)
# 5단계: 광고 생성 POST (광고 세트 ID, 크리에이티브 에셋 포함)

이 모든 단계가 Markdown 파일에 정의된 규칙에 따라 자동으로 실행됩니다.

Diagram of OpenAPI Links connecting campaign, ad set, and ad entities in Spotify Ads API System Abstract Visual

왜 MCP가 아니라 CLI + OpenAPI Spec인가?

Model Context Protocol(MCP)은 LLM과 외부 도구를 연결하는 표준으로 떠오르고 있습니다. 하지만 스포티파이 팀은 여러 이유로 MCP를 선택하지 않았습니다.

1. API 표면이 너무 넓다

스포티파이 Ads API는 수십 개의 엔드포인트와 중첩된 요청 스키마를 가지고 있습니다. 각각을 MCP 도구로 정의하면 거대한 도구 레지스트리가 생성되어, 사용자가 해당 엔드포인트를 필요로 하지 않더라도 매 상호작용마다 상당한 컨텍스트 윈도우를 소모합니다. 반면 Claude Code 플러그인 접근법에서는 에이전트가 필요할 때만 관련 참조 문서를 로드합니다.

2. Curl 명령어는 투명하고 디버깅 가능하다

플러그인이 만드는 모든 API 호출은 curl 명령어로 사용자에게 표시됩니다. 사용자는 정확히 무엇이 전송되는지 보고, 복사하고, 수정하고, 독립적으로 실행할 수 있습니다. 이 투명성은 모든 요청이 실제 예산에 영향을 미칠 수 있는 광고 시스템에서 감사 가능성과 사용자 통제권을 제공합니다.

3. OpenAPI Spec이 진실의 원천(Source of Truth)이다

스포티파이 Ads API는 약 8,600줄의 포괄적인 OpenAPI v3 스펙을 제공합니다. 이를 MCP 도구 스키마로 번역하고 API가 진화할 때마다 그 번역을 유지하는 대신, 플러그인에 스펙을 직접 탑재합니다. 에이전트가 엔드포인트의 파라미터나 응답 형식을 이해해야 할 때 이 스펙을 읽습니다. API가 변경되면 파일 하나만 업데이트하면 됩니다.

OpenAPI Links: 에이전트를 위한 워크플로우 그래프

여기서 가장 흥미로운 부분은 OpenAPI Links의 활용입니다. OpenAPI 3.x 스펙의 상대적으로 덜 사용되는 기능인 Links는 작업 간의 관계를 정의합니다. 특히 한 작업의 응답을 다른 작업의 입력으로 사용하는 방법을 명시합니다.

스포티파이 Ads API 스펙은 Links를 통해 전체 엔티티 계층을 인코딩합니다:

# 예시: 캠페인 생성 응답이 광고 세트 생성을 가리킴
'201':
  links:
    createAdSet:
      operationId: createAdSet
      parameters:
        ad_account_id: '$request.path.ad_account_id'
        campaign_id: '$response.body#/id'

인간 개발자에게는 암시적이었던 엔티티 계층(캠페인 → 광고 세트 → 광고)이 LLM 에이전트에게는 기계가 읽을 수 있는 형태로 명시적으로 선언됩니다. $response.body#/id와 같은 런타임 표현식은 에이전트에게 어떤 필드를 추출하고 다음 요청에 주입해야 하는지 정확히 알려줍니다.

graph LR
    A[자연어 요청] --> B[에이전트 분해]
    B --> C[캠페인 생성 POST]
    C --> D[광고 세트 생성 POST]
    D --> E[광고 생성 POST]
    C -.-> F[OpenAPI Links: 응답 ID 전달]
    D -.-> F

이 접근법은 근거자료에서 확인할 수 있듯이, 단순한 광고 플로우를 넘어 복잡한 API 통합으로 확장 가능한 패턴을 보여줍니다.

Developer reviewing curl command output from LLM agent for Spotify Ads API Technical Structure Concept

국내 개발 생태계에서의 적용 맥락

한국의 광고 플랫폼(예: 네이버, 카카오)도 유사하게 복잡한 API 구조를 가지고 있습니다. 이 접근법은 다음과 같은 국내 환경에 직접 적용할 수 있습니다:

  • 복잡한 광고 API의 자연어 인터페이스화: 네이버 쇼핑광고, 카카오모먼트 등 복잡한 타겟팅 구조를 가진 API에 Claude Code 플러그인 패턴을 적용
  • SI 프로젝트의 문서 기반 자동화: 레거시 SI 환경에서 Markdown 기반 에이전트를 활용한 API 통합 자동화
  • OpenAPI Links 활용: 국내 API 제공자들이 OpenAPI Links를 적극 활용하면 LLM 기반 도구와의 호환성이 크게 향상

이 기술의 한계 또는 주의사항

  • 에이전트 신뢰도: 현재는 비교적 단순한 광고 플로우를 기준으로 로직이 작성되어 있어, 매우 복잡하거나 예외적인 케이스에서는 추가적인 프롬프트 엔지니어링이 필요합니다.
  • 멱등성 키 미지원: 현재 버전에서는 네트워크 재시도나 에이전트 재실행 시 중복 캠페인이 생성될 위험이 있습니다. 팀은 멱등성 키 도입을 계획 중입니다.
  • 플랫폼 종속성: 현재 Claude Code에 특화되어 있으나, Codex나 Gemini CLI 등 다른 플랫폼으로의 확장을 검토 중입니다.

함께 보면 좋은 글

다음 단계 학습 방향

  1. OpenAPI 3.x Links 스펙을 깊이 있게 학습하고, 자신의 API에 Links를 적용해보세요.
  2. Claude Code 플러그인 개발에 도전해보세요. Markdown 파일 몇 개로 시작할 수 있습니다.
  3. 자연어 인터페이스 설계의 원칙을 공부하고, 복잡한 도메인을 단순화하는 프롬프트 엔지니어링을 연습해보세요.

이 플러그인은 하나의 명확한 테제에 기반합니다: 복잡한 API에 대한 최고의 인터페이스는 자연어이며, 상세한 문서와 투명한 실행이 뒷받침되어야 한다. 사용자는 원하는 바를 말합니다. 에이전트는 API 호출을 알아서 처리합니다. Hook 레이어는 인증을 투명하게 처리합니다. 그리고 모든 curl 명령어는 보고, 복사하고, 디버깅할 수 있습니다.

프레임워크도, 런타임도, curl, jq, python3 외의 의존성도 없습니다. 진실의 원천은 OpenAPI 스펙입니다. 비즈니스 로직은 산문(prose)입니다.

이 접근법이 가장 복잡한 API 통합까지 확장 가능할지는 열린 질문입니다. 하지만 스포티파이 Ads API처럼 의도와 올바른 POST 요청 시퀀스 사이의 거리가 상당한 경우, 놀랍도록 잘 작동합니다.

본 콘텐츠는 신뢰할 수 있는 출처를 바탕으로 AI 도구를 활용하여 초안이 작성되었으며, 편집자의 검토를 거쳐 발행되었습니다. 전문가의 조언을 대체하지 않습니다.