기술: 코드형 해운 운영 경험

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

SKILL은 단순한 명령어 참조가 아닙니다. 이는 AI 에이전트를 위한 운영 가이드입니다: 언제 명령어를 사용해야 하는지, 어떤 명령어가 먼저 와야 하는지, 어떤 필드를 추측해서는 안 되는지, 언제 검증해야 하는지, 언제 다시 읽어야 하는지 등입니다.

CLI만으로는 충분하지 않습니다

CLI 명령어는 에이전트에게 실행 능력을 부여합니다.

그러나 판단 없는 능력은 문제로 이어집니다:

에이전트는 명령어 그 이상을 필요로 합니다. 그들에게는 운영 판단이 필요합니다.

SKILL이란 무엇인가?

SKILL은 AI 에이전트를 위해 작성된 운영 가이드입니다.

이는 다음이 아닙니다:

• 단순한 명령어 목록
• 참조 매뉴얼
• 도움말 페이지

이는 다음입니다:

SKILL은 에이전트에게 운영 판단을 제공합니다.

설치

SKILL은 Apidog CLI의 동반자입니다:

# AI 에이전트를 위한 SKILL 설치
apidog skill install

이는 에이전트가 다음을 이해하는 데 도움이 되는 8가지 동반 SKILL을 설치합니다:

• CLI 명령어 의미론
• 리소스 구조
• 작업 워크플로우
• 오류 처리
• 검증 패턴

SKILL이 중요한 이유: 숨겨진 워크플로우

에이전트는 여전히 작업이 비즈니스 간 실행 흐름으로 어떻게 분해되어야 하는지 알아야 합니다.

이러한 경험은 다음이 될 수 없습니다:

• 도구 설명에 포괄적으로 작성 (너무 많은 컨텍스트를 소비할 것임)
• 채팅 컨텍스트에 흩어져 있음 (세션 간에 손실될 것임)
• 모델에 의해 암기됨 (제품별 지식이며 일반 지식이 아님)

숨겨진 워크플로우와 "비즈니스 함정"은 명시적인 지침을 필요로 합니다.

예시: 테스트 시나리오 유지 관리

복잡한 테스트 시나리오를 유지 관리하는 것을 고려해 보세요.

잘못된 접근 방식 (에이전트가 처음부터 수동으로 작성):

에이전트: "테스트 시나리오 구조를 수동으로 만들겠습니다"
에이전트: 어설션, 추출기, 프로세서가 포함된 완전한 단계 배열을 작성합니다
결과: 필드 오류, 잘못된 비교 연산자, 누락된 필수 필드
CLI: 쓰기를 거부하거나 불완전한 시나리오를 생성합니다

올바른 접근 방식 (SKILL에 인코딩됨):

SKILL은 단순히 "test-scenario update 명령어가 있습니다"라고 말하지 않습니다.

다음과 같이 말합니다:

"복잡한 시나리오는 처음부터 완전한 구조를 수동으로 작성하는 데 적합하지 않습니다. 더 안정적인 경로는 먼저 기존 엔드포인트 또는 케이스 단계를 가져온 다음, 완전한 구조를 다시 읽고, 마지막으로 로컬 수정 작업을 수행하는 것입니다."

SKILL 지침 뒤의 명령어

다음은 SKILL이 에이전트에게 사용하도록 안내하는 실제 명령어입니다:

# 1단계: 엔드포인트에서 단계 가져오기
apidog test-scenario import-steps  --project  \
  --source endpoint --ids  --sync manual

# 2단계: 전체 세부 정보로 다시 읽기
apidog test-scenario get  --project  \
  --with-case-detail

# 3단계: 특정 부분 업데이트 (에이전트가 업데이트 JSON 생성)

# 4단계: 업데이트 전에 검증
apidog cli-schema validate test-scenario-update --file ./scenario-update.json

# 5단계: 업데이트 실행
apidog test-scenario update  --project  \
  --file ./scenario-update.json

# 6단계: 검증 실행
apidog run --project  --test-scenario 

SKILL은 에이전트에게 각 명령어를 언제 사용해야 하는지 그리고 이유를 알려줍니다.

핵심 통찰: get--with-case-detail

SKILL은 다음을 강조합니다:

