DEV Community

Cover image for DeepSeek Harness에서 Apidog CLI 사용법
Rihpig
Rihpig

Posted on Originally published at apidog.com

DeepSeek Harness에서 Apidog CLI 사용법

DeepSeek Harness는 하나의 루프로 동작합니다. 에이전트는 작업 공간을 읽고, 파일을 편집하고, bash 도구로 명령을 실행한 뒤, 출력에 따라 다음 작업을 결정합니다. 그렇다면 API 테스트도 이 루프에 포함되어야 합니다. GUI에서 누군가 직접 클릭해야 하는 Apidog 테스트 대신, CLI로 시나리오를 실행하면 에이전트가 단위 테스트와 같은 방식으로 결과를 읽고 실패한 코드를 수정할 수 있습니다.

지금 Apidog 사용해 보기

해결책은 간단합니다. npm 패키지인 apidog-cli를 설치하고, Apidog에서 만든 테스트 시나리오를 터미널에서 실행하도록 DeepSeek Harness에 지시하면 됩니다.

에이전트는 다음과 같은 흐름으로 동작합니다.

  1. apidog run 명령 실행
  2. CLI 출력과 종료 코드 확인
  3. 종료 코드가 0이면 다음 작업 진행
  4. 종료 코드가 0이 아니면 실패한 어설션 확인
  5. 코드 수정 후 시나리오 재실행

이 방식은 에이전트가 핸들러 코드와 응답 형식을 반복해서 추론하는 데 쓰는 컨텍스트를 줄입니다. CLI가 “API가 올바른가?”라는 질문을 종료 코드와 테스트 결과로 반환하므로, 에이전트는 분석보다 수정 작업에 집중할 수 있습니다.

이 글에서는 일반 설치 가이드보다 DeepSeek Harness 통합에 초점을 맞춥니다. 아직 CLI를 설치하지 않았다면 먼저 AI 코딩 에이전트로 Apidog CLI를 설치하는 방법을 참고하세요. 아래 내용은 apidog --version이 정상적으로 버전을 출력하고, 현재 컴퓨터가 Apidog에 인증되어 있다는 전제에서 진행합니다.

이 문서가 다루는 DeepSeek Harness

명령줄에서 dsh로 실행하는 DeepSeek Harness는 DeepSeek이 2026년 8월 13일 V4-Pro와 함께 API에 출시한 오픈 소스 에이전트 Harness입니다.

웹 UI에서 프로젝트 디렉터리를 작업 공간으로 선택하면 에이전트는 해당 디렉터리 안에서 파일을 읽고 편집하며 명령을 실행합니다. 활성 권한 정책에 따라 특정 작업은 실행 전 승인이 필요할 수 있습니다.

다만 DeepSeek Harness는 개발자 프리뷰입니다. README에서 호환성을 깨뜨리는 변경이 발생할 수 있다고 경고하므로, 파일 이름이나 설정 키가 동작하지 않을 때는 공식 리포지토리 문서를 다시 확인하세요.

DeepSeek Harness의 전체 개요는 DeepSeek Harness란 무엇인가, 기존 도구와의 비교는 DeepSeek Harness vs Claude Code에서 확인할 수 있습니다.

단계 1: AGENTS.md에 Apidog CLI 명령 추가

DeepSeek Harness는 @deepseek-ai/dsh-agent-instructions 플러그인을 통해 작업 공간 지침을 읽습니다.

설정 카탈로그에 따르면, 지침 로더는 세션 작업 디렉터리에서 프로젝트 루트까지 상위 디렉터리를 탐색하며 다음 파일을 읽습니다.

  1. AGENTS.md
  2. CLAUDE.md — AGENTS.md가 없을 때 대체
  3. AGENTS.local.md
  4. CLAUDE.local.md
  5. $DSH_HOME/AGENTS.md — 기본적으로 ~/.dsh/AGENTS.md

즉, 이미 Codex용 AGENTS.md 또는 Claude Code용 CLAUDE.md를 사용 중이라면 별도 설정 없이 DeepSeek Harness가 해당 파일을 읽을 수 있습니다.

프로젝트의 AGENTS.md에 다음 블록을 추가하세요.

## API testing with the Apidog CLI
- To test the API, run the Apidog scenario. Do not click through the GUI.
- Command: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed. Non-zero means a failure; read the report and fix the code.
- The machine is already authenticated. Never add an --access-token flag and never put a token in this file.
Enter fullscreen mode Exit fullscreen mode

실제 프로젝트에서는 <scenario_id>와 <env_id>를 Apidog에서 발급된 값으로 교체합니다.

예시는 다음과 같습니다.

