새로운 Apidog CLI + SKILL 개발 배경

이것은 Apidog이 API 테스트 및 API 수명 주기 관리를 위한 명령줄 도구인 Apidog CLI를 개발한 방법을 공유하는 10부작 시리즈입니다. 순서대로 읽거나 관심 있는 게시물로 바로 이동하세요:

MCP가 최적화하지 않는 복잡한 워크플로우(검증 게이트 및 구조화된 실행 포함)를 처리하기 위해 CLI + SKILL을 구축했습니다.

MCP는 계속해서 목적을 수행합니다

CLI + SKILL에 대해 자세히 알아보기 전에 명확히 하겠습니다: Apidog MCP는 여전히 사용 가능하며 유지 관리되고 있습니다.

MCP는 프로토콜에 따라 표준화된 도구 연결을 제공하며, 이는 다음과 같은 경우에 유용합니다:

• 단순하고 잘 정의된 작업
• MCP 기반 워크플로우를 선호하는 사용자
• MCP 준수 클라이언트와의 생태계 통합

우리는 MCP를 대체하지 않았습니다. 우리는 MCP를 보완하기 위해 CLI + SKILL을 구축했습니다.

우리가 발견한 것은 MCP가 도구를 연결하는 데 탁월하지만, 검증, 읽기, 확인을 포함하는 다단계 프로세스와 같은 복잡한 R&D 워크플로우의 경우 에이전트는 실행 가능한 엔지니어링 프로세스의 이점을 얻는다는 것입니다. 이것이 CLI + SKILL이 적합한 지점입니다.

다음과 같이 생각해보십시오:

이전 CLI: 마지막 단계에서 테스트 실행

Apidog CLI는 오랫동안 API 테스트 실행을 위한 명령줄 진입점이었습니다.

apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>

그 기반은 여전히 중요합니다. 팀은 다음을 위한 안정적인 방법이 필요합니다:

• 터미널에서 API 테스트 실행
• CI 파이프라인에서 보고서 생성
• 자동화 워크플로우 내에서 품질 게이트 유지

그러나 이전 CLI는 주로 테스트 실행에 중점을 두었습니다. 이는 워크플로우의 끝 부분에 나타났습니다:

설계 → 문서화 → 목 → 디버그 → 테스트 → [CLI 테스트 실행]

CLI는 다른 모든 작업이 완료된 후의 마지막 단계였습니다.

새로운 요구 사항: 에이전트는 더 많은 것을 필요로 합니다

API 개발이 변화하고 있습니다.

AI 에이전트는 이제 다음 단계에 참여하고 있습니다:

이러한 워크플로우에서 CLI는 기존 테스트를 실행하는 마지막 단계일 수 없습니다.

또한 에이전트가 다음을 수행할 수 있는 안정적인 방법을 제공해야 합니다:

• API 자산 읽기 (엔드포인트, 스키마, 환경)
• 테스트 자산 생성 또는 업데이트 (테스트 케이스, 테스트 시나리오)
• 쓰기 전에 구조화된 변경 사항 검증
• 프로젝트에 다시 쓰기
• 결과 확인

점진적 추가가 아닌 체계적인 확장

새로운 Apidog CLI는 이전 CLI에 몇 가지 명령을 추가하는 것에 그치지 않습니다.

이는 Apidog의 핵심 기능을 CLI에 체계적으로 도입하여 개발자, 스크립트 및 AI 에이전트를 위한 워크플로우 레이어로 만듭니다.

그 뒤에 있는 아키텍처 경계는 극적으로 변화했습니다.

MCP 대 CLI: 실행 체인 비교

복잡한 워크플로우에 대한 일반적인 실행 체인을 비교해 봅시다.

MCP 경로 (도구 연결에 적합)

MCP 세션 초기화
        ↓
도구 목록 + 도구 설명 로드
        ↓
에이전트가 도구 선택
        ↓
추가 도구 검색 (listOpenApiEndpoints)
        ↓
스키마 가져오기 (getOpenApiDetails)
        ↓
HTTP 호출 실행 (executeOpenApi)

MCP의 강점: 에이전트에 도구를 연결하기 위한 표준화된 프로토콜.

복잡성 배치: 대부분의 복잡성은 모델 컨텍스트 및 도구 선택 단계에 있습니다. 에이전트는 다음을 이해해야 합니다:

• 도구 목록
• 도구 설명
• 입력 스키마
• 호출 시퀀스
• 반환 구조

잘 작동하는 경우: 명확한 도구-작업 매핑을 가진 단순한 작업.

어려워지는 경우: 에이전트가 여러 도구를 조율하고, 제품 의미론을 이해하고, 유효성 검사를 처리해야 하는 복잡한 워크플로우.

CLI + SKILL 경로 (복잡한 워크플로우에 더 적합)

SKILL이 작업 유형 판단
        ↓
CLI가 제품 의미론적 명령 실행
        ↓
cli-schema가 구조 검증
        ↓
agentHints가 다음 단계 제안
        ↓
검증 루프 (읽기 또는 apidog run 실행)

CLI + SKILL의 강점: 복잡성을 엔지니어링 시스템으로 분산합니다.

복잡성 배치:

• SKILL: 방법론 및 워크플로우 지침
• CLI: 제품 의미론적 실행
• cli-schema: 쓰기 전 검증
• agentHints: 실행 후 탐색

