Building a Natural Language Interface to the Spotify Ads API with Claude Code Plugins | Spotify Engineering (새 탭에서 열림)

Spotify Ads API의 복잡한 계층 구조와 타겟팅 설정을 해결하기 위해 자연어 인터페이스를 제공하는 Claude Code 플러그인이 개발되었습니다. 이 플러그인은 사용자의 단순한 영어 요청을 분석하여 캠페인 생성, 광고 세트 구성, 소재 업로드 등 일련의 정교한 API 호출로 자동 변환합니다. 개발자는 복잡한 SDK를 유지보수하는 대신 Markdown 기반의 에이전트 설정을 통해 AI가 광고 플랫폼의 도메인 전문가처럼 동작하도록 제어할 수 있습니다.

Markdown 기반의 경량 플러그인 아키텍처

• 컴파일 없는 개발: 모든 기술(Skills)과 에이전트 로직이 Markdown(.md) 파일로 작성되어 빌드 단계나 패키지 매니저 없이도 인간이 읽기 쉽고 버전 관리가 용이한 구조를 가집니다.
• 모듈화된 구성 요소: 슬래시 커맨드를 정의하는 'Skills', 대화형 요청을 처리하는 'Agents', OAuth 토큰 갱신을 담당하는 'Hooks', 로컬 설정을 저장하는 'Settings'로 역할을 분리하여 관리 효율성을 높였습니다.
• 유연한 유지보수: API의 새로운 제약 사항이나 특이 동작이 발견될 경우, 코드를 수정하는 대신 Markdown 파일에 설명 문구를 한 줄 추가하는 것만으로 에이전트의 행동을 교정할 수 있습니다.

MCP 대신 CLI와 OpenAPI 명세서 활용

• 컨텍스트 윈도우 최적화: 수많은 엔드포인트를 가진 Ads API를 MCP(Model Context Protocol) 도구로 일일이 정의하면 LLM의 컨텍스트를 과도하게 소모하지만, 이 방식은 필요한 시점에만 명세서를 참조하여 효율적입니다.
• 투명한 디버깅: 플러그인이 실행하는 모든 API 호출을 curl 명령어로 노출하여, 사용자가 실제 전송되는 데이터를 실시간으로 모니터링하고 필요 시 복사하여 독립적으로 실행할 수 있게 합니다.
• 명세서 중심의 설계: 8,600줄에 달하는 OpenAPI v3 명세서를 소스 오브 트루스(Source of Truth)로 직접 사용하여, API 업데이트 시 명세서 파일만 교체하면 에이전트가 즉시 변경 사항을 학습합니다.

지능형 에이전트의 도메인 전문성 구현

• 다단계 오케스트레이션: "캠페인 생성"이라는 단일 요청을 받아 캠페인, 광고 세트, 광고 소재 생성이라는 세 가지 순차적 API 호출로 분해하고 각 단계에서 생성된 ID를 다음 단계로 자동 전달합니다.
• 데이터 변환 및 검증: 사용자 언어로 입력된 금액을 API 규격인 마이크로 단위로 변환하고, 지오타겟팅 이름을 지역 ID로 조회하며, 캠페인 실행 전 오디언스 규모가 최소 기준을 충족하는지 미리 검증합니다.
• 상호작용형 가이드: 필수 필드가 누락되었을 경우 에이전트가 사용자에게 추가 정보를 능동적으로 요청하며, 실행 전 전체 계획을 사용자에게 확인받아 의도치 않은 예산 집행을 방지합니다.

복잡한 엔터프라이즈 API를 위한 AI 인터페이스를 구축할 때, 기존의 무거운 SDK 방식보다는 Markdown과 OpenAPI 명세서를 결합한 가벼운 플러그인 방식이 개발 속도와 유지보수 면에서 더 유리합니다. 특히 광고 시스템처럼 실질적인 비용이 발생하는 도구에서는 AI의 내부 동작을 투명하게 공개하여 사용자가 제어권을 가질 수 있도록 설계하는 것이 중요합니다.