## API testing with the Apidog CLI
- API 변경 후 반드시 다음 테스트를 실행한다.
- Command: apidog run -t 123456 -e 789012 -r cli
- 종료 코드가 0이면 테스트가 통과한 것이다.
- 종료 코드가 0이 아니면 CLI 보고서를 읽고 실패한 코드와 테스트를 수정한다.
- 이 머신은 이미 인증되어 있다. --access-token을 추가하거나 토큰을 이 파일에 기록하지 않는다.
Enter fullscreen mode Exit fullscreen mode

이 규칙을 채팅 메시지가 아니라 리포지토리의 AGENTS.md에 넣는 것이 중요합니다. 세션 채팅에 입력한 시나리오 ID는 세션 종료 후 사라지지만, 리포지토리에 기록한 명령은 팀원이 프로젝트를 복제하거나 새 세션을 시작해도 유지됩니다.

여러 프로젝트에서 공통 규칙을 사용한다면 ~/.dsh/AGENTS.md에 다음과 같은 전역 지침을 둘 수 있습니다.

- API 변경이 있으면 프로젝트에 정의된 apidog run 명령을 실행한다.
- 테스트 실패 시 종료 코드와 실패한 어설션을 확인한 뒤 코드를 수정한다.
Enter fullscreen mode Exit fullscreen mode

프로젝트별 AGENTS.md에는 실제 시나리오 및 환경 ID를 기록하세요.

단계 2: Apidog에서 실행 명령 복사

시나리오 ID와 환경 ID를 직접 추측하지 마세요.

Apidog에서 다음 순서로 명령을 가져옵니다.

  1. 테스트 시나리오 열기
  2. CI/CD 탭으로 이동
  3. 생성된 CLI 명령 복사
  4. AGENTS.md에 붙여넣기

명령은 일반적으로 다음 형식입니다.

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

각 옵션의 의미는 다음과 같습니다.

옵션 설명
-t 테스트 시나리오 ID
-e 환경 ID
-r cli 결과를 터미널 인라인 출력으로 반환하는 리포터

에이전트가 잘못된 ID를 추측하지 않도록, Apidog의 CI/CD 탭에서 복사한 명령을 그대로 사용하세요.

단계 3: DeepSeek Harness에서 테스트 실행

dsh 웹 UI에서 프로젝트 작업 공간을 선택한 뒤 세션을 시작합니다. AGENTS.md가 로드되었다면 에이전트는 Apidog CLI 명령을 이미 알고 있어야 합니다.

다음과 같이 요청할 수 있습니다.

Apidog 테스트 시나리오를 실행하고 종료 코드를 알려주세요.
Enter fullscreen mode Exit fullscreen mode

또는 API 변경까지 포함해 요청할 수 있습니다.

체크아웃 핸들러를 수정한 뒤 AGENTS.md에 정의된 Apidog 테스트를 실행하세요.
실패하면 보고서를 읽고 코드를 수정한 뒤 다시 실행하세요.
Enter fullscreen mode Exit fullscreen mode

DeepSeek Harness의 기본 bash 도구는 명령마다 새 셸을 실행합니다. 따라서 다음과 같은 두 단계 호출은 의도대로 동작하지 않을 수 있습니다.

cd apps/api
Enter fullscreen mode Exit fullscreen mode 
apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

두 번째 명령은 첫 번째 명령의 cd 상태를 유지하지 않습니다.

시나리오를 특정 하위 디렉터리에서 실행해야 한다면, AGENTS.md에 전체 명령을 한 줄로 작성하세요.

- Command: cd apps/api && apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

또는 Harness가 제공하는 경우 bash 도구의 workdir 매개변수를 사용하세요.

도구 카탈로그에 따르면, 명령 실패 시 Harness는 다음과 같은 마커를 반환합니다.

[exit code: 1]
Enter fullscreen mode Exit fullscreen mode

긴 로그가 잘리더라도 이 마커를 통해 테스트 성공 여부를 확인할 수 있습니다.

권한 정책에 따라 apidog run 실행 전 승인을 요청받을 수도 있습니다. 사용자 가이드에 따라 웹 UI에서 요청을 승인하면 됩니다.

단계 4: CLI 보고서 읽기

테스트가 실패했을 때는 -r cli 출력이 핵심입니다. CLI 보고서에는 일반적으로 다음 정보가 포함됩니다.

  • 실행된 요청
  • 각 요청의 어설션 결과
  • 예상 상태 코드와 실제 상태 코드
  • 예상 필드와 실제 응답 필드
  • 실패한 어설션

예를 들어 다음과 같은 실패를 확인할 수 있습니다.

Expected status code: 200
Actual status code: 500
Enter fullscreen mode Exit fullscreen mode

또는:

Assertion failed: response.body.total is required
Enter fullscreen mode Exit fullscreen mode

이 정보가 있으면 에이전트는 사용자 설명 없이도 실패한 핸들러, 응답 DTO 또는 데이터 변환 로직을 찾아 수정할 수 있습니다.

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

