황금률: CLI는 사실을 생성하고, 모델은 사실을 기반으로 작동한다

Apidog이 API 테스트 및 API 라이프사이클 관리를 위한 명령줄 도구인 Apidog CLI를 개발한 과정을 공유하는 10부작 시리즈입니다. 순서대로 읽거나 관심 있는 게시물로 바로 이동하세요:

모델이 모든 규칙을 외우게 하지 마세요. 규칙이 적절한 곳에서 실행되도록 하세요. cli-schema validate는 스키마를 지식에서 품질 게이트로 전환합니다.

핵심 원칙: 규칙이 적절한 곳에서 실행되도록 하라.

우리는 경험을 통해 하나의 핵심 원칙을 추출했습니다:

모델이 모든 규칙을 외우게 하지 마세요. 규칙이 적절한 곳에서 실행되도록 하세요.

이는 에이전트 평가에서 얻은 교훈과 유사합니다:

Apidog CLI + SKILL에서는:

CLI가 구조의 유효성을 검사하도록 하고, 에이전트가 콘텐츠를 생성하도록 하세요.

모델 메모리의 문제점

AI 에이전트가 Apidog 리소스를 생성하거나 업데이트하는 데 도움을 줄 때, 위험한 부분은 단순히 콘텐츠를 생성하는 것만이 아닙니다.

위험한 부분은 충분한 구조나 검증 없이 생성된 콘텐츠를 실제 프로젝트에 작성하는 것입니다.

Apidog 리소스는 구조화되어 있습니다. 테스트 케이스 또는 테스트 시나리오에 포함되는 내용을 고려해 보세요:

에이전트가 구조를 추측하면:

• 잘못된 필드 이름 → 쓰기 실패
• 잘못된 열거형 값 → 서버 거부
• 필수 필드 누락 → 불완전한 리소스
• 잘못된 유형 → UI 표시 문제
• 잘못된 중첩 → 테스트가 예상대로 작동하지 않음

cli-schema validate: 품질 게이트

우리 원칙의 가장 직접적인 구현은 cli-schema validate입니다.

apidog cli-schema validate test-scenario-update --file ./scenario-update.json

에이전트가 테스트 시나리오를 작성하거나 업데이트할 때, AI가 복잡한 단계 구조를 생성하도록 하는 것은 오류가 발생하기 매우 쉽습니다.

`validate` 명령어는:

• 필드 이름을 확인합니다.
• 구조적 유효성을 검사합니다.
• 열거형 값의 유효성을 검증합니다.
• 유형 제약 조건을 검증합니다.

모든 것이 쓰기 요청을 시작하기 전에 이루어집니다.

cli-schema가 포착하는 일반적인 오류

다음은 에이전트가 일반적으로 저지르는 오류 중 cli-schema validate가 잡아내는 실제 예시입니다:

이는 이론적인 것이 아닙니다. 우리는 실제 에이전트 상호작용을 통해 이를 발견했습니다.

각 오류는 다음을 유발할 수 있습니다:

• 쓰기 요청 실패
• API 오류 응답
• 무엇이 잘못되었는지에 대한 에이전트의 혼란
• 여러 번의 재시도
• 반복적인 호출로 인한 토큰 낭비

cli-schema validate를 사용하면 이러한 오류가 네트워크 호출 전에 로컬에서 포착됩니다.

설계 철학

대안을 고려해 봅시다:

대안 1: 규칙을 프롬프트에 작성하기

모든 필드 규칙을 에이전트의 프롬프트에 작성한다면:

• 모든 필드 이름이 문서화됨
• 모든 열거형 값이 나열됨
• 모든 유형 제약 조건이 설명됨
• 모든 중첩 구조가 설명됨

결과: 엄청난 컨텍스트 부담.

포괄적인 테스트 시나리오 스키마는 쉽게 5,000개 이상의 설명 토큰을 필요로 할 수 있습니다. 이는 대부분의 규칙이 관련이 없는 경우에도 모델이 모든 작업에 대해 전달해야 하는 컨텍스트입니다.

