Claude Code는 루프입니다: 파일을 편집하고, 터미널에서 명령을 실행하고, 출력을 읽고, 다음에 무엇을 할지 결정합니다. 그렇다면 왜 API 테스트는 그 루프에 포함되지 않습니까? API 테스트는 GUI 뒤의 Apidog에 앉아 있다가 누군가가 클릭해야 실행됩니다. 당신의 에이전트는 결코 그들을 건드리지 않습니다.
해결책은 단 하나의 설정 블록입니다. Apidog CLI는 Apidog에서 구축한 테스트 시나리오를 터미널에서 직접 실행하는 npm 패키지인 `apidog-cli`입니다. CLI가 설치되고 Claude Code가 그 존재를 알게 되면, 당신의 에이전트는 단위 테스트를 실행하는 것과 동일한 방식으로 Apidog 시나리오를 실행합니다: 명령을 실행하고, 종료 코드를 읽고, 코드가 빨간색이면 수정합니다.
이 가이드는 일반적인 설치 가이드가 건너뛰는 Claude Code 특정 부분들을 다룹니다: `CLAUDE.md`에 추가할 정확한 줄, Claude Code가 권한 모델 하에서 `apidog run`을 실행하는 방법, 그리고 자체 편집-테스트-수정 루프 내에서 결과를 읽는 방법입니다.
아직 CLI를 설치하지 않았다면, 먼저 설치하십시오. AI 코딩 에이전트와 함께 Apidog CLI를 설치하는 방법은 npm 설치와 첫 실행 과정을 에이전트가 입력하는 방식으로 안내합니다. 이 문서는 `apidog --version`이 숫자를 출력하고 Apidog 계정이 인증되었다고 가정합니다.
버튼
어떤 Claude Code에 대한 내용인가요?
이것은 Anthropic의 코딩 에이전트인 Claude Code CLI로, 터미널(또는 데스크톱 앱)에서 실행됩니다. 이는 저장소를 읽고, 파일을 편집하고, 셸 명령을 실행하며, 사용자의 권한 모드에 따라 승인을 요청합니다. 이는 Claude 채팅 앱이 아니며 일반 API 호출도 아닙니다. 만약 저장소에서 `claude`를 실행하여 편집 및 명령 실행을 제안하는 대화형 에이전트를 만난다면, 제대로 찾아오신 것입니다. 터미널용으로 작성하는 명령은 Claude Code 슬래시 명령 및 해당 규칙 파일에 있으며, Apidog CLI는 바로 그 규칙 파일에 속합니다.
이 구별은 중요합니다. 왜냐하면 Claude Code는 프로젝트 규칙을 학습하는 자체적인 방식을 가지고 있으며, 이 메커니즘은 일회성 "내 테스트 실행"을 Claude가 스스로 활용하는 것으로 전환시키기 때문입니다. 그 메커니즘이 바로 `CLAUDE.md`입니다.
1단계: Apidog 블록을 CLAUDE.md에 추가
Claude Code는 모든 세션 시작 시 `CLAUDE.md` 파일을 읽습니다. 이는 Codex의 `AGENTS.md`에 직접적으로 대응됩니다. 사실 Anthropic의 문서는 Claude Code가 `AGENTS.md`가 아닌 `CLAUDE.md`를 읽는다고 명시하며, 다른 에이전트용으로 `AGENTS.md`를 가지고 있다면 `@AGENTS.md`를 사용하여 기존 파일을 가져올 것을 제안합니다. 만약 Codex에서 Apidog CLI를 이미 설정했다면, 이는 파일 이름만 다를 뿐 동일한 개념입니다.
저장소 루트에 `CLAUDE.md`를 배치하십시오 (Claude Code는 `./.claude/CLAUDE.md`와 개인 기본값을 위한 전역 `~/.claude/CLAUDE.md`도 허용합니다). Claude Code는 실행된 위치에서 디렉토리 트리를 거슬러 올라가서 발견하는 모든 `CLAUDE.md`를 로드하므로, 저장소 루트의 단일 파일이 모든 세션에 적용됩니다. 다음과 같은 짧은 블록을 추가하십시오:
## API testing with Apidog CLI
This project has Apidog test scenarios. To check the API, run:
`apidog run -t <scenario_id> -e <env_id> -r cli`
- Exit code 0 means every assertion passed. Non-zero means something failed; open the report and fix it before moving on.
- The machine is already authenticated via `apidog login`. Never add an `--access-token` flag and never put a token in this file.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
이것이 바로 채팅에서 언급하는 대신 `CLAUDE.md`에 CLI를 작성하는 이유입니다. 세션에 입력된 시나리오 ID는 해당 세션이 종료되면 사라집니다. `CLAUDE.md`에 있는 시나리오 ID는 이제부터 모든 팀원과 모든 Claude Code 실행을 위해 존재합니다. 파일은 시작 시 완전히 로드되며 `/compact` 명령에도 유지되므로, 지시사항은 전체 세션 동안 활성화 상태를 유지합니다.
2단계: Apidog에서 명령 가져오기
해당 블록의 `<scenario_id>`와 `<env_id>`는 추측하는 값이 아닙니다. Apidog에서 테스트 시나리오를 열고 CI/CD 탭으로 이동하여 생성된 `apidog run ...` 명령을 복사하십시오. 여기에는 실제 시나리오 ID, 환경 ID, 그리고 `-r cli` 리포터가 이미 채워져 있습니다. 해당 정확한 ID를 `CLAUDE.md` 블록에 붙여넣으십시오.
`-r cli` 리포터는 터미널에 단계별 결과와 요약을 바로 출력하는데, 이는 Claude Code가 다음 단계를 결정하기 위해 읽는 출력과 정확히 일치합니다. 모든 플래그에 대한 자세한 내용은 전체 Apidog CLI 가이드 및 apidog run 명령 참조를 참조하십시오.
3단계: Claude Code가 테스트를 실행하도록 하기
블록을 추가한 후, 저장소에서 Claude Code를 시작하십시오:
claude
Claude Code는 시작 시 `CLAUDE.md`를 로드하므로, CLI가 있음을 이미 알고 있습니다. API에 영향을 주는 변경을 하거나, 단순히 검사를 실행하도록 요청하십시오. Claude Code는 `CLAUDE.md`에 있는 `apidog run` 명령을 실행합니다.
여기서는 권한 모델이 중요합니다. 기본 모드에서 Claude Code는 승인된 적 없는 셸 명령을 실행하기 전에 질문합니다. 프롬프트가 나타나면 `apidog run` 명령을 승인하십시오. 신뢰하는 명령에 대해 더 이상 질문을 받지 않으려면, CLI가 프롬프트 없이 실행되도록 권한 규칙을 추가하십시오: 세션 내에서 /permissions를 실행하거나 .claude/settings.json에 Bash(apidog run *)에 대한 허용 규칙을 추가하십시오. 스테이징 환경에 대한 읽기 전용 테스트 시나리오는 허용 목록에 추가하기에 안전한 명령입니다. 무인 실행을 위해서는 프롬프트를 완전히 건너뛰는 --dangerously-skip-permissions가 있지만, 이는 CI용으로 보관하고 일상적인 사용에는 권장하지 않습니다.
실행이 진행되고 Claude Code가 성공을 주장하는 문장뿐만 아니라 요약과 종료 코드 모두를 보고하는 것을 보고 싶을 것입니다.
4단계: Claude Code 내에서 보고서 읽기
실행이 실패하면 보고서에 답이 있습니다. `-r cli`를 사용하면 Claude Code는 터미널에서 읽기 쉬운 상세 분석을 얻습니다: 각 요청, 각 어설션, 그리고 예상 값과 실제 값을 통해 어떤 것이 실패했는지. 실패한 어설션은 정확한 필드 또는 상태 코드를 명시하며, 이는 일반적으로 Claude Code가 수정 사항을 찾는 데 충분합니다.
브라우저에서 열거나 팀원에게 전달할 수 있는 보고서를 원한다면, HTML 리포터를 추가하십시오:
apidog run -t <scenario_id> -e <env_id> -r cli,html
`html` 리포터는 `./apidog-reports`에 자체 포함된 파일을 작성합니다. Claude Code가 다음 단계를 결정하기 위해 읽는 인라인 출력을 계속 받도록 목록에 `cli`를 유지하십시오. CI 대시보드가 구문 분석하는 JUnit 형식 및 기타 리포터에 대해서는 Apidog CLI 테스트 보고서를 참조하십시오.
Claude Code 자체 루프 내에서 테스트하기
중요한 점은 당신이 요청을 멈추고 `CLAUDE.md`가 지시했기 때문에 Claude Code가 스스로 시나리오를 실행할 때 발생하는 일입니다.
Claude Code가 결제 응답을 생성하는 핸들러를 편집하는 상황을 상상해 보십시오. Claude Code의 루프가 바뀝니다: 코드를 편집하고, 승리를 선언하는 대신, 스테이징 환경에 대해 Apidog 시나리오를 실행하고, 종료 코드를 읽고, 그에 따라 조치합니다. 녹색이면 다음으로 진행합니다. 빨간색이면 보고서를 열고 어떤 어설션이 실패했는지 (상태 코드, 누락된 필드, 잘못된 값) 읽고, 수정 시도를 한 다음 다시 실행합니다. API 테스트는 Claude Code가 이미 단위 테스트를 실행하는 것과 동일한 편집-테스트-수정 루프의 일부가 됩니다. 당신은 단 하나의 지시를 작성했고 Claude는 그 명령을 이미 작동하는 방식에 통합했습니다.
이것이 바로 모든 에이전트 워크플로우를 안전하게 만드는 위임-검증 모델입니다. Claude Code는 명령을 실행하고 결과를 읽습니다. 당신은 Apidog에서 시각적으로 시나리오를 계속 작성하고 에이전트가 종료 코드를 정확하게 읽는지 확인합니다. 더 넓은 패턴에 대해서는 AI 에이전트를 API 테스트에 사용하는 방법 및 Apidog AI 테스트 하니스를 참조하십시오.
Claude Code가 실제로 CLI를 실행하는지 확인
에이전트는 얻지 못한 성공을 보고하며, Claude Code도 예외는 아닙니다. 문제를 자주 발견하는 순서대로 세 가지 확인 사항이 있습니다.
첫째, 명령이 실제로 실행되었는지 확인하십시오. Claude Code는 실행된 명령과 그 출력을 인라인으로 보여줍니다. 리터럴 apidog run ... 줄과 그 아래 결과를 찾으십시오. 만약 Claude가 테스트를 실행했다고 말하지만 당신이 명령을 보지 못했다면, 그것은 결코 하지 않은 일을 요약한 것입니다. 다시 실행하고 원시 출력을 보여달라고 요청하십시오.
둘째, 중요한 종료 코드를 확인하십시오. 직접 물어보세요: "그 apidog run 명령의 종료 코드는 무엇이었습니까?" apidog run은 모든 어설션이 통과하면 0으로 종료되고, 뭔가 실패하면 0이 아닌 값으로 종료됩니다. 이 단일 동작은 Claude Code 또는 파이프라인이 실행을 깔끔한 게이트로 취급하도록 합니다. Claude의 설명이 "테스트 통과"라고 하지만 종료 코드가 0이 아닌 경우, 종료 코드가 옳습니다.
셋째, 실제 시나리오를 사용했는지 확인하십시오. 실행이 "시나리오를 찾을 수 없음"으로 실패하면, Claude가 ID를 만들었거나 잘못 기억했을 수 있습니다. CLAUDE.md의 -t 및 -e 값과 Apidog가 CI/CD 탭에서 생성한 명령을 다시 확인하십시오. CLAUDE.md의 ID가 진실입니다.
선택 사항: Apidog MCP 서버 연결
`CLAUDE.md`에서 `apidog run`을 실행하는 것으로 대부분의 필요한 작업을 처리할 수 있습니다. 한 단계 더 나아가려면, MCP 서버를 연결하여 Claude Code가 코드를 작성하는 동안 API 사양을 읽을 수 있도록 하고, 사후 테스트만 하는 것이 아니게 하십시오.
Claude Code는 모델 컨텍스트 프로토콜(Model Context Protocol)을 지원합니다. claude mcp add ...를 사용하여 서버를 추가하거나, 프로젝트 루트에 .mcp.json 파일을 커밋하고 --scope project를 선택하여 전체 팀이 사용할 수 있도록 할 수 있습니다. Apidog MCP 서버는 MCP를 통해 API 사양을 노출하므로, Claude는 코딩할 때 스키마를 읽습니다. 이를 분업으로 생각하십시오: CLI는 테스트를 실행하고, MCP는 에이전트에게 사양을 제공합니다.
Claude Code가 잘못했을 때
설정 중에 몇 가지 오류가 자주 나타납니다.
CLAUDE.md 블록을 무시합니다. Claude가 일반 명령을 실행하거나 아무것도 실행하지 않는다면, 블록이 로드되지 않았을 수 있습니다. 파일 이름이 정확히 CLAUDE.md이고 저장소 루트 또는 현재 디렉토리의 상위 디렉토리에 있는지 확인하십시오. 세션 내에서 /memory를 실행하여 Claude가 실제로 로드한 파일을 나열하십시오. 당신의 파일이 없다면 Claude는 그것을 볼 수 없습니다. 세션을 다시 시작하면 새로 읽기를 강제합니다.
그래도 액세스 토큰을 전달합니다. Claude가 --access-token을 추가하려고 한다면, 공개 예시에서 추측하는 것입니다. 블록은 이미 `apidog login`을 통해 기기가 인증되었으므로 그렇게 하지 말라고 지시하고 있습니다. 해당 줄을 강화하고, 실제 토큰을 CLAUDE.md에 절대 넣지 마십시오. 기기가 한 번 인증되는 방법에 대해서는 Apidog CLI 인증을 참조하십시오.
플래그를 임의로 만듭니다. "알 수 없는 옵션" 오류는 Claude가 당신의 버전에는 없는 플래그를 추측했다는 의미입니다. Claude에게 apidog run --help를 실행하고 거기서 정확한 플래그를 복사하도록 지시하십시오. 이 플래그는 설치된 버전에 항상 올바릅니다.
실패한 실행에 대해 통과로 보고합니다. 가장 비용이 많이 드는 문제이며, 종료 코드 규칙이 CLAUDE.md와 확인 단계에 있는 이유입니다. 요약과 종료 코드가 일치하지 않을 때는 종료 코드가 우선합니다.
일상 에이전트에서 테스트 루프로
그것이 설정 과정입니다. 설치 가이드에 따라 `apidog-cli`를 한 번 설치하고, 저장소의 `CLAUDE.md`에 짧은 Apidog 블록을 추가하면, Claude Code는 코드를 편집하는 데 이미 사용하는 동일한 루프 내에서 API 테스트를 실행하고 결과를 읽는 방법을 알게 됩니다. 손상된 엔드포인트는 배포된 후가 아니라 Claude가 변경 작업을 진행하는 동안 감지됩니다.
GUI 뒤의 테스트는 사람이 클릭할 때 실행됩니다. 한 줄짜리 명령은 Claude가 결정할 때마다 실행됩니다. 당신은 Apidog에서 시각적으로 시나리오를 계속 구축하고, 당신의 에이전트는 당신이 보지 않는 곳에서 시나리오를 실행합니다. Apidog를 다운로드하고, 하나의 시나리오를 만들고, `apidog run` 명령을 `CLAUDE.md`에 추가한 다음, Claude가 다음 변경에서 이를 어떻게 처리하는지 지켜보십시오. Claude 없이 파이프라인에서 동일한 명령을 실행할 준비가 되면, GitHub Actions의 Apidog CLI에서 비밀, 리포터, 종료 코드 게이팅을 다룹니다.