apidog run -t 123456 -e 789012 -r cli,html
Enter fullscreen mode Exit fullscreen mode

html 리포터는 ./apidog-reports에 자체 포함형 보고서를 생성합니다. 다만 에이전트가 다음 수정 작업을 결정하려면 터미널 출력도 필요하므로 cli 리포터는 유지하는 것이 좋습니다.

전체 루프: 수정, 테스트, 수정

설정이 완료되면 API 작업 흐름은 다음과 같이 바뀝니다.

  1. 에이전트가 체크아웃 핸들러 수정
  2. apidog run -t 123456 -e 789012 -r cli 실행
  3. 종료 코드와 어설션 결과 확인
  4. 통과하면 다음 작업 진행
  5. 실패하면 실패한 필드, 상태 코드 또는 응답 값 확인
  6. 코드 수정
  7. 테스트 재실행

예를 들어 테스트가 다음과 같이 실패했다고 가정해 보겠습니다.

Expected status: 200
Actual status: 500
[exit code: 1]
Enter fullscreen mode Exit fullscreen mode

에이전트는 단순히 “코드가 올바르게 보인다”라고 판단하지 않고, 실제 API 계약 테스트 결과를 기준으로 핸들러를 다시 검토할 수 있습니다.

또 다른 실패 예시는 다음과 같습니다.

Expected field: total
Actual response: field missing
[exit code: 1]
Enter fullscreen mode Exit fullscreen mode

이 경우 에이전트는 응답 객체에 total이 누락되었는지, 직렬화 과정에서 필드가 제거되었는지, 잘못된 DTO를 반환하고 있는지 확인한 뒤 수정하고 시나리오를 다시 실행합니다.

핵심은 역할 분리입니다.

  • DeepSeek Harness: 코드 읽기, 수정, 명령 실행
  • Apidog CLI: API 계약 및 시나리오 검증
  • Apidog: 테스트 시나리오의 시각적 작성과 관리

에이전트는 API가 동작하는지 확인하기 위해 모든 라우트와 핸들러 파일을 반복해서 해석할 필요가 없습니다. Apidog 시나리오가 이미 기대 동작을 정의하고 있으므로, 에이전트는 결정론적인 CLI 결과를 바탕으로 수정 작업을 진행할 수 있습니다.

dsh가 실제로 테스트를 실행했는지 확인하기

에이전트의 요약만 믿지 말고, 다음 세 가지를 확인하세요.

1. 실제 bash 호출 확인

dsh 웹 UI는 에이전트의 도구 호출과 출력을 세션에 표시합니다.

다음과 같은 실제 명령이 표시되는지 확인하세요.

apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

에이전트가 “테스트를 실행했다”고 말하지만 실제 bash 호출이 없다면 테스트는 실행되지 않은 것입니다. 이 경우 다음처럼 요청하세요.

Apidog 테스트를 다시 실행하고, 원시 CLI 출력과 종료 코드를 보여주세요.
Enter fullscreen mode Exit fullscreen mode

2. 종료 코드 확인

직접 종료 코드를 물어보세요.

방금 실행한 apidog run 명령의 종료 코드는 무엇이었나요?
Enter fullscreen mode Exit fullscreen mode

다음 값이 기준입니다.

  • 0: 모든 어설션 통과
  • 0 이외의 값: 테스트 실패 또는 실행 문제 발생

에이전트가 “테스트 통과”라고 요약했더라도 출력에 [exit code: 1]이 있다면 실패로 처리해야 합니다.

3. 실제 시나리오 ID와 환경 ID 확인

다음과 같은 오류는 대개 잘못된 ID를 사용했음을 의미합니다.

Scenario not found
Enter fullscreen mode Exit fullscreen mode

이 경우 다음 세 위치의 값을 비교하세요.

  1. Apidog CI/CD 탭에서 복사한 명령
  2. 리포지토리의 AGENTS.md
  3. dsh가 실제로 실행한 bash 명령

특히 -t와 -e 값이 일치해야 합니다. AGENTS.md에 기록된 명령을 기준으로 삼고, 에이전트가 임의로 생성하거나 기억한 값은 신뢰하지 않는 것이 안전합니다.

선택 사항: API 사양 접근을 위한 Apidog MCP 서버 추가

Apidog CLI는 검증에 적합합니다. 반면 에이전트가 코드를 작성하기 전에 API 스키마와 엔드포인트 정의를 읽게 하려면 MCP가 필요합니다.

2026년 8월 말 기준으로 DeepSeek Harness 핵심 README와 사용자 가이드에는 MCP 지원이 문서화되어 있지 않습니다. 대신 커뮤니티 플러그인인 hyqhyq3/dsh-mcp-manager를 사용할 수 있습니다.

