Claude 코드에서 Apidog CLI 사용법

Claude Code는 파일을 편집하고, 터미널 명령을 실행하고, 출력을 읽은 뒤 다음 작업을 결정하는 루프로 동작합니다. API 테스트도 이 루프에 넣을 수 있습니다. Apidog에서 만든 테스트 시나리오를 apidog-cli로 실행하면 Claude Code는 단위 테스트처럼 결과와 종료 코드를 확인하고, 실패 시 수정한 뒤 다시 실행할 수 있습니다.

지금 Apidog 사용해 보기

이 글에서는 Claude Code에 Apidog CLI를 연결하는 방법을 다룹니다. 핵심은 저장소의 CLAUDE.md에 실행 명령과 실패 처리 규칙을 추가하는 것입니다.

사전 조건: apidog --version이 정상적으로 버전을 출력하고, apidog login으로 Apidog 계정 인증을 완료해야 합니다. 아직 설치하지 않았다면 AI 코딩 에이전트와 함께 Apidog CLI를 설치하는 방법을 먼저 확인하세요.

어떤 Claude Code를 대상으로 하나요?

여기서 말하는 Claude Code는 Anthropic의 코딩 에이전트 CLI입니다. 터미널 또는 데스크톱 앱에서 실행되며 다음 작업을 수행합니다.

• 저장소 파일 읽기
• 코드 편집
• 셸 명령 실행
• 권한 모드에 따른 실행 승인 요청

일반 Claude 채팅 앱이나 API 호출이 아닙니다. 저장소에서 claude 명령을 실행해 편집과 명령 실행을 수행하는 에이전트를 사용 중이라면 이 설정을 적용할 수 있습니다.

Claude Code는 프로젝트 규칙을 CLAUDE.md에서 읽습니다. Claude Code 슬래시 명령과 프로젝트 규칙 파일을 함께 사용하면, 매번 “API 테스트를 실행해 달라”고 요청하지 않아도 에이전트가 테스트를 작업 흐름에 포함할 수 있습니다.

1단계: CLAUDE.md에 Apidog 실행 규칙 추가

Claude Code는 세션 시작 시 CLAUDE.md를 읽습니다. Codex의 AGENTS.md와 비슷한 역할이지만, Claude Code는 기본적으로 AGENTS.md가 아닌 CLAUDE.md를 사용합니다. Anthropic 문서에서도 Claude Code 메모리 파일 동작을 확인할 수 있습니다.

이미 Codex에 Apidog CLI를 설정했다면 Codex에서 Apidog CLI 설정하기와 동일한 방식이며, 파일 이름만 다릅니다.

저장소 루트에 CLAUDE.md를 만드세요. Claude Code는 다음 위치의 파일도 지원합니다.

• 저장소 루트의 CLAUDE.md
• ./.claude/CLAUDE.md
• 전역 기본값용 ~/.claude/CLAUDE.md

실행 위치부터 상위 디렉터리까지 탐색하며 발견한 CLAUDE.md를 로드하므로, 일반적으로 저장소 루트에 하나를 두면 충분합니다.

다음 블록을 추가하세요.

## Apidog CLI로 API 테스트

이 프로젝트에는 Apidog 테스트 시나리오가 있습니다. API를 검증할 때 다음 명령을 실행하세요.

`apidog run -t <scenario_id> -e <env_id> -r cli`

- 종료 코드가 0이면 모든 어설션이 통과한 것입니다. 0이 아니면 실패한 것이므로 보고서를 확인하고 수정한 뒤 계속하세요.
- 이 장비는 이미 `apidog login`으로 인증되어 있습니다. `--access-token` 플래그를 추가하거나 이 파일에 토큰을 저장하지 마세요.
- 알 수 없는 플래그가 있으면 `apidog run --help`를 실행하고, 출력에 있는 정확한 플래그만 사용하세요.

이 지침을 채팅에 일회성으로 입력하는 대신 CLAUDE.md에 넣어야 하는 이유는 간단합니다.

• 채팅에 입력한 시나리오 ID는 세션이 끝나면 사라집니다.
• CLAUDE.md의 지침은 모든 팀원과 모든 Claude Code 세션에서 재사용됩니다.
• 파일은 세션 시작 시 로드되며 /compact 이후에도 유지됩니다.

2단계: Apidog에서 실제 실행 명령 가져오기

<scenario_id>와 <env_id>를 추측하지 마세요.

1. Apidog에서 테스트 시나리오를 엽니다.
2. CI/CD 탭으로 이동합니다.
3. 생성된 apidog run ... 명령을 복사합니다.
4. 복사한 실제 시나리오 ID와 환경 ID를 CLAUDE.md에 붙여 넣습니다.

예시는 다음과 같습니다.

apidog run -t 123456 -e 789012 -r cli