대안 2: 모델 메모리에 의존하기

모델이 올바른 구조를 "알고" 있다고 가정한다면:

• 일부 API 패턴으로 훈련된 모델
• 하지만 Apidog 스키마에 특화되지 않음
• 필드 이름은 제품마다 다름
• 열거형 값은 제품별로 다름

결과: 높은 오류율.

모델은 Apidog 고유의 규칙을 완벽하게 기억하지 못합니다. 모델은 추측할 것이고, 그 추측은 틀릴 것입니다.

더 나은 접근 방식: 로컬에서 유효성 검사하기

에이전트가 초안을 생성하도록 하고, CLI가 쓰기 전에 유효성 검사를 실행하도록 하세요.

# 에이전트가 JSON을 생성합니다.
# (에이전트가 모든 규칙을 외울 필요는 없습니다)

# CLI가 유효성을 검사합니다.
apidog cli-schema validate test-case-create --file ./test-case-create.json

# 오류가 있다면 CLI가 특정 오류를 출력합니다.
# 에이전트가 오류를 기반으로 조정합니다.

# 유효한 쓰기만 진행됩니다.
apidog test-case create --project <projectId> --file ./test-case-create.json

스키마 변환

cli-schema validate는 스키마의 의미를 변환합니다:

문제는 무의미한 왕복 네트워크 요청으로 소모되지 않습니다.

품질 검사는 로컬 명령을 통해 완료됩니다.

실제 예시

실제 워크플로우를 살펴보겠습니다:

# 에이전트가 엔드포인트를 읽습니다.
apidog endpoint get <endpointId> --project <projectId>

# 에이전트가 테스트 케이스 JSON을 생성합니다.
# (./test-case-create.json 파일 생성)

# 작성 전에 유효성 검사
apidog cli-schema validate test-case-create --file ./test-case-create.json

유효성 검사가 통과하면:

apidog test-case create --project <projectId> --file ./test-case-create.json

유효성 검사가 실패하면:

Error: Field "assertions[0].comparator" has invalid value "contains"
Valid values: equal, not_equal, greater, less, include, not_include, exists, not_exists

Error: Field "extractors[0].type" has invalid value "global"
Valid values: globals, environment, collection, local

Suggestion: Fix these fields and re-validate before writing.

에이전트는:

1. 특정 오류를 읽습니다.
2. 무엇이 잘못되었는지 정확히 이해합니다.
3. JSON 파일을 조정합니다.
4. 유효성 검사를 다시 실행합니다.
5. 유효할 때만 진행합니다.

쓰기 실패 없음. 혼란스러운 재시도 없음. 토큰 낭비 없음.

더 넓은 교훈

이 원칙은 유효성 검사 이상으로 확장됩니다.

결정론적 규칙 → 엔지니어링 시스템

의미론적 판단 → 에이전트

다음은 무엇인가요?

이제 유효성 검사 원칙을 확립했으므로, 다음 질문은 다음과 같습니다:

유효성 검사 후, CLI는 에이전트를 다음 단계로 어떻게 안내할까요?

4부, agentHints: CLI가 에이전트와 대화하도록 가르치기에서는 다음 단계 제안과 함께 구조화된 출력을 통해 CLI가 명령어 실행자에서 워크플로우 내비게이터로 어떻게 변모하는지 살펴보겠습니다.

핵심 요점

• 핵심 원칙: 규칙은 컨텍스트가 아닌 실행에 속합니다.
• cli-schema validate는 쓰기 전 품질 게이트입니다.
• 일반적인 오류: 잘못된 필드 이름, 잘못된 열거형, 잘못된 유형
• 유효성 검사는 로컬에서 오류를 포착하여 네트워크 왕복을 절약합니다.
• 스키마는 "외워야 할 지식"에서 "통과해야 할 게이트"로 변환됩니다.
• 결정론적 규칙 → 엔지니어링; 의미론적 판단 → 에이전트

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