DeepSeek Harness 실측: AI Agent는 모델만으로 부족하다

최종 확인은 2026년 9월 11일입니다. 근거는 DeepSeek Harness 공식 저장소, Skills 서브시스템, Process Sandbox 문서입니다.

DeepSeek를 Claude나 Gemini로 바꿔도 대화는 나아질 수 있습니다. 현장에서 넘어지는 지점은 같습니다. 모델이 도구를 부르고 파일을 고치고 스크립트를 돌리는데, 그 한 걸음이 왜 생겼는지, 다시 재생할 수 있는지, 어디에 썼는지, 재시도해도 되는지를 아무도 설명하지 못합니다. 2026년 Agent의 병목은 “누가 더 잘 답하느냐”가 아니라 누가 작업을 안전하게 끝내는가입니다.

먼저 결론입니다. 모델은 다음 의도를 고릅니다. Harness는 루프, 세션, 플러그인 조합을 가집니다. Skill은 절차서를 필요할 때만 넣고, 시스템 프롬프트에 전부 밀어 넣지 않습니다. Sandbox는 이번 자식 프로세스가 만져도 되는 파일을 정하고, 격리를 강제할 수 없으면 조용히 맨몸으로 실행하지 않고 실패합니다. 한 층이라도 빠지면 데모는 통과하고 감사는 실패합니다.

도구 호출과 실행 주체를 나누는 법은 다른 스택에서도 같습니다. Gemini Agent가 도구·API·함수를 호출하는 방법도 의도와 실행을 분리합니다. 필드 이름만 다를 뿐, 모델만 갈아끼운다고 루프가 스스로 고쳐지지는 않습니다.

모델만 바꿔서는 안 고쳐지는 세 가지

“더 센 모델”을 Agent 계획 자체로 두면 보통 세 곳이 같이 무너집니다. 공급사를 바꿔도 그대로입니다.

첫째는 믿을 수 없는 루프 기억입니다. 실제 작업은 목록, 읽기, 수정, 테스트를 여러 번 왕복합니다. 이력이 프로세스 안 배열에만 있으면 재시작이나 화면 갱신에 작업 기억이 사라집니다. 디버깅하는 사람도 같은 이벤트 로그를 못 보고 채팅 스크린샷으로 추측합니다.

둘째는 절차서 과부하입니다. 배포 규칙, 스타일, 티켓 절차를 시스템 프롬프트에 다 붙이면 창이 차고 단계가 빠집니다. “반드시 지켜라”를 더해도 더 시끄러워질 뿐입니다. 평소에는 목록만 보여주고, 실제로 손을 댈 때 본문 하나만 읽히면 됩니다.

셋째는 가두지 않은 부작용입니다. 셸을 쓸 수 있으면 저장소 밖에도 씁니다. 비밀 파일을 건드리고, 실패한 반제품을 디스크에 남깁니다. “그러지 마라”는 프롬프트는 제어면이 아닙니다.

컨텍스트를 키워도 해결되지 않습니다. 잘못된 절차서가 더 오래 자리를 차지할 뿐입니다. 루프와 파일 경계는 실행 층의 일입니다.

Harness가 맡는 일

DeepSeek Harness(dsh)는 또 하나의 채팅 화면이 아니라 오픈소스 Agent Harness입니다. 공식 문구는 Everything is a Plugin입니다. 모델 어댑터, 시스템 프롬프트, 도구 등록, 세션 로그, Agent 인터페이스, 기본 루프가 교체 가능한 패키지로 나뉘고 Cordis로 조합됩니다. 저장소는 아직 개발자 프리뷰입니다. 호환이 깨질 수 있습니다. 그래도 “실행 층이 무엇을 가져야 하는가”를 보기에는 충분합니다.

실측에서 Harness가 대신 지는 일은 세 가지입니다.

• 다음 한 걸음을 누가 돌리는가. 기본 agent-loop는 Agent 계약의 한 구현일 뿐입니다. 플러그인은 기본 드라이버가 아니라 인터페이스에 의존해야 합니다. 목표가 흐리면 열린 루프, 승인이 있는 업무는 바깥을 확정 워크플로로 둡니다.
• 다시 만들 수 있는 세션. 다음 모델 요청은 Session Log에서 나와야 합니다. 어떤 함수의 임시 배열이 아닙니다. 원본 청크를 남기는 이유는 재생, 화면, 조사입니다.
• 덮어쓸 수 있는 조합. Profile, Bundle, Patch가 런타임 플러그인 나무가 됩니다. 모델 공급자나 샌드박스, UI를 바꿀 때는 코어를 복사하기 전에 Patch를 칩니다. dsh --profile web --dump-config로 실제로 뜨는 나무를 봅니다.

