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 브랜치: AI 에이전트로 더 안전한 프로젝트 변경 | 보안 계층 |
| 10 | 스펙 우선은 어제 이야기. 스킬 우선에 오신 것을 환영합니다. | 비전 및 미래 |
우리는 일반적인 사용자 작업을 대상으로 MCP와 CLI + SKILL을 비교했습니다. 결과는 다음과 같습니다: 더 적은 도구 호출, 더 적은 토큰 낭비, 더 나은 오류 복구—그리고 데이터가 그 이유를 설명합니다.
중요한 질문
우리가 공유한 모든 철학과 설계 원칙들이 실제로 작동할까요?
우리는 내부적으로 두 접근 방식에 걸쳐 여러 일반적인 사용자 작업을 비교했습니다:
| 작업 유형 | 설명 |
|---|---|
| 테스트 케이스 추가 + 검증 | 엔드포인트용 테스트 케이스 생성, 테스트 실행 |
| 테스트 시나리오 유지 관리 | 복잡한 다단계 시나리오 업데이트 |
| 프로젝트 자산 가져오기/검증 | 데이터 가져오기, 구조 확인, 테스트 실행 |
결과는 단순히 주관적인 개선이 아니었습니다. **측정 가능한 감소**였습니다.
작업 1: 엔드포인트를 기반으로 테스트 케이스 추가
사용자 요청:
"이 엔드포인트에 대한 테스트를 추가하고 검증을 실행하세요"
MCP 경로
| 단계 | 발생하는 일 |
|---|---|
| 도구 발견 | 에이전트가 도구 목록을 검색 |
| 도구 선택 | 올바른 도구를 선택하기 위한 여러 차례 시도 |
| 필드 발견 | 에이전트가 도구 스키마를 읽음 |
| 필드 추측 | 에이전트가 필수 필드를 추측 |
| 쓰기 시도 | 에이전트가 생성 도구 호출 |
| 오류 응답 | 서버가 거부 (잘못된 필드/필수 누락) |
| 재시도 | 에이전트가 조정, 다시 시도 |
| 추가 재시도 | 성공할 때까지 반복 |
| 테스트 실행 | 에이전트가 실행 도구를 찾아 실행 |
일반적인 패턴:
도구 검색 → 도구 선택 → 스키마 읽기 → 필드 추측 → 쓰기 → 오류 → 재시도 → 쓰기 → 오류 → 재시도 → 성공 → 실행 도구 찾기 → 실행CLI + SKILL 경로
| 단계 | 발생하는 일 |
|---|---|
| SKILL 안내 | SKILL이 작업 유형을 식별, 워크플로 제공 |
| 엔드포인트 읽기 | CLI가 엔드포인트 사실을 읽음 |
| 테스트 케이스 생성 | 에이전트가 실제 엔드포인트 데이터를 기반으로 생성 |
| 로컬에서 유효성 검사 | cli-schema가 쓰기 전에 유효성 검사 |
| 쓰기 | CLI가 테스트 케이스 생성 |
| 다시 읽기 | CLI가 생성된 구조 + agentHints 반환 |
| 테스트 실행 | agentHints가 실행을 제안, 에이전트가 따름 |
일반적인 패턴:
SKILL 안내 → 엔드포인트 읽기 → 생성 → 유효성 검사 → 쓰기 → 다시 읽기 → 실행결과
| 측정 지표 | MCP 경로 | CLI + SKILL | 개선 |
|---|---|---|---|
| 도구 호출 단계 | ~15-20 | ~10-12 | ↓ ~30% |
| 설명에서 발생하는 토큰 | ~50,000 로드됨 | ~2,000 로드됨 | ↓ ~96% |
| 재시도에서 발생하는 토큰 | ~5,000+ 낭비 | ~500 낭비 | ↓ ~90% |
| 총 토큰 낭비 | ~55,000 | ~2,500 | ↓ ~25% |
도구 호출 단계가 약 30% 감소했습니다. 잘못된 도구 설명 및 오류 재시도로 인한 토큰 소비는 약 25% 감소했습니다.
작업 2: 구조화된 쓰기 (프로세서, 어설션, 추출기)
사용자 요청:
"이 테스트 케이스에 사후 작업 어설션 및 변수 추출을 추가하세요"
MCP 경로
| 단계 | 발생하는 일 |
|---|---|
| 필드 이름 추측 | 에이전트가 정확한 이름을 모름 |
| 열거형 값 추측 | 에이전트가 비교자(comparator), 유형(type)을 추측 |
| 쓰기 시도 | 서버가 잘못된 값을 거부 |
| 네트워크 재시도 | 각 오류마다 왕복 통신 |
| 여러 번의 시도 | 3-5회 재시도가 일반적 |
일반적인 오류:
| 잘못된 추측 | 올바른 값 | 재시도 횟수 |
|---|---|---|
comparator: "contains" |
comparator: "include" |
1-2 |
type: "global" |
type: "globals" |
1-2 |
subject: "responseBody" |
subject: "responseJson" |
1-2 |
각 오류는 네트워크 왕복 1회 + 응답 + 에이전트 처리로 구성됩니다.
CLI + SKILL 경로
| 단계 | 발생하는 일 |
|---|---|
| 테스트 케이스 읽기 | CLI가 실제 구조를 가져옴 |
| 추가 사항 생성 | 에이전트가 실제 형식을 기반으로 생성 |
| 로컬에서 유효성 검사 | cli-schema가 네트워크 전에 오류를 포착 |
| 로컬에서 수정 | 에이전트가 유효성 검사 결과에 따라 조정 |
| 재검증 | 수정 사항 확인 |
| 쓰기 | 유효한 쓰기만 서버로 전송 |
모든 오류가 로컬에서 포착됩니다. 필드 오류로 인한 네트워크 재시도는 없습니다.
결과
| 측정 지표 | MCP 경로 | CLI + SKILL | 개선 |
|---|---|---|---|
| 구조적 오류로 인한 네트워크 재시도 | 3-5 | 0 | ↓ ~100% |
| 오류 응답에서 발생하는 토큰 | ~2,000 | ~0 | ↓ ~100% |
| 총 반복 호출 | ~5 | ~1 | ↓ ~40% |
구조적 오류로 인한 반복 호출이 약 40% 감소했습니다.
작업 3: 생성 후 연속 작업
사용자 요청:
"이 엔드포인트를 사용하여 테스트 시나리오를 만드세요"
MCP 경로
| 단계 | 발생하는 일 |
|---|---|
| 시나리오 생성 | 에이전트가 생성 도구 호출 |
| 성공 응답 | 에이전트가 "생성됨"을 확인 |
| 쓰기 계속 | 에이전트가 즉시 업데이트/추가 |
| 다시 읽기 건너뛰기 | 에이전트가 실제 구조를 읽지 않음 |
| 가정에 기반한 쓰기 | 에이전트가 추측된 ID/구조로 쓰기 |
| 오류 또는 불완전 | 결과가 예상과 일치하지 않음 |
문제: 실행 관성.
모델은 성공 직후에 직접 진행하려 하며, 다시 읽기 단계를 건너뛰는 경향이 있습니다.
CLI + SKILL 경로
| 단계 | 발생하는 일 |
|---|---|
| 시나리오 생성 | CLI가 시나리오 생성 |
| 성공 + agentHints | CLI가 성공 + 다음 단계 제안 반환 |
agentHints: "먼저 다시 읽기" |
에이전트가 제안을 확인 |
| 제안 따르기 | 에이전트가 다시 읽기 |
| 실제 구조로 작업 | 에이전트가 정확한 데이터로 진행 |
agentHints는 명시적으로 다시 읽기를 제안합니다. 에이전트는 이를 따릅니다.
결과
| 측정 지표 | MCP 경로 | CLI + SKILL | 개선 |
|---|---|---|---|
| 계속하기 전에 다시 읽은 비율 | ~20% | ~85% | ↑ ~425% |
| 직접적인 이동으로 인한 오류 재시도 | ~3-5 | ~0-1 | ↓ ~21% |
에이전트가 능동적으로 다시 읽고, 유효성을 검사하고, 검증을 실행하는 비율이 크게 증가했습니다. 다음 단계로 직접 이동하여 발생하는 오류 재시도는 약 21% 감소했습니다.
요약: 절감 효과의 원천
| 절감 원천 | 설명 |
|---|---|
| 도구 발견 | CLI 명령어는 명확한 이름을 가지며; SKILL이 선택을 안내 |
| 스키마 유효성 검사 | 로컬 유효성 검사가 네트워크 호출 전에 오류를 포착 |
| 오류 복구 | agentHints는 단순히 "실패"가 아닌 실행 가능한 제안을 제공 |
| 다시 읽기 안내 | 가정에 기반한 쓰기 방지 |
| 워크플로 순서 | SKILL이 의사 결정 지점을 감소 |
실제 비용 분석
핵심 통찰:
제품의 에이전트 활성화는 도구가 많을수록 좋다는 것이 아닙니다.
모델이 실제로 소비하는 것:
| 비용 유형 | MCP 부담 | CLI + SKILL 부담 |
|---|---|---|
| 컨텍스트 | 도구 설명, 스키마 | 작업 중심의 SKILL만 해당 |
| 주의력 | 많은 도구 중에서 선택 | 안내된 워크플로 따르기 |
| 경로 선택 | 시퀀스 추측 | SKILL 정의 시퀀스 |
| 사용자 토큰 비용 | 재시도, 실패한 호출 | 유효성 검사된 쓰기, 더 적은 호출 |
도구 수가 증가하면, 모델이 실제로 소비하는 것은 API 호출 능력이 아니라 컨텍스트, 주의력, 경로 선택, 사용자 토큰 비용 간의 트레이드오프입니다.
엔지니어링 원칙
목표:
이러한 비용을 모델 컨텍스트에서 벗어나 엔지니어링 시스템이 감당할 수 있는 위치로 옮기는 것.
| 비용 | MCP 위치 | CLI + SKILL 위치 |
|---|---|---|
| 도구 발견 | 모델이 검색해야 함 | SKILL이 제공 |
| 필드 유효성 검사 | 모델이 알아야 함 | cli-schema가 유효성 검사 |
| 다음 단계 안내 | 모델이 결정해야 함 | agentHints가 제안 |
| 제품 의미론 | 모델이 이해해야 함 | CLI가 처리 |
엔지니어링 시스템이 복잡성을 흡수합니다. 모델은 생성과 판단에 집중합니다.
이 수치들이 의미하는 것
이 수치들은 더 구체적인 문제를 설명합니다:
| 통찰 | 함의 |
|---|---|
| 30% 더 적은 도구 호출 | 복잡성이 발견에서 안내로 이동 |
| 25% 더 적은 낭비 토큰 | 네트워크 전에 오류 포착 |
| 40% 더 적은 구조적 재시도 | 유효성 검사 게이트 작동 |
| 21% 더 적은 점프 오류 | agentHints가 맹목적인 진행 방지 |
CLI + SKILL은 단순히 아키텍처적 우아함이 아닙니다. 측정 가능한 효율성입니다.
다음 단계
이제 수치로 접근 방식을 검증했으니, 실제로 어떻게 작동하는지 살펴봅시다.
7부인 PRD에서 테스트 루프까지: 완벽한 에이전트 워크플로에서는 "주문 환불" PRD를 가진 팀이 에이전트가 CLI + SKILL을 사용하여 OpenAPI를 생성하고, 테스트를 만들고, 유효성을 검사하고, 확인하는 실제 사례를 살펴보겠습니다.
주요 내용
- 도구 호출 단계가 약 30% 감소했습니다.
- 설명 및 재시도로 인한 토큰 낭비가 약 25% 감소했습니다.
- 구조적 오류 재시도가 약 40% 감소했습니다.
- 다시 읽기를 건너뛰는 것으로 인한 점프 오류가 약 21% 감소했습니다.
- 절감 효과는 안내된 발견, 로컬 유효성 검사, 실행 가능한 힌트에서 비롯됩니다.
- 복잡성은 컨텍스트에서 엔지니어링 시스템으로 이동했습니다.
하나의 워크스페이스에서 API를 설계, 목업, 테스트, 문서화하려면 Apidog을 다운로드하세요. 명령줄 API 테스트, CI 자동화 및 AI 에이전트 워크플로를 위한 Apidog CLI에 대해 자세히 알아보세요.