잘 작동하는 경우: 다단계 워크플로우, 검증이 많은 작업, 에이전트 기반 테스트.

핵심 차이점: 복잡성이 존재하는 곳

이 두 가지 접근 방식의 차이점은 복잡성이 어디에 배치되는지입니다.

MCP에서 모델은 다음을 수행해야 합니다:

• 어떤 도구를 사용할지
• 도구 설명이 무엇을 말하는지
• 어떤 필드가 필수적인지
• 어떤 순서를 따를지
• 반환 구조가 무엇을 의미하는지

이는 작업-도구 매핑이 간단할 때 작동합니다.

CLI + SKILL에서 엔지니어링 시스템은 다음을 수행합니다:

• 이것이 어떤 작업 유형인지 (SKILL)
• 실행할 명령이 무엇인지 (CLI)
• 어떤 구조가 유효한지 (cli-schema)
• 다음에 무엇을 할지 (agentHints)

이는 워크플로우에 유효성 검사 게이트, 읽기 요구 사항 및 검증 루프가 있을 때 더 잘 작동합니다.

일반적인 워크플로우 예시

다음은 CLI + SKILL 워크플로우의 구체적인 예시입니다:

# 1단계: 사실 읽기
apidog endpoint get <endpointId> --project <projectId>

# 2단계: 쓰기 전 검증
apidog cli-schema validate test-case-create --file ./test-case-create.json

# 3단계: 검증 실행
apidog run --project <projectId> --out-dir ./apidog-reports

이 세 가지 명령은 세 가지 엔지니어링 작업을 나타냅니다:

복잡한 워크플로우를 위한 에이전트 경로

복잡한 다단계 워크플로우의 경우, 에이전트의 경로는 CLI + SKILL 구조의 이점을 얻습니다.

복잡한 워크플로우를 위한 MCP 경로

"도구 선택 → 스키마 이해 → 시퀀스 조율 → 오류 처리"

에이전트는 다음을 수행합니다:

• 많은 옵션 중에서 적절한 도구 선택
• 도구 설명 및 스키마 이해
• 올바른 시퀀스 조율
• 재시도를 통한 오류 처리

이는 작동할 수 있지만, 각 결정 지점에 대해 상당한 모델 추론이 필요합니다.

복잡한 워크플로우를 위한 CLI + SKILL 경로

"사실 읽기 → 변경 사항 생성 → 구조 검증 → 쓰기 → 검증 실행"

에이전트는 다음을 수행합니다:

• 기존 사실 먼저 읽기 (SKILL의 안내에 따라)
• 사실을 기반으로 변경 사항 생성
• 로컬에서 구조 검증 (cli-schema)
• 프로젝트에 쓰기
• 검증 실행 (agentHints가 다음 단계를 안내)

엔지니어링 시스템은 유효성 검사, 안내 및 확인을 처리하여 모델 추론 부담을 줄입니다.

두 경로 모두 작업을 완료할 수 있습니다. CLI + SKILL은 모델 컨텍스트 단계의 복잡성을 줄입니다.

CLI가 이제 다루는 내용

업그레이드를 통해 CLI는 이제 더 많은 핵심 Apidog 리소스를 다룹니다:

이는 Apidog CLI의 역할을 변화시킵니다.

이는 단순히 다른 모든 작업이 완료된 후 테스트를 실행하는 방법이 아닙니다.

이제 개발 루프 초기에 참여할 수 있습니다. 에이전트가 다음을 수행해야 하는 경우:

• 프로젝트 이해
• 테스트 자산 생성 또는 업데이트
• 변경 사항 검증
• 검증 실행

아키텍처 요약

둘 다 사용 가능합니다. 작업에 따라 선택하세요.

다음 단계

이제 CLI + SKILL이 MCP를 어떻게 보완하는지 살펴보았으니, 다음 질문은 다음과 같습니다:

CLI + SKILL이 복잡한 워크플로우에 효과적인 핵심 원칙은 무엇일까요?

3부 황금률: CLI는 사실을 생성하고, 모델은 사실에 따라 행동합니다에서는 모든 CLI + SKILL 결정의 지침이 되는 설계 철학을 탐구할 것입니다. 이는 실패한 쓰기가 되기 전에 오류를 포착하는 품질 게이트인 cli-schema validate부터 시작합니다.

주요 요점

• MCP는 계속 작동합니다—간단한 작업 및 MCP 생태계 통합에 사용하세요.
• CLI + SKILL은 MCP를 보완합니다—검증이 필요한 복잡한 워크플로우에 더 적합합니다.
• 핵심 차이점은 복잡성이 존재하는 위치입니다: 모델 컨텍스트 대 엔지니어링 시스템.
• CLI + SKILL은 검증, 안내, 확인을 통해 모델 추론 부담을 줄입니다.
• CLI는 이제 프로젝트, API, 환경, 테스트 케이스, 시나리오 등을 다룹니다.
• 두 가지 접근 방식 모두 사용 가능합니다—작업 복잡성에 따라 선택하세요.

Apidog을 다운로드하여 단일 작업 공간에서 API를 설계, 목업, 테스트, 문서화하세요. 명령줄 API 테스트, CI 자동화 및 AI 에이전트 워크플로우를 위한 Apidog CLI에 대해 자세히 알아보세요.