2026 DeepSeek Harness 병렬 도구 호출은 몇 개로 열어야 할까?
DeepSeek Harness에서 병렬 도구 호출을 무조건 늘리면 코드 충돌과 자원 경쟁이 먼저 발생할 수 있습니다. 이 글은 읽기 전용, 독립 쓰기, 공유 쓰기, 외부 부작용 도구를 나누고 작업 공간 격리, 자원 피크, 취소 복구, 로그 추적성을 기준으로 직렬·제한 병렬·환경 분할을 결정하는 절차를 설명합니다.
공식 설정 목록에서 maxParallelToolCalls는 에이전트 단계 안에서 동시에 실행할 수 있는 호출 수를 뜻하며, 1은 직렬 실행으로 정의되어 있습니다. 따라서 2026년 DeepSeek Harness 병렬 도구 호출은 맥의 코어 수에 맞춰 바로 정할 값이 아닙니다. 이번 주에는 1을 기준선으로 삼고, 읽기 전용 도구부터 격리·취소·로그 검증을 통과한 범위만 제한 병렬로 여는 것이 안전합니다. 공식 설정 카탈로그에도 같은 기준이 명시되어 있습니다.
이 글은 세 부류의 독자를 위한 글입니다.
에이전트 개발자는 여러 도구 단계를 줄이면서 결과 경쟁을 피할 수 있습니다. 플랫폼 엔지니어는 공유 실행 환경의 자원과 동시성 경계를 정할 수 있습니다. 기술 구매 담당자는 현재 맥 한 대로 버틸지, 독립된 맥 환경을 추가할지 판단할 수 있습니다.
이번 주 실행 일정과 판단 기준
| 시점 | 확인할 항목 | 통과하지 못했을 때 |
|---|---|---|
| 오늘 | 도구별 읽기·쓰기·외부 전송 대상을 목록화합니다 | 모든 도구를 직렬로 유지합니다 |
| 다음 실행 | 동일 작업을 직렬 기준선으로 반복합니다 | 병렬 비교를 보류합니다 |
| 그다음 실행 | 격리, 자원 피크, 취소, 로그를 함께 검증합니다 | 병렬 상한을 낮추거나 환경을 나눕니다 |
| 승인 시점 | 통과한 도구 조합만 제한 병렬로 적용합니다 | 공유 쓰기 도구는 직렬로 회귀합니다 |
DeepSeek Harness는 도구 등록부와 실행 파이프라인을 플러그인으로 구성합니다. 따라서 도구 이름이 read, test, build처럼 보인다는 이유만으로 안전성을 추정하면 안 됩니다. 실제로는 실행 파이프라인이 어떤 권한과 작업 공간을 전달하는지 확인해야 합니다. 공식 구조 문서는 도구, 세션 기록, 에이전트 루프까지 교체 가능한 플러그인으로 설명합니다.
도구 부작용 분류
먼저 각 도구에 대해 아래 세 가지 대상을 기록합니다.
- 무엇을 읽는가
- 무엇을 변경하거나 생성하는가
- 어떤 외부 시스템으로 데이터를 보내거나 상태를 바꾸는가
| 도구 유형 | 읽는 대상 | 쓰는 대상 | 외부 부작용 | 초기 운영 방식 |
|---|---|---|---|---|
| 읽기 전용 | 소스, 설정, 로그 | 없음 또는 메모리 | 없음 | 격리 확인 후 제한 병렬 |
| 독립 쓰기 | 고유 임시 경로, 별도 산출물 | 전용 디렉터리 | 없음 | 작업 공간 분리 후 제한 병렬 |
| 공유 쓰기 | 공용 소스와 설정 | 같은 파일, 빌드 폴더, 잠금 파일 | 간접 영향 | 직렬 |
| 외부 작업 | 파일과 인증 정보 | 배포 상태, 티켓, 저장소 | 네트워크 요청, 배포, 메시지 전송 | 승인 게이트 뒤 직렬 |
코드 검색과 서로 다른 파일을 읽는 검사는 병렬 시험의 첫 후보가 될 수 있습니다. 반면 테스트가 캐시나 결과 폴더를 갱신하거나, 빌드가 공용 잠금 파일을 만들면 읽기 전용으로 볼 수 없습니다. 외부 API 호출은 응답을 받기만 해도 호출량, 비용, 상태 변경이 발생할 수 있으므로 별도 부작용으로 분류해야 합니다.
모델이 한 단계에서 여러 도구 호출을 생성했다는 사실도 모든 도구가 안전하게 동시에 실행된다는 뜻은 아닙니다. 실행기가 병렬 안전 호출만 묶는지, 실패 시 다른 호출을 중단하는지, 결과를 원래 호출과 연결하는지는 별도 검증 대상입니다. 공식 도구 문서의 실행 파이프라인과 도구 권한 설명을 함께 확인해야 합니다. 공식 도구 실행 문서
작업 공간과 파일 경쟁
DeepSeek Harness에서 여러 명령이 서로 다르다는 사실만으로 파일 충돌이 사라지지는 않습니다. 코드 검색은 색인 파일을 만들 수 있고, 테스트는 캐시를 갱신할 수 있으며, 빌드는 공용 출력 폴더와 잠금 파일을 사용할 수 있습니다.
다음 항목을 병렬 실행 전후에 비교해야 합니다.
git status와 변경 파일 목록- 브랜치와 현재 커밋
- 빌드 디렉터리와 임시 파일
- 잠금 파일의 생성·삭제 상태
- 각 산출물의 작업 식별자와 소유 도구
- 중단 뒤 남은 반쪽 결과
| 검증 결과 | 해석 | 선택 |
|---|---|---|
| 읽기만 하고 변경 차이가 없음 | 충돌 가능성이 낮습니다 | 제한 병렬 후보 |
| 도구마다 고유 경로를 사용함 | 독립 쓰기가 가능합니다 | 분리된 경로에서 병렬 |
| 공용 파일이나 캐시를 갱신함 | 명령이 달라도 쓰기 경쟁이 있습니다 | 직렬 또는 전용 작업 공간 |
| 브랜치와 산출물 소유가 섞임 | 결과 귀속이 불가능합니다 | 환경 분할 후 재검증 |
병렬 빌드 작업은 서로 다른 명령을 실행하는 것보다 서로 다른 작업 공간을 제공하는지가 중요합니다. 같은 저장소, 같은 빌드 폴더, 같은 패키지 캐시를 사용한다면 작업 공간을 나누지 않은 병렬 빌드는 승인하지 않는 편이 낫습니다. 다중 프로젝트를 운영한다면 맥 환경 분할 운영 안내처럼 프로젝트별 실행 환경을 분리하는 방식도 비교 대상에 넣어야 합니다.
자원 피크와 맥 동시성
maxParallelToolCalls는 애플리케이션 수준의 동시 호출 상한입니다. 맥의 CPU 코어 수나 메모리 용량을 자동으로 의미하지 않습니다. 병렬 빌드, 테스트, 언어 서버, 셸 하위 프로세스가 동시에 실행되면 CPU만이 아니라 메모리 압력, 파일 디스크립터, 임시 저장 공간, 입출력 대기까지 누적됩니다.
단일 환경에서 측정할 때는 다음 순서가 적합합니다.
- 동일한 커밋과 동일한 입력으로 직렬 기준선을 만듭니다.
- 실행 시간, 최대 메모리, CPU 사용률, 하위 프로세스 수를 기록합니다.
- 제한 병렬로 같은 작업을 반복합니다.
- 지속적인 자원 포화와 작업 실패 여부를 확인합니다.
- 결과가 안정적일 때만 다음 설정을 시험합니다.
| 관찰 항목 | 기록 방법 | 낮춰야 하는 신호 |
|---|---|---|
| CPU | 활성 상태 보기 또는 운영체제 계측 | 장시간 포화와 실행 시간 악화 |
| 메모리 | 메모리 압력, 스왑, 프로세스별 사용량 | 스왑 증가 또는 프로세스 종료 |
| 파일 핸들 | 프로세스별 열린 파일 수 | 핸들 부족, 읽기·쓰기 실패 |
| 임시 저장 공간 | 실행 전후 여유 공간 | 임시 파일 누적, 공간 부족 |
| 하위 프로세스 | 도구별 자식 프로세스 수 | 취소 뒤 잔류 프로세스 |
수치가 일시적으로 높아지는 것보다 지속적으로 포화되는지가 중요합니다. 작업이 끝난 뒤 정상으로 돌아오더라도 중간에 프로세스가 강제 종료되거나 결과가 누락되면 병렬 설정은 통과가 아닙니다. 맥의 자원 확인은 운영체제 자원 모니터링 문서를 기준으로 같은 작업을 반복 기록하는 방식이 적합합니다.
취소와 실패 복구
병렬 도구 실행은 성공 속도보다 중단 시 피해가 작아야 합니다. 한 도구가 실패하거나 사용자가 취소했을 때 다음 세 상태를 구분해야 합니다.
- 앞단 호출이 취소 응답을 반환했는가
- 백그라운드 하위 프로세스가 계속 남아 있는가
- 작업 공간에 반쯤 생성된 파일과 잠금 파일이 남았는가
반복 가능한 중지 시험은 다음처럼 진행합니다.
- 읽기 도구와 쓰기 도구를 하나의 작업 단계에 배치합니다.
- 실행 중간에 동일한 방식으로 취소합니다.
- 모든 하위 프로세스가 종료되는지 확인합니다.
- 작업 공간의 변경 파일과 잠금 파일을 저장합니다.
- 같은 세션을 재개했을 때 중복 실행이나 산출물 덮어쓰기가 없는지 확인합니다.
공식 개발 문서에는 셸 실행의 시간 제한, 출력 용량, 종료 유예 시간 같은 실행 경계가 설정 항목으로 존재합니다. 다만 이 설정이 모든 사용자 도구의 취소 동작까지 보장한다고 해석해서는 안 됩니다. 공식 개발 안내와 실제 사용하는 도구의 종료 동작을 함께 시험해야 합니다.
주의: 앞단 호출이 취소되었다는 로그만 보고 전체 작업이 끝났다고 판단하면 안 됩니다. 하위 프로세스와 반쪽 산출물을 직접 확인해야 합니다.
결과 순서와 로그 증거
병렬 실행에서는 결과의 도착 순서가 호출 순서와 다를 수 있습니다. 따라서 로그에 최소한 다음 정보를 남겨야 합니다.
- 작업 식별자
- 도구 이름과 입력 대상
- 시작 시각과 종료 상태
- 성공·실패·취소 구분
- 생성된 산출물 경로
- 상위 에이전트 단계와 원래 호출의 연결 정보
로그에 실제로 존재하지 않는 필드를 가정해 운영 대시보드를 만들면 안 됩니다. 먼저 세션 기록 문서를 확인하고, 현재 버전의 세션 이벤트와 실행 결과에 맞춰 수집해야 합니다. 공식 구조상 세션 로그와 도구 실행은 서로 다른 플러그인 경계를 가질 수 있으므로, 한쪽 기록만으로 전체 실행을 복원할 수 있는지도 확인해야 합니다.
설정값을 정하는 조건 분기
아래 조건을 순서대로 적용하면 maxParallelToolCalls 설정을 숫자 하나로 추측하는 실수를 줄일 수 있습니다.
- 모든 후보 도구가 읽기 전용이고, 작업 공간 변경이 없으며, 취소 뒤 하위 프로세스가 남지 않으면: 직렬 기준선과 비교해 제한 병렬을 선택합니다.
- 도구가 각자 독립된 경로에 쓰지만 공용 저장소나 캐시를 사용하면: 작업 공간과 캐시를 분리한 뒤 제한 병렬을 선택합니다. 분리가 불가능하면 직렬로 회귀합니다.
- 공유 소스, 공용 빌드 폴더, 잠금 파일, 배포 상태를 변경하면: 병렬 호출을 열지 않고 직렬로 유지합니다.
- 자원 피크가 지속되고 스왑, 프로세스 종료, 임시 공간 부족이 발생하면: 설정을 낮추고, 같은 작업이 계속 필요할 때만 독립 맥 환경을 추가합니다.
- 결과 순서와 오류를 원래 호출에 연결할 수 없으면: 속도가 빨라도 승인하지 않습니다.
- 도구마다 책임과 장시간 점유 자원이 완전히 다르면: 한 환경의 병렬 상한을 키우기보다 프로젝트 또는 작업 공간을 분리합니다.
이 판단표의 핵심은 “몇 개까지 가능한가”가 아니라 “어떤 도구 조합이 증거를 남기면서 안전하게 끝나는가”입니다. 자원 측정과 로그 검증이 끝나기 전에는 maxParallelToolCalls를 코어 수에 맞춰 올리지 않는 것이 좋습니다.
현재 로컬 맥이나 단일 클라우드 환경에서 병렬화를 시도하면 공용 작업 공간, 변동하는 자원 여유, 취소 뒤 남은 프로세스를 직접 관리해야 합니다. 장기 실행 작업에서는 이 세 가지가 운영 비용으로 이어지고, 여러 프로젝트가 같은 환경을 공유하면 장애 원인 추적도 어려워집니다. 반대로 단기 실험이나 독립된 검증 작업이라면 새 장비를 구매하기보다 VPSMAC의 서울 맥 노드처럼 별도 환경에서 직렬과 제한 병렬을 비교하는 편이 판단에 유리할 수 있습니다. 다만 지속적인 고정 부하, 물리 장치 접근, 장기 보유 비용이 핵심이면 맥을 직접 운영하는 편이 더 적합할 수 있습니다.
먼저 자신의 기준 작업으로 직렬 실행과 제한 병렬 실행의 작업 공간 차이, 자원 피크, 취소 복구, 로그 귀속을 나란히 기록하십시오. 그 결과 환경 자원이나 작업 공간 격리가 병목으로 확인될 때만 VPSMAC의 독립 맥 환경을 추가하는 순서가 가장 안전합니다.