이것은 Apidog이 API 테스트 및 API 수명 주기 관리를 위한 명령줄 도구인 Apidog CLI를 개발한 방법을 공유하는 10부작 시리즈입니다. 순서대로 읽거나 관심 있는 게시물로 바로 이동하세요:
| 제목 | 초점 | |
|---|---|---|
| 1 | 우리는 126개의 MCP 도구를 만들었습니다. 하지만 이는 에이전트를 위한 최고의 솔루션이 아닙니다 | 문제 발견 |
| 2 | 우리가 새로운 Apidog CLI를 개발한 이유 | 아키텍처 개발 |
| 3 | 황금률: CLI는 사실을 생성하고, 모델은 사실에 따라 행동합니다 | 핵심 철학 |
| 4 | agentHints: CLI가 에이전트와 대화하도록 가르치기 |
구조화된 출력 |
| 5 | SKILL: 운영 경험을 코드로 제공 | 운영 경험 |
| 6 | 수치는 거짓말하지 않습니다: 30% 적은 도구 호출, 25% 적은 토큰 | 정량적 결과 |
| 7 | PRD부터 테스트 루프까지: Apidog CLI를 사용한 완벽한 에이전트 워크플로우 | 실용적인 튜토리얼 |
| 8 | 에이전트 도구에 CI/CD 호환성이 필수적인 이유 | DevOps 관점 |
| 9 | AI Branch: AI 에이전트를 통한 안전한 프로젝트 변경 | 보안 계층 |
| 10 | 스펙 우선은 과거입니다. 스킬 우선에 오신 것을 환영합니다. | 비전 및 미래 |
우리는 126개의 MCP 도구를 만들었습니다. 하지만 이는 에이전트와 함께 API 개발을 수행하기 위한 최고의 솔루션이 아니라는 것을 발견했습니다.
2025년 초에 MCP(Model Context Protocol)가 업계의 핫스팟이 되자, 모든 API 제품이 직면한 질문은 간단했습니다: "MCP가 있습니까?"
Apidog은 "예"라고 답했습니다. 우리는 단순한 데모가 아닌, 완전한 MCP 서버를 구축했습니다. MCP 클라이언트가 세션을 초기화하면, 서버는 sessionId를 생성하고 Redis를 통해 세션 상태를 저장했습니다. 이는 프로토콜 수준의 세션 시스템이었습니다. 우리는 도구를 네이티브 프로젝트 도구, 내장 도메인 도구, 그리고 OpenAPI 엔드포인트 정의에서 자동으로 변환된 126개의 생성된 도구로 분류했습니다.
Apidog MCP는 MCP 통합이 필요한 사용자에게 계속 작동하며 서비스를 제공합니다. 이는 MCP 프로토콜을 따르는 표준화된 도구 연결을 제공하여 생태계에 가치를 더합니다.
하지만 복잡한 R&D 워크플로우를 포함하는 실제 작업에 들어가면서 우리는 한계를 발견했습니다. 사용자가 "이 엔드포인트에 대한 테스트를 추가하고 검증을 실행하는 것을 도와주세요"라고 말하면, 에이전트는 어떤 도구를 어떤 순서로 어떤 유효성 검사를 통해 사용할지 결정해야 하는 무작위 도구들의 벽에 부딪혔습니다.
우리는 깨달았습니다: MCP는 도구 연결에 탁월하지만, 복잡한 R&D 작업에는 도구 연결 이상의 것이 필요합니다. 바로 실행 가능한 엔지니어링 프로세스입니다.
이러한 통찰력은 우리가 개발 워크플로우를 더 잘 처리하는 더 나은 접근 방식인 Apidog CLI를 개발하도록 이끌었습니다.
Apidog CLI란 무엇인가요?
Apidog CLI는 API 테스트를 위한 명령줄 도구로, 터미널 또는 CI/CD 파이프라인에서 직접 테스트 시나리오를 실행하고, API 문서를 관리하며, 테스트 워크플로우를 자동화할 수 있습니다. API 리소스를 관리하기 위해 AI 에이전트를 위해 특별히 구축되었으며, 기존의 API 테스트용 CLI를 넘어 에이전트가 복잡한 워크플로우를 안전하게 실행하는 데 필요한 구조화된 출력, 스키마 유효성 검사, 다음 단계 지침을 제공합니다. GitHub Actions에서 자동화된 API 테스트를 실행하든, Claude Code로 코드에서 테스트 케이스를 생성하든, 프로젝트 전반에 걸쳐 테스트 시나리오를 유지 관리하든, Apidog CLI는 AI 에이전트와 API 테스트 인프라 사이의 다리 역할을 합니다.
빠른 시작: Apidog CLI + SKILL 사용해보기
이 시리즈에서 설명하는 접근 방식을 사용해보고 싶다면, 다음 방법으로 시작하세요:
# Apidog CLI 설치
npm install -g apidog-cli@latest
# AI 에이전트용 SKILL 설치
apidog skill install
# 버전 확인 (새로운 기능을 위해서는 2.2.5+ 필요)
apidog -v
# 인증
또는 AI 에이전트에게 설치를 요청하세요:
지침을 읽고 Apidog CLI 설치를 도와주세요:
첫 번째 에이전트 작업
설치 후, 에이전트에게 작고 위험 부담이 적은 작업을 부여하세요:
Apidog CLI를 사용하여 Apidog에서 첫 API 엔드포인트를 생성하는 것을 도와주세요.
먼저, Apidog CLI 설정을 확인하고 접근할 수 있는 프로젝트 목록을 보여주세요.
어떤 프로젝트를 사용할지 물어봐 주세요. 제가 확인하면, 간단한 GET /health
엔드포인트를 'Health Check'라는 이름으로 200 응답 예시와 함께 생성해 주세요.
작성하기 전에 구조화된 입력을 검증한 다음, 엔드포인트를 다시 읽어 요약해 주세요.
이것은 구체적인 시작점을 제공합니다: 에이전트는 설정을 확인하고, 작성하기 전에 묻고, 작은 API 정의를 생성하고, 작성하기 전에 유효성을 검사하며, 저장된 결과를 확인합니다.
핵심 아키텍처
| 계층 | 책임 |
|---|---|
| Apidog | API 및 테스트 자산(문서, 스키마, 목업, 테스트, 보고서) 관리 |
| CLI | 결정론적 실행 제공 (읽기, 유효성 검사, 쓰기, 실행) |
| SKILL | 작업 판단 및 운영 경로 제공 (8개의 보조 Skills) |
| AI Branch | 병합 전 사람 검토를 위한 변경 사항 격리 |
| Agents | 목표 이해, 명령 호출, 피드백 기반 조정 |
에이전트 중심 테스트를 위한 더 안전한 루프
AI Branch를 외부 안전 계층으로 사용하면 전체 워크플로우는 다음과 같습니다:
┌─────────────────────────────────────────────────────────────────────┐
│ AI BRANCH (안전 계층) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 자산 읽기 │────▶│ 생성 │────▶│ 유효성 │ │
│ │ (CLI get) │ │ (에이전트) │ │ 검사 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 테스트 실행 │◀────│ 다시 읽기 │◀────│ 쓰기 │ │
│ │ (apidog run) │ │ (CLI get) │ │ (AI Branch로) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ 사람의 검토 및 병합 │ │
│ │ (사용자가 메인 브랜치 전에 확인) │ │
│ └──────────────────────────────────────┘ │
이 루프가 중요한 이유는 많은 Apidog 리소스가 구조화되어 있기 때문입니다. 테스트 케이스와 테스트 시나리오에는 요청 데이터, 어설션, 변수 추출, 전/후 처리기, 단계 순서, 환경 참조가 포함됩니다. 에이전트가 구조를 추측하면 작은 실수라도 쓰기 실패, 불완전한 표시 또는 예상대로 작동하지 않는 테스트로 이어질 수 있습니다.
에이전트가 생성하도록 하고, CLI가 유효성을 검사하며, AI Branch가 사람의 검토가 있을 때까지 변경 사항을 격리하도록 하세요.
Apidog CLI 여정 개요
이 시리즈는 우리가 API R&D 워크플로우를 위한 더 나은 전략으로 Apidog CLI를 개발한 과정을 문서화합니다.
Apidog MCP는 표준화된 도구 연결을 계속 제공하며, 이는 가치 있는 부분이고 우리는 이를 유지 관리합니다. 그러나 다단계 워크플로우, 유효성 검사 게이트 및 구조화된 실행을 포함하는 작업의 경우 CLI + SKILL이 더 나은 경험을 제공한다는 것을 발견했습니다.
우리는 사용자들이 CI/CD와 통합하여 자동화된 API 테스트를 실행하는 기존 CLI에 단순히 명령을 추가한 것이 아닙니다. 우리는 Apidog의 핵심 기능을 CLI에 체계적으로 도입하여 개발자, 스크립트 및 AI 에이전트를 위한 워크플로우 계층으로 만들었습니다.
핵심적인 차이점은 복잡성이 존재하는 위치입니다:
- MCP 경로: 모델 컨텍스트 및 도구 선택 단계에서의 복잡성 – 간단한 도구 호출에 적합
- CLI + SKILL 경로: 엔지니어링 시스템에 복잡성 분산 – 고급 워크플로우에 더 적합
결과적으로, 복잡한 작업을 위한 더 안전한 에이전트 워크플로우, 더 적은 도구 호출, 더 적은 토큰 낭비, 그리고 더 나은 오류 복구를 제공하며, MCP는 해당 접근 방식을 선호하는 사용자를 위해 계속 사용할 수 있습니다.
Apidog CLI 여정 지도
┌─────────────────────────────────────────────────────────────────┐
│ THE APIDOG CLI + SKILL JOURNEY │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [문제 발견] │
│ │ │
│ ┌───┐ │
│ │ 1 │ 우리는 126개의 MCP 도구를 만들었습니다. 그리고 │
│ └───┘ 워크플로우를 위한 더 나은 접근 방식을 발견했습니다. │
│ │ │
│ ▼ │
│ [아키텍처 개발] │
│ ┌───┐ │
│ │ 2 │ 우리가 완전히 새로운 Apidog CLI를 개발한 이유 │
│ └───┘ │
│ │ │
│ ├──────────────────┬──────────────────┐ │
│ ▼ ▼ ▼ │
│ [핵심 철학] [기술 설계] │
│ ┌───┐ ┌───┐ ┌───┐ │
│ │ 3 │ CLI는 사실을 │ 4 │ agentHints: │ 5 │ SKILL: 운영 │
│ └───┘ 생산한다 └───┘ CLI에 └───┘ 경험을 코드로 │
│ │ │ 가르치기 │ 전달하기 │
│ │ │ │ │
│ └──────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ [검증 및 실습] │
│ ┌───┐ ┌───┐ │
│ │ 6 │───────│ 7 │ │
│ └───┘ 숫자 │ PRD에서 테스트까지 │
│ │ │ 루프 │
│ ▼ ▼ │
│ [기반] [보안 계층] │
│ ┌───┐ ┌───┐ │
│ │ 8 │───────│ 9 │ │
│ └───┘ CI/CD │ AI Branch │
│ │ │ │
│ └────────┘ │
│ │ │
│ ▼ │
│ [비전] │
│ ┌────┐ │
│ │ 10 │ Spec-First → Skill-First │
│ └────┘ │
│ │
빠른 여정 탐색
1부: 문제 발견
우리는 126개의 MCP 도구를 만들었습니다. 그리고 AI 에이전트와 함께하는 API 개발 워크플로우를 위한 더 나은 접근 방식을 발견했습니다.
MCP는 표준화된 도구 연결을 제공하지만, 복잡한 R&D 워크플로우에서는 한계를 발견했습니다. 에이전트는 다단계 프로세스를 포함하는 작업을 수행할 때 무작위 도구의 벽에 부딪혔습니다. 이 게시물은 네 가지 구조적 문제와 CLI + SKILL이 워크플로우 중심 작업에 더 나은 이유를 탐구합니다.
2부: 아키텍처 개발
2. 우리가 완전히 새로운 Apidog CLI를 개발한 이유
우리는 MCP를 포기한 것이 아닙니다. 우리는 MCP가 최적화하지 않는 복잡한 워크플로우, 유효성 검사 게이트 및 구조화된 실행을 처리하기 위해 CLI + SKILL을 구축했습니다. 이 게시물은 실행 체인을 비교하고 CLI + SKILL이 복잡성을 엔지니어링 시스템에 분산시키는 동안 MCP가 계속 그 목적을 수행하는 방법을 설명합니다.
3부: 핵심 철학
3. 황금률: CLI는 사실을 생산하고, 모델은 사실에 따라 작동한다
핵심 원칙: 모델이 모든 규칙을 기억하게 하지 말고, 규칙이 올바른 위치에서 실행되도록 하세요. 이 게시물은 `cli-schema validate`를 소개합니다. 이는 필드 오류, 잘못된 열거형, 구조적 문제를 쓰기 실패로 이어지기 전에 잡아내는 품질 게이트입니다.
4-5부: 기술 설계
4. agentHints: CLI가 에이전트와 대화하는 법 가르치기
기존 CLI 출력은 사람을 위한 것입니다. 에이전트는 구조화된 결과, 실패 원인, 다음 단계 제안을 필요로 합니다. `agentHints`는 제품 경험을 기계가 읽을 수 있는 지침으로 전환하여 에이전트가 결정을 내려야 하는 바로 그곳에 나타납니다.
SKILL은 단순히 명령 참조가 아닙니다. 이는 AI 에이전트를 위한 운영 가이드입니다: 언제 명령을 사용할지, 무엇이 먼저 오는지, 어떤 필드를 추측해서는 안 되는지, 언제 유효성을 검사해야 하는지, 언제 다시 읽어야 하는지 등. SKILL은 워크플로우 지식을 버전 관리 가능하고 발전 가능한 가이드로 패키징합니다.
6-7부: 검증 및 실습
6. 숫자는 거짓말하지 않습니다: 도구 호출 30% 감소, 토큰 25% 감소
우리는 일반적인 작업에 대해 MCP와 CLI + SKILL을 비교했습니다. 도구 호출 단계가 약 30% 감소했습니다. 유효하지 않은 설명 및 재시도로 인한 토큰 소비가 약 25% 감소했습니다. 구조적 오류 재시도가 약 40% 감소했습니다. 이 게시물은 절감 효과가 어디에서 오는지 자세히 설명합니다.
7. PRD부터 테스트 루프까지: Apidog CLI와 함께하는 완전한 에이전트 워크플로우
실제 예시를 살펴보세요: 한 팀은 주문 환불 PRD와 코드베이스를 가지고 있습니다. 에이전트가 CLI + SKILL을 사용하여 OpenAPI를 생성하고, 테스트 케이스를 만들고, 구조를 검증하고, 테스트 시나리오를 구축하고, 검증을 실행하는 방법을 처음부터 끝까지 확인하세요.
8-9부: 기반 및 보안
8. 에이전트 도구에 CI/CD 호환성이 필수적인 이유
에이전트 친화성은 CI/CD 친화성을 기반으로 구축되어야 합니다. `apidog run`은 둘 다를 제공합니다: CI는 종료 코드, 보고서 파일, 안정적인 매개변수에 관심을 가지며, 에이전트는 구조화된 결과, 실패 원인, 다음 단계 제안에 관심을 가집니다. 하나의 명령, 여러 소비자.
9. AI Branch: AI 에이전트로 더 안전한 프로젝트 변경
에이전트가 프로젝트 리소스를 수정할 때 안전이 중요합니다. AI Branch는 격리된 편집을 제공합니다. 변경 사항은 사람의 검토가 있을 때까지 별도의 브랜치에 유지됩니다. 이는 자동화된 변경 사항이 메인 브랜치에 직접 영향을 미 미치는 것을 방지합니다. 자신 있게 생성하고, 검토한 다음 병합하세요.
10부: 비전 및 미래
10. Spec-First는 어제였습니다. Skill-First에 오신 것을 환영합니다.
AI 에이전트가 워크플로우에 합류하면서 API 개발이 변화하고 있습니다. Spec-First는 인간의 협업을 위한 것이었습니다. Skill-First는 스펙, 테스트, 시나리오를 실행 가능하고 검증 가능한 스킬로 패키징하여 에이전트 시대를 위한 기존 접근 방식을 보완합니다. 이 게시물은 미래를 설명하고 구체적인 시작 단계를 제공합니다.
핵심 요점 (TL;DR)
| 통찰 | 의미 |
|---|---|
| MCP와 CLI + SKILL은 다른 요구를 충족합니다 | MCP는 도구를 연결하고, CLI + SKILL은 워크플로우를 실행합니다. 작업에 맞는 것을 사용하세요. |
| 복잡성은 컨텍스트가 아닌 엔지니어링에 속합니다 | 126개 도구 × 500 토큰 = 복잡한 워크플로우에 대한 50,000 토큰의 부담 |
| `cli-schema validate`는 품질 게이트입니다 | 쓰기 실패가 아닌 로컬에서 오류를 잡으세요. |
| `agentHints`는 다음 단계를 안내합니다 | 에이전트가 "상상"에 기반하여 작성하는 것을 방지합니다. |
| SKILL은 운영 경험을 패키징합니다 | 단순한 명령이 아닌, 에이전트를 위한 워크플로우 지혜 |
| CI/CD는 여전히 기반입니다 | 에이전트 기능은 CI를 대체하는 것이 아니라 그 위에 추가됩니다. |
| AI Branch는 안전 계층을 제공합니다 | 병합 전 격리된 편집 + 사람 검토 |
읽기 시작
깊이 들어가 볼 준비가 되셨나요? 1부: 우리는 126개의 MCP 도구를 만들었습니다. 그리고 워크플로우를 위한 더 나은 접근 방식을 발견했습니다.부터 시작하세요.
하나의 작업 공간에서 API를 설계, 목업, 테스트, 문서화하려면 Apidog를 다운로드하세요. 명령줄 API 테스트, CI 자동화 및 AI 에이전트 워크플로우를 위한 Apidog CLI에 대해 더 알아보세요.