-r cli 리포터는 각 요청, 어설션 결과, 실패 요약을 터미널에 출력합니다. Claude Code가 다음 작업을 판단하려면 이 출력이 필요하므로 기본 리포터로 유지하는 것이 좋습니다.

자세한 옵션은 전체 Apidog CLI 가이드와 apidog run 명령 참조를 참고하세요.

3단계: Claude Code에서 테스트 실행

저장소 루트에서 Claude Code를 시작합니다.

claude

Claude Code는 시작할 때 CLAUDE.md를 로드합니다. 이후 API에 영향을 주는 변경을 요청하거나, 직접 테스트 실행을 요청하세요.

예를 들면 다음과 같이 요청할 수 있습니다.

결제 응답 핸들러를 수정하고, 완료 후 CLAUDE.md에 정의된 Apidog 테스트를 실행해 주세요.

Claude Code는 CLAUDE.md에 정의된 apidog run 명령을 실행해야 합니다.

권한 설정

기본 모드에서는 Claude Code가 처음 실행하는 셸 명령에 대해 승인을 요청할 수 있습니다. apidog run 프롬프트가 나타나면 명령을 검토한 후 승인하세요.

반복 승인 없이 실행하려면 다음 중 하나를 사용합니다.

• 세션에서 /permissions 실행
• .claude/settings.json에 Bash(apidog run *) 허용 규칙 추가

스테이징 환경에 대해 읽기 전용으로 동작하는 테스트 시나리오는 허용 목록에 추가하기 적합합니다.

--dangerously-skip-permissions는 모든 권한 프롬프트를 건너뛰므로 무인 CI 실행에는 사용할 수 있지만, 일상적인 로컬 개발 환경에서는 권장하지 않습니다.

4단계: Claude Code가 읽을 수 있는 보고서 만들기

실패한 실행의 원인은 보고서에 있습니다. -r cli를 사용하면 Claude Code는 터미널에서 다음 정보를 읽을 수 있습니다.

• 실행된 요청
• 각 어설션 결과
• 예상 값과 실제 값
• 실패한 상태 코드 또는 필드

브라우저에서 확인하거나 팀과 공유할 HTML 보고서도 필요하다면 html 리포터를 추가하세요.

apidog run -t <scenario_id> -e <env_id> -r cli,html

html 리포터는 ./apidog-reports에 자체 포함형 보고서를 생성합니다. 단, Claude Code가 즉시 결과를 읽을 수 있도록 cli 리포터는 반드시 함께 유지하세요.

JUnit 등 CI 대시보드용 리포터는 Apidog CLI 테스트 보고서에서 확인할 수 있습니다.

Claude Code의 편집-테스트-수정 루프에 넣기

설정의 핵심은 단순히 테스트를 한 번 실행하는 것이 아닙니다. Claude Code가 코드 변경 후 스스로 다음 흐름을 수행하도록 만드는 것입니다.

1. 핸들러, 서비스 또는 API 응답 코드를 수정합니다.
2. apidog run을 실행합니다.
3. 종료 코드와 CLI 출력을 확인합니다.
4. 성공하면 다음 작업으로 진행합니다.
5. 실패하면 어설션 실패 내용을 분석합니다.
6. 코드를 수정하고 다시 실행합니다.

예를 들어 결제 API 응답에서 필드 이름을 바꿨다면, Claude Code는 테스트 결과에서 누락된 필드나 잘못된 상태 코드를 확인할 수 있습니다. 이후 수정하고 같은 시나리오를 다시 실행해 검증합니다.

이 방식은 에이전트에 작업을 위임하되 결과는 테스트로 검증하는 구조입니다. 시나리오는 계속 Apidog UI에서 관리하고, 에이전트는 CLI를 통해 실행과 결과 판독을 담당합니다.

관련 워크플로우는 AI 에이전트를 API 테스트에 사용하는 방법과 Apidog AI 테스트 하니스도 참고하세요.

Claude Code가 실제로 CLI를 실행했는지 확인하는 방법

에이전트의 “테스트를 통과했습니다”라는 요약만 신뢰하지 마세요. 다음 세 가지를 확인하세요.

1. 실제 명령 실행 여부 확인

Claude Code는 실행한 명령과 출력을 인라인으로 보여줍니다. 다음과 같은 실제 명령이 표시되어야 합니다.

apidog run -t <scenario_id> -e <env_id> -r cli

명령과 원시 출력이 보이지 않는다면, 테스트가 실행되지 않았을 수 있습니다. 다시 실행하고 전체 출력을 보여 달라고 요청하세요.

2. 종료 코드 확인

Claude Code에 다음처럼 직접 물어볼 수 있습니다.

방금 실행한 apidog run 명령의 종료 코드를 알려 주세요.

apidog run은 다음 규칙으로 종료됩니다.

종료 코드	의미
0	모든 어설션 통과
0 이외	하나 이상의 테스트 또는 어설션 실패