이 플러그인은 다음 기능을 제공합니다.

  • 설정 화면에 MCP 관리 페이지 추가
  • 원격 HTTP MCP 서버 지원
  • 로컬 stdio MCP 서버 지원
  • mcp__<name>__* 형식의 도구 등록
  • <workspace>/.dsh/dshmm/mcp.json에서 프로젝트별 서버 설정 로드

이를 통해 Apidog MCP 서버를 연결하면, 에이전트는 테스트 실패 후뿐 아니라 핸들러를 작성하기 전에도 API 사양을 조회할 수 있습니다.

다만 이는 커뮤니티 플러그인과 개발자 프리뷰 호스트를 함께 사용하는 구성입니다. 양쪽 업데이트로 인해 동작이 바뀔 수 있으므로, 기본 경로는 여전히 CLI로 유지하는 것이 좋습니다.

기본 경로: Apidog CLI로 테스트 실행
추가 경로: MCP로 API 스키마와 엔드포인트 조회
Enter fullscreen mode Exit fullscreen mode

개발자 프리뷰 주의 사항

DeepSeek Harness는 빠르게 변경될 수 있습니다. 특히 다음 요소는 변경 가능성이 높습니다.

  • 지침 파일 탐색 규칙
  • AGENTS.md 및 CLAUDE.md 우선순위
  • bash 도구의 샌드박스 동작
  • 권한 승인 흐름
  • MCP 플러그인 호환성

구체적인 설정이 바뀌더라도 핵심 패턴은 유지됩니다.

  1. 규칙 파일에 API 검증 명령 기록
  2. 에이전트가 해당 명령 실행
  3. CLI가 명확한 종료 코드 반환
  4. 에이전트가 실패 로그를 바탕으로 코드 수정
  5. 수정 후 다시 검증

이 패턴은 Claude Code에서 Apidog CLI 사용하기와 다른 Harness 환경에서도 적용할 수 있습니다. 에이전트는 명령 출력 해석에는 강하지만, 실제 검증 명령 없이 결과를 신뢰하기는 어렵기 때문입니다.

Apidog를 다운로드한 뒤 테스트 시나리오 하나를 만들고, CI/CD 탭에서 apidog run 명령을 복사해 AGENTS.md에 추가해 보세요. 다음에 DeepSeek Harness가 API 코드를 수정할 때, 완료되었다고 말하기 전에 실제 시나리오로 결과를 확인하게 할 수 있습니다.

FAQ

DeepSeek Harness는 기본적으로 AGENTS.md를 읽나요?

예. @deepseek-ai/dsh-agent-instructions 플러그인은 프로젝트 루트와 세션 작업 디렉터리 상위 경로에서 AGENTS.md를 읽습니다. 파일이 없으면 CLAUDE.md를 대체 파일로 사용하며, AGENTS.local.md, CLAUDE.local.md, ~/.dsh/AGENTS.md도 로드할 수 있습니다.

다른 에이전트용으로 이미 AGENTS.md를 유지하고 있다면 dsh는 별도 변환 없이 해당 파일을 활용할 수 있습니다.

dsh에서 Apidog CLI를 사용하려면 유료 DeepSeek 플랜이 필요한가요?

아니요. Harness는 MIT 라이선스 기반 오픈 소스이며 사용자가 모델을 선택합니다. 카탈로그 공급자는 Anthropic, OpenAI, Bedrock, Vertex, Azure를 다루며, 사용자 지정 게이트웨이는 settings.yaml으로 설정할 수 있습니다.

관련 내용은 DeepSeek Harness에서 모든 모델을 실행하는 방법에서 확인할 수 있습니다.

Apidog CLI 자체는 무료 npm 패키지입니다. 필요한 것은 특정 DeepSeek 플랜이 아니라 Apidog 테스트 시나리오와 인증입니다.

두 번째 명령이 첫 번째 명령의 디렉터리 변경을 잊는 이유는 무엇인가요?

기본 dsh bash 도구가 각 호출을 새 셸에서 실행하기 때문입니다. 첫 번째 호출의 cd는 두 번째 호출에 유지되지 않습니다.

다음 중 하나를 사용하세요.

cd apps/api && apidog run -t 123456 -e 789012 -r cli
Enter fullscreen mode Exit fullscreen mode

또는 Harness 도구의 workdir 매개변수를 전달하세요.

dsh가 매번 승인 요청 없이 시나리오를 실행할 수 있나요?

활성 권한 정책에 따라 다릅니다. 웹 UI는 승인이 필요한 작업 전에 요청을 표시할 수 있습니다. 정책 수준은 배포 구성에 따라 달라질 수 있으므로 현재 환경의 설정을 확인하세요.

스테이징 환경에 대해 읽기 중심으로 실행하는 apidog run은 승인 가능한 작업의 일반적인 예입니다.

Top comments (0)