"단계 내의 케이스를 상상하는 대신 get--with-case-detail을 사용하여 실제 구조를 얻으세요."

이것이 중요한 이유:

실제 구조를 얻는 것은 상상에 기반한 업데이트를 방지합니다.

진화 가능성: SKILL은 변경될 수 있습니다

Apidog SKILL은 진화 가능하고 버전 관리 가능한 운영 경험입니다.

이것이 중요한 이유

작동 방식

에이전트는 SKILL에 대한 쓰기 권한을 부여받습니다.

SKILL이 뒤처지거나 사용하기 어려워지는 경우:

• 에이전트가 수정할 수 있습니다
• 에이전트가 개선 사항을 제안할 수 있습니다
• SKILL은 사용을 통해 진화합니다

SKILL은 고정된 문서가 아닙니다. 그것은 살아있는 운영 코드입니다.

호환성 계층

우리는 실제 버그를 통해 이것을 배웠습니다:

발견된 문제:

일부 시나리오 단계에서 2차 업데이트 시 외부 단계는 성공적으로 업데이트되었지만, 내부 HTTP 케이스는 올바르게 업데이트되지 않았습니다.

근본 원인:

• 내부 케이스 업데이트 마커에 특별한 처리가 필요했습니다
• 에이전트는 이 마커에 대해 알지 못했습니다
• 제품 의미론은 특정 플래그를 요구했습니다

해결책:

• 호환성 로직이 CLI에 포함되었습니다
• CLI는 내부 마커를 자동으로 처리합니다
• 사용자와 에이전트는 내부 세부 사항을 알 필요가 없습니다

제약 조건의 의미는 SKILL에 계층화되어 있습니다:

SKILL은 에이전트에게 올바른 명령어를 사용하도록 지시합니다. CLI는 해당 명령어 뒤의 제품 의미론을 처리합니다. 에이전트는 내부 마커를 이해할 필요가 없습니다.

온디맨드 로딩

SKILL은 cli-schema와 동일한 원칙을 따릅니다:

복잡성은 모델에 완전히 노출되는 것이 아니라 실행과 문서화에 의해 흡수되어야 합니다.

SKILL 접근 방식:

• 에이전트가 요청 시 SKILL을 활성화합니다
• 작업 유형이 식별될 때 SKILL이 로드됩니다
• 관련 워크플로우 지침만 컨텍스트에 들어갑니다

SKILL 대 문서화

8가지 동반 SKILL

Apidog는 8가지 동반 SKILL을 제공합니다:

각 SKILL은 다음을 포함합니다:

• 작업 유형 식별
• 명령어 순서 지침
• 필드 안전 경계
• 검증 체크포인트
• 검증 패턴

다음 단계

이제 세 가지 핵심 구성 요소를 모두 확립했습니다:

• cli-schema validate — 품질 게이트
• agentHints — 다음 단계 탐색
• SKILL — 워크플로우 판단

다음 질문은 다음과 같습니다:

이것이 실제로 작동할까요? 수치는 어떻게 될까요?

6부, 숫자는 거짓말하지 않습니다: 도구 호출 30% 감소, 토큰 25% 감소에서 내부 비교를 통한 정량적 결과를 공유하고 절감 효과가 어디서 오는지 설명할 것입니다.

주요 내용

• CLI는 실행 능력을 제공하고, SKILL은 운영 판단을 제공합니다
• SKILL은 명령어 참조가 아닌 운영 가이드입니다
• 숨겨진 워크플로우는 명시적인 지침을 필요로 합니다
• 단계 가져오기 → 다시 읽기 → 로컬에서 업데이트하는 것이 수동 작성보다 안전합니다
• --with-case-detail은 상상에 기반한 업데이트를 방지합니다
• SKILL은 진화 가능합니다 — 에이전트가 수정할 수 있습니다
• CLI는 제품 의미론을 흡수하고, SKILL은 워크플로우를 안내합니다
• 온디맨드 로딩은 컨텍스트 부담을 방지합니다

하나의 워크스페이스에서 API를 설계하고, 모의하고, 테스트하며, 문서화하려면 Apidog를 다운로드하세요. 명령줄 API 테스트, CI 자동화 및 AI 에이전트 워크플로우를 위한 Apidog CLI에 대해 더 자세히 알아보세요.