DeepSeek Harness는 하나의 루프입니다. 에이전트는 작업 공간을 읽고, 파일을 편집하고, bash 도구를 통해 명령을 실행하며, 출력에 따라 다음에 무엇을 할지 결정합니다. 그렇다면 왜 API 테스트는 그 루프에 포함되지 않을까요? API 테스트는 GUI 뒤 Apidog에 존재하며 누군가가 클릭해야 실행됩니다. 에이전트는 API 테스트를 전혀 건드리지 않습니다.
해결책은 하나의 설정 블록입니다. Apidog CLI는 npm 패키지인 apidog-cli로, Apidog에서 구축한 테스트 시나리오를 터미널에서 직접 실행합니다. CLI가 설치되고 DeepSeek Harness가 CLI의 존재를 알게 되면, 에이전트는 단위 테스트를 실행하는 방식과 동일하게 Apidog 시나리오를 실행합니다. 즉, 명령을 실행하고, 종료 코드를 읽고, 빨간색이면 코드를 수정합니다.
이를 위한 토큰 인자도 있습니다. 핸들러 코드를 다시 읽고 응답 형태를 추론하여 API가 여전히 작동하는지 확인하는 에이전트는 매번 컨텍스트를 소모합니다. 하나의 명령을 실행하는 에이전트는 몇 줄의 코드로 실제 결과를 얻습니다. CLI는 "API가 올바른가?"라는 질문을 종료 코드로 압축하고, 에이전트는 컨텍스트를 수정 작업에 사용합니다.
이 가이드는 일반적인 설치 가이드에서 건너뛰는 Harness 특정 부분을 다룹니다. DeepSeek Harness가 실제로 읽는 지침 파일, bash 도구가 apidog run을 실행하는 방식, 그리고 루프를 정직하게 유지하는 방법 등입니다. 아직 CLI를 설치하지 않았다면 먼저 설치하십시오. AI 코딩 에이전트로 Apidog CLI를 설치하는 방법은 npm 설치, 인증 및 첫 실행을 안내합니다. 이 문서는 apidog --version이 숫자를 출력하고 컴퓨터가 인증되었다고 가정합니다.
이 문서가 다루는 DeepSeek Harness
명령줄에서 dsh로 불리는 DeepSeek Harness는 DeepSeek이 2026년 8월 13일 V4-Pro와 함께 API에 출시한 오픈 소스 에이전트 Harness입니다. MIT 라이선스를 따르며 github.com/deepseek-ai/deepseek-harness에 있으며, 8월 20일 현재 16만 9천 개 이상의 별표를 넘어섰습니다. npx @deepseek-ai/dsh web으로 시작하며, http://127.0.0.1:3080에서 로컬 웹 UI를 제공합니다. 여기서 작업 공간(시작한 프로젝트 디렉터리)을 선택하면 에이전트가 그 안에서 작동합니다. 파일을 읽고 편집하고, 명령을 실행하며, 활성 권한 정책에 따라 승인이 필요한 작업 전에 요청합니다.
두 가지가 아래의 모든 것을 형성합니다. 첫째, Harness는 **개발자 프리뷰**입니다. README는 대문자로 호환성을 깨뜨리는 변경 사항이 있을 것이라고 경고하므로, 여기의 파일 이름과 구성 키를 2026년 8월 말 기준으로 정확하다고 간주하고, 무언가 로드되지 않으면 리포지토리 문서와 다시 대조하십시오. 둘째, dsh의 모든 것은 Cordis 아키텍처를 기반으로 구축된 플러그인이며, 이는 아래의 실질적인 질문에 답할 수 있게 합니다. 즉, 어떤 플러그인이 프로젝트 규칙을 읽고 무엇을 찾습니까? 더 넓은 투어는 DeepSeek Harness란 무엇인가를 참조하고, 기존 제품과의 비교는 DeepSeek Harness vs Claude Code를 참조하십시오.
단계 1: AGENTS.md에 CLI 넣기
DeepSeek Harness는 @deepseek-ai/dsh-agent-instructions 플러그인을 통해 작업 공간 지침을 읽으며, 다른 에이전트를 사용해 본 적이 있다면 기본값이 친숙할 것입니다. 플러그인의 소스 및 설정 카탈로그에 따르면, 로더는 세션의 작업 디렉터리에서 프로젝트 루트(.git으로 표시됨)까지 위로 올라가면서 각 디렉터리에서 AGENTS.md를 로드하고, 찾지 못하면 CLAUDE.md로 대체합니다. AGENTS.local.md 또는 CLAUDE.local.md라는 로컬 오버레이는 기본 파일 다음에 로드되며, $DSH_HOME(기본값은 ~/.dsh)의 고정된 사용자 전역 AGENTS.md는 모든 프로젝트에 적용됩니다. 1MiB가 넘는 파일은 무시되는데, 규칙 파일은 이 크기에 근접하지 않을 것입니다.
실질적인 결론은 다음과 같습니다. 리포지토리에 이미 Codex용 AGENTS.md 또는 Claude Code용 CLAUDE.md가 있는 경우, DeepSeek Harness는 추가 설정 없이 이를 가져옵니다. 여기에 짧은 Apidog 블록을 추가하십시오:
## 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.
이것이 규칙 파일이 채팅보다 우월한 이유입니다. 세션 작성기에 입력된 시나리오 ID는 세션이 종료되면 사라집니다. AGENTS.md에 작성된 ID는 리포지토리를 복제하는 모든 팀원, 모든 컴퓨터의 새 세션에 로드됩니다. 여러 프로젝트에서 작업하는 경우, 사용자 전역 ~/.dsh/AGENTS.md는 습관("항상 프로젝트의 apidog run 명령으로 API 변경 사항을 확인하라")을 전달하고, 각 리포지토리의 파일은 실제 ID를 전달합니다.
단계 2: Apidog에서 명령 가져오기
시나리오 및 환경 ID를 추측할 필요가 없습니다. Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 이동하여 생성된 명령을 복사하십시오. 다음과 같이 보일 것입니다:
apidog run -t 123456 -e 789012 -r cli
-t 플래그는 테스트 시나리오 ID이고, -e는 환경 ID이며, -r cli는 결과를 인라인으로 출력하는 리포터를 선택합니다. 이는 에이전트가 읽어야 할 내용과 정확히 일치합니다. 실제 ID를 AGENTS.md 블록에 붙여넣어 에이전트가 Apidog가 생성한 명령을 실행하고 추측된 명령을 실행하지 않도록 하십시오.
단계 3: 에이전트가 테스트를 실행하도록 하기
작업 공간을 선택한 상태에서 dsh 웹 UI에서 세션을 시작하십시오. 지침 로더는 이미 AGENTS.md를 에이전트의 컨텍스트에 전달했으므로 에이전트는 CLI의 존재를 알고 있습니다. API에 영향을 주는 변경을 하거나 단순히 요청하십시오:
Apidog 테스트 시나리오를 실행하고 종료 코드를 알려주세요.
에이전트는 bash 도구를 통해 이를 실행하며, 해당 도구가 어떻게 작동하는지 알면 나중에 디버깅 세션을 절약할 수 있습니다. 도구 카탈로그에 따르면, 기본 bash 도구는 각 명령을 **새로운 쉘**에서 실행합니다. 즉, 호출 간에 작업 디렉터리, 변수 또는 함수가 지속되지 않으며, workdir가 전달되지 않는 한 명령은 세션 작업 공간에서 실행됩니다. apidog run과 같이 단일 독립형 명령에는 괜찮지만, 에이전트가 먼저 cd하여 특정 위치로 이동한 다음 두 번째 단계로 테스트를 실행할 수는 없습니다. 시나리오가 하위 디렉터리에서 실행되어야 하는 경우, 규칙 파일에 전체 호출을 한 줄로 작성하십시오.
알아두면 좋은 두 가지 동작이 더 있습니다. 0이 아닌 종료 코드는 명시적인 [exit code: N] 마커로 반환되므로, 긴 출력이 잘려도 통과/실패 신호가 유지됩니다. 그리고 명령은 파일 샌드박스 아래에서 실행될 수 있습니다. 차단된 작업은 명령 실패가 아닌 정책 거부로 보고됩니다. 읽기 전용 테스트 실행은 거의 이를 유발하지 않지만, HTML 리포터가 ./apidog-reports에 쓰는 것은 활성 정책에 따라 발생할 수 있습니다.
실행에 먼저 클릭이 필요한지 여부는 동일한 권한 정책에 따라 달라집니다. 웹 UI는 사용자 가이드에 따라 승인이 필요한 작업 전에 요청합니다. apidog run에 대해 프롬프트가 나타나면 승인하십시오. 스테이징에 대한 테스트 시나리오는 승인 흐름이 통과시키도록 존재하는 안전하고 읽기 위주 명령의 정확한 종류입니다.
단계 4: 보고서 읽기
실행이 실패하면 보고서에 답이 있습니다. -r cli를 사용하면 에이전트는 인라인으로 읽을 수 있는 분석을 얻습니다. 각 요청, 각 어설션, 그리고 예상 값과 실제 값 중 어떤 것이 실패했는지 나타납니다. 실패한 어설션은 정확한 필드 또는 상태 코드를 명명하며, 이는 일반적으로 에이전트가 사용자의 번역 없이 수정 사항을 찾는 데 충분합니다.
브라우저에서 열거나 팀원에게 전달할 수 있는 보고서를 원한다면 HTML 리포터를 추가하십시오:
apidog run -t 123456 -e 789012 -r cli,html
html 리포터는 ./apidog-reports에 자체 포함된 파일을 작성합니다. 에이전트가 다음 단계를 결정하기 위해 읽는 인라인 출력을 계속 얻을 수 있도록 cli를 목록에 유지하십시오.
루프, 처음부터 끝까지
설정으로 얻을 수 있는 것은 다음과 같습니다. 에이전트가 체크아웃 핸들러를 편집하고 있다고 가정해 봅시다. CLI가 없으면 루프는 "코드가 올바르게 보인다"에서 끝납니다. AGENTS.md에 블록이 있으면 루프가 확장됩니다. 핸들러를 편집하고, apidog run -t 123456 -e 789012 -r cli를 실행하고, 결과를 읽습니다. 녹색이면 다음으로 넘어갑니다. 빨간색이면 [exit code: 1]을 보고, 어떤 어설션이 실패했는지(200이 예상되었는데 500이 발생했는지, total 필드가 누락되었는지, 잘못된 통화 코드인지) 확인하고, 핸들러를 패치하고, 다시 실행합니다. API 계약 확인은 에이전트가 이미 단위 테스트를 실행하는 것과 동일한 편집-테스트-수정 사이클의 일부가 됩니다.
에이전트가 하지 않은 일에 주목하십시오. API가 작동하는지 확인하기 위해 모든 경로 파일을 다시 읽지 않았습니다. 시나리오는 이미 API 소유자가 Apidog에서 시각적으로 구축한 예상 동작을 인코딩하고 있습니다. 에이전트는 검증을 결정론적 도구에 위임하고 판단이 필요한 곳에 토큰을 사용합니다. 이러한 분업이 전체 패턴입니다. dsh는 코드를 작성하고, CLI는 API 계층을 검증하며, 사용자는 테스트 코드를 전혀 작성하지 않고도 Apidog에서 시나리오를 작성합니다.
dsh가 실제로 실행했는지 확인하기
에이전트는 얻지 못한 성공을 보고하고, 개발자 프리뷰 Harness는 글을 그대로 믿을 곳이 아닙니다. 문제점을 포착하는 순서대로 세 가지 확인 사항을 살펴봅니다.
첫째, 명령이 실행되었는지 확인하십시오. dsh 웹 UI는 에이전트의 도구 호출과 그 출력을 세션에 표시합니다. 문자 그대로의 apidog run ... bash 호출과 그 결과를 찾으십시오. 에이전트가 테스트를 실행했다고 말했지만 그러한 호출이 나타나지 않으면, 그것은 결코 하지 않은 일을 요약한 것입니다. 다시 실행하고 원시 출력을 표시하도록 요청하십시오.
둘째, 종료 코드를 확인하십시오. 직접 물어보십시오: "그 apidog run 명령의 종료 코드는 무엇이었습니까?" Harness는 실패 시 에이전트에게 명시적인 [exit code: N] 마커를 제공하므로 숨길 모호성이 없습니다. 에이전트의 요약이 "테스트 통과"라고 말했지만 마커가 0이 아니었다면 마커가 맞습니다.
셋째, 실제 시나리오를 사용했는지 확인하십시오. "시나리오를 찾을 수 없음" 실패는 일반적으로 에이전트가 ID를 만들었거나 잘못 기억했음을 의미합니다. -t 및 -e 값을 AGENTS.md 블록 및 Apidog의 CI/CD 탭의 명령과 다시 대조하십시오. 규칙 파일의 ID가 진실입니다. 에이전트가 입력한 다른 모든 것은 추측입니다.
선택 사항: 사양 접근을 위해 Apidog MCP 서버 추가
시나리오 실행은 검증을 다룹니다. 에이전트가 코드를 작성하는 동안 API 사양을 읽기를 원한다면, 이는 MCP의 역할이며, 여기서 솔직한 그림이 중요합니다. 2026년 8월 말 현재, MCP 지원은 DeepSeek Harness 핵심 README 또는 사용자 가이드에 문서화되어 있지 않습니다. 존재하는 것은 커뮤니티 플러그인인 hyqhyq3/dsh-mcp-manager이며, 이는 다른 생태계와 마찬가지로 dsh-plugin GitHub 토픽을 통해 발견되었습니다. 이 플러그인은 설정 아래에 MCP 페이지를 추가하고, 원격 HTTP 및 로컬 stdio 서버를 지원하며, 도구를 mcp__<name>__*로 등록하고, <workspace>/.dsh/dshmm/mcp.json에서 프로젝트별 서버 정의를 읽습니다.
이를 통해 Apidog MCP 서버를 연결할 수 있으며, 이는 API 사양을 MCP를 통해 노출하여 에이전트가 시나리오 실패 후가 아니라 핸들러를 작성하기 전에 엔드포인트의 실제 스키마를 확인할 수 있도록 합니다. 커뮤니티 플러그인과 개발자 프리뷰 호스트의 조합은 양측의 업데이트로 인해 깨질 수 있으므로, 이를 추가적인 계층으로 간주하십시오. 위의 CLI 경로는 핵심 경로입니다. 쉘 외에는 아무것도 필요하지 않습니다.
미리보기 주의 사항 및 향후 방향
DeepSeek Harness는 빠르게 움직이며 문제가 발생할 수 있음을 경고합니다. 여기에서 언급된 특정 사항들, 즉 지침 플러그인의 파일 후보, bash 도구의 샌드박스 보고, 커뮤니티 MCP 플러그인이 다루는 모든 것이 변경될 가능성이 가장 높습니다. 그러나 패턴은 이식 가능합니다. "이 명령 하나로 API를 검증하라"고 말하는 규칙 파일과 깔끔한 종료 코드를 반환하는 CLI는 Claude Code 및 이 시리즈의 다른 모든 Harness에서 작동하는 것과 동일한 이유로 dsh에서도 오늘날 작동합니다. 에이전트는 명령 출력을 읽는 데 능숙하지만, 그것 없이는 신뢰하기 어렵기 때문입니다.
그러니 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 패키지입니다. 특정 모델이 아니라 Apidog 테스트 시나리오와 인증이 필요합니다.
에이전트의 두 번째 명령이 첫 번째 명령이 변경했던 디렉터리를 잊는 이유는 무엇인가요? 의도된 설계입니다. 기본 dsh bash 도구는 모든 호출을 새로운 쉘에서 실행하므로, cd는 명령 간에 지속되지 않습니다. 도구의 workdir 매개변수를 전달하거나, 더 간단하게, 규칙 파일에 전체 apidog run 호출을 한 줄로 유지하여 잊을 것이 없도록 하십시오.
dsh는 매번 저에게 묻지 않고 시나리오를 실행할 수 있나요? 이는 활성 권한 정책에 따라 다릅니다. 웹 UI는 승인이 필요한 작업 전에 요청합니다. 사용자 가이드는 정책 수준을 열거하지 않으므로, 배포가 허용하는 사항을 확인하려면 빌드의 설정을 확인하십시오. 프롬프트가 나타날 때, 스테이징에 대한 apidog run을 승인하는 것은 안전한 예입니다.