따라서 Harness는 모델을 더 똑똑하게 만들지 않습니다. 누가 다음을 돌리는지, 이력이 어디에 있는지, 어느 이음을 바꿔도 되는지에 답합니다. 이 층이 없으면 Skill을 넣을 시점이 흔들리고, Sandbox를 부를 주체도 흔들립니다.

Skill이 맡는 일

공식 Skill은 선택 지시이며 세션 이벤트가 아닙니다. 모델이 평소 보는 것은 목록뿐입니다. 정렬된 name과 잘리고 이스케이프된 description(기본 상한 500자)입니다. 본문, 경로, 출처, 라우팅 힌트는 미리 프롬프트에 들어가지 않습니다. 작업을 시작하면 모델이 skill({ name })을 부르고, 프레임워크가 세션 cwd에서 이긴 Skill을 풀어 정규 결과를 돌려줍니다.

로컬 Skill 이름은 kebab-case입니다. 디렉터리 묶음의 SKILL.md이거나 납작한 Markdown입니다. 중첩 **/SKILL.md 재귀 발견은 지원하지 않습니다. 로컬 제공자는 순위대로 루트를 봅니다. 프로젝트 .dsh/skills가 가장 앞이고, 다음은 .agents/skills, 그다음이 사용자 정의, 사용자 홈, 번들입니다. 프로젝트 루트는 가장 가까운 Git 루트이고, 없으면 cwd 자체입니다.

이 층이 답하는 질문은 “절차서가 언제 나타나느냐”입니다. 배포 점검이나 테스트 수정 절차를 Skill로 두면 그 일에서만 본문이 올라갑니다. 본문을 고쳐도 지난 도구 결과는 다시 쓰이지 않습니다. 목록은 핫 리프레시할 수 있지만, 불완전한 발견이 직전 사용 가능 목록을 덮으면 안 됩니다.

Skill은 권한 시스템이 아닙니다. 하는 방법을 알려 줄 뿐, 작업 공간 밖 쓰기를 허용할지는 정하지 않습니다. Sandbox가 없으면 잘 쓰인 “배포 Skill”이 더 위험합니다. 위험한 단계가 실행하기 쉬워지기 때문입니다.

Sandbox가 가두는 범위

공식 Process Sandbox가 보는 것은 같은 호스트 자식 프로세스의 파일 부작용입니다. 네트워크와 프로세스 가시성은 이 어휘 밖입니다. 컨테이너, 마이크로VM, 원격 실행은 다른 능력 이음이며 ctx.sandbox의 구현이 아닙니다. 로컬 제공자는 Linux에서 bwrap/Landlock, macOS에서 Seatbelt, Windows에서 제한 토큰과 ACL을 씁니다.

모드는 세 가지이고, 격리 제공자로 가는 것은 앞의 둘뿐입니다.

• read-only는 쓰기를 거절합니다. POSIX 실행기는 셸이 필요로 하는 /dev/null만 더 엽니다.
• workspace-write는 세션의 불변 cwd와 백엔드가 약속한 임시 영역에 쓰기를 허용합니다.
• danger-full-access는 격리를 건너뜁니다. 호출자가 원래 argv를 직접 띄우고 ctx.sandbox는 부르지 않습니다.

실측에서 남는 규율은 닫힌 실패입니다. 격리를 요청했는데 쓸 백엔드가 없으면 SANDBOX_UNAVAILABLE을 던지고, 조용한 통과는 금지입니다. 정책은 호출마다 정해지므로 bash는 읽기 전용으로 두고 자식 Agent의 상태 디렉터리만 쓸 수 있습니다. 실패도 둘로 나눕니다. 러너가 안 뜬 것과, 격리가 작동해 쓰기를 막은 것. 앞은 인프라, 뒤는 Sandbox가 일한 것입니다.