설명과 종료 코드가 다르면 종료 코드를 기준으로 판단하세요.

3. 실제 시나리오 ID 사용 여부 확인

다음과 같은 오류가 나온다면 ID가 잘못되었거나 임의 값이 사용된 것입니다.

Scenario not found

이 경우 다음 값을 다시 대조하세요.

• CLAUDE.md의 -t <scenario_id>
• CLAUDE.md의 -e <env_id>
• Apidog의 CI/CD 탭에서 생성한 명령

Apidog가 생성한 명령을 기준으로 CLAUDE.md를 업데이트하세요.

선택 사항: Apidog MCP 서버 연결

CLAUDE.md와 apidog run만으로도 코드 변경 후 테스트를 실행하는 흐름을 만들 수 있습니다.

추가로 MCP 서버를 연결하면 Claude Code가 코드를 작성하기 전에 API 사양을 읽을 수 있습니다. 즉, CLI는 테스트 실행을 담당하고 MCP는 API 스키마와 사양을 에이전트 컨텍스트에 제공합니다.

Claude Code는 Model Context Protocol(MCP)을 지원합니다. claude mcp add ... 사용법을 사용하거나, 프로젝트 루트의 .mcp.json을 커밋한 뒤 --scope project를 선택해 팀 전체 설정으로 관리할 수 있습니다.

Apidog MCP 서버를 연결하면 Claude Code가 API 사양을 읽으며 구현할 수 있습니다.

역할은 다음처럼 분리됩니다.

• Apidog CLI: 테스트 실행 및 종료 코드 반환
• Apidog MCP 서버: API 사양과 스키마 제공
• Claude Code: 코드 수정, 결과 분석, 재실행

자주 발생하는 문제 해결

CLAUDE.md 규칙을 무시하는 경우

Claude Code가 일반 명령만 실행하거나 아무 테스트도 실행하지 않는다면 파일이 로드되지 않았을 수 있습니다.

다음을 확인하세요.

1. 파일 이름이 정확히 CLAUDE.md인지 확인합니다.
2. 파일이 저장소 루트 또는 현재 디렉터리의 상위 경로에 있는지 확인합니다.
3. Claude Code 세션에서 /memory를 실행해 실제로 로드된 파일 목록을 확인합니다.
4. 파일을 추가하거나 수정했다면 Claude Code 세션을 재시작합니다.

--access-token을 추가하려는 경우

Claude Code가 --access-token을 추가하려 한다면 공개 예시를 잘못 적용한 것일 수 있습니다.

CLAUDE.md에 다음 규칙이 포함되어 있는지 확인하세요.

이 장비는 이미 `apidog login`으로 인증되어 있습니다.
`--access-token`을 추가하지 말고 토큰을 파일에 기록하지 마세요.

실제 토큰을 CLAUDE.md에 저장하면 안 됩니다. 인증 절차는 Apidog CLI 인증에서 확인하세요.

존재하지 않는 플래그를 사용하는 경우

다음 오류는 설치된 CLI 버전에 없는 옵션을 사용했다는 의미입니다.

unknown option

이 경우 Claude Code가 추측하지 않도록 다음 명령을 먼저 실행하게 하세요.

apidog run --help

출력에 표시된 플래그만 사용하면 현재 설치된 버전에 맞는 옵션을 적용할 수 있습니다.

실패한 실행을 통과로 보고하는 경우

가장 중요한 기준은 종료 코드입니다.

• 요약이 “통과”라고 해도 종료 코드가 0이 아니면 실패입니다.
• Claude Code가 실패한 어설션을 확인하고 수정한 뒤 재실행하도록 CLAUDE.md에 명시하세요.

일상적인 에이전트 작업을 테스트 루프로 전환하기

설정은 간단합니다.

1. 설치 가이드에 따라 apidog-cli를 설치합니다.
2. Apidog에서 테스트 시나리오와 환경을 준비합니다.
3. CI/CD 탭에서 생성한 apidog run 명령을 복사합니다.
4. 저장소의 CLAUDE.md에 Apidog 실행 규칙을 추가합니다.
5. Claude Code가 코드 변경 후 테스트를 실행하고 종료 코드를 확인하도록 합니다.

이제 API 문제를 배포 후에 발견하는 대신, Claude Code가 변경을 수행하는 동안 발견할 수 있습니다.

테스트는 계속 Apidog에서 시각적으로 설계하고 관리하세요. Claude Code는 저장소 규칙에 따라 해당 시나리오를 CLI로 실행합니다.

Apidog 다운로드 후 테스트 시나리오 하나를 만들고, 실행 명령을 CLAUDE.md에 추가해 보세요. 이후 CI에서도 같은 명령을 실행하려면 GitHub Actions의 Apidog CLI에서 시크릿, 리포터, 종료 코드 게이팅 설정을 확인할 수 있습니다.