강제 완전성은 full 또는 partial입니다. 오래된 Landlock과 일부 Windows ACL 경계는 지금 partial입니다. 절대 약속이 필요하면 partial을 잠긴 상태로 보지 마십시오.

한 작업에서 세 층이 붙는 순서

“실패한 테스트를 고치고 패치를 낸다”를 펼치면 추상이 사라집니다.

1. Harness가 Session Log에서 문맥을 다시 만들고, 보이는 Skill 목록(이름과 설명만)을 넣습니다.
2. 모델은 기억으로 단계를 만들지 않고 repo-test-patch 같은 Skill을 먼저 읽습니다.
3. skill 도구가 이 cwd의 본문을 다시 읽고 지시와 상대 자원 안내를 반환합니다.
4. 모델이 파일 읽기나 테스트 실행을 요청하고, Harness가 도구 관을 돌리며, Sandbox가 이번 정책으로 argv를 감쌉니다.
5. 결과는 Session Log로 돌아갑니다. 다음 걸음은 로그에서 나옵니다. “대충 했던 것 같다”는 전역 변수가 아닙니다.

Harness가 없으면 목록 주입과 결과 정착이 흔들립니다. Skill이 없으면 시스템 프롬프트가 매뉴얼로 넘칩니다. Sandbox가 없으면 분명한 Skill은 분명한 권한 상승 안내서입니다. 세 층은 보완이지, 같은 기능의 다른 이름이 아닙니다.

실행과 첫 Skill

공식 최단 경로는 npx @deepseek-ai/dsh web이고, 기본 Web UI는 http://127.0.0.1:3080입니다. 소스에서는 clone 후 pnpm install && pnpm run build && pnpm dsh web입니다. SSH로 띄우면 보통 호스트 URL만 찍고, 로컬 포워딩 주소는 클라이언트에 맡깁니다.

첫 프로젝트 Skill은 로컬 제공자가 가장 먼저 보는 저장소 루트에 둡니다.

---
name: repo-test-patch
description: 실패 테스트를 최소 패치로 고칠 때만 사용한다.
---

# repo-test-patch
1. 작업 공간 루트에서 브랜치를 확인한다.
2. 제품 코드를 고치기 전에 실패 테스트를 돌린다.
3. 패치는 실패와 관련된 파일만 건드린다.
4. 작업 공간 밖에는 쓰지 않는다.

이름은 kebab-case여야 합니다. 묶음은 SKILL.md입니다. 깊은 중첩은 발견되지 않습니다. frontmatter의 disable-model-invocation과 user-invocable이 모델과 사람이 목록에서 보는지를 정합니다. 둘 다 끄면 신뢰된 ctx.skills.get()만 읽을 수 있습니다.

띄운 뒤에는 세 가지를 봅니다. 세션에 목록 메시지가 생겼는지. skill이 본문을 돌려주고 매뉴얼 전체를 시스템 프롬프트에 미리 붙이지 않는지. read-only에서 작업 공간 밖 쓰기가 프롬프트가 아니라 백엔드에 거절되는지. 격리 백엔드가 없으면 맨몸 실행을 이어가지 말고 오류로 멈춰야 합니다.

DeepSeek Harness는 검증용 아키텍처 샘플입니다. 생산 인증을 끝낸 플랫폼으로 보지 마십시오. 받는 것은 루프, 목록, confine 경로이지 데모 영상이 아닙니다.

전체 스택을 올릴 때

직접 짠 while과 몇 개 도구에 비해 DeepSeek Harness의 이득은 조합, 세션 재구성, 호출 단위 격리가 이미 나뉘어 있다는 점입니다. 값은 Cordis 이해, 프리뷰 단계의 파괴, Skill과 Sandbox가 다르다는 학습 비용입니다. 올해 정말로 모델 백엔드나 샌드박스 구현을 바꾸거나 Skill 목록을 여러 저장소에 나눌 때만 이 분리가 수지가 맞습니다.

한 줄로. 2026년에 Agent를 안정적으로 돌리려면 채팅 모델을 한 번 더 갈아끼우는 일이 아닙니다. 판단, 루프, 절차서, 파일 경계를 나눕니다. Harness가 끝까지 돌리고, Skill이 필요할 때 설명하며, Sandbox가 이번에 쓸 수 있는 곳을 정합니다. 셋이 모이면 데모가 감사 가능한 작업이 됩니다.

자주 묻는 질문