2026 DeepSeek Harness 병렬 코드 수정: Git worktree인가 독립 클론인가?

DeepSeek Harness 여러 세션이 같은 저장소를 사용할 수는 있습니다. 다만 세션마다 작업 공간 경로, 브랜치, 작업 목적, 종료 조건을 고정해야 합니다. 공식 저장소는 DeepSeek Harness가 개발자 미리 보기 단계이며 호환성이 빠르게 바뀔 수 있다고 안내합니다. 따라서 Harness가 자동으로 worktree를 만들고 세션을 연결하거나 회수한다고 가정해서는 안 됩니다. DeepSeek Harness 공식 저장소

작업 계약에는 최소한 다음 항목을 기록합니다.

• 작업 소유자와 실행 세션 식별자
• 기준 브랜치와 작업 브랜치
• 전용 작업 공간 경로
• 수정 허용 범위와 읽기 전용 경로
• 테스트 명령과 빌드 산출물 경로
• 커밋·검토·병합을 담당할 사람
• 취소 또는 실패 시 보존할 로그와 파일

코드 수정 작업은 반드시 작업 공간을 독점해야 하나요?

파일을 직접 수정하는 작업은 독점 worktree를 배정하는 것이 기본입니다. 읽기 전용 분석은 같은 클론을 참조해도 되지만, 분석 과정에서 색인 파일이나 임시 설정을 바꾸는 도구라면 별도 worktree가 필요합니다. 테스트 실패를 고치는 작업은 기존 변경 사항을 덮어쓸 가능성이 높으므로 독립 브랜치와 독립 경로를 함께 배정해야 합니다.

동일 파일을 여러 세션이 반복해서 수정하거나, 한 작업의 인터페이스 변경이 다른 작업의 입력을 즉시 바꾸는 경우에는 디렉터리만 나누어도 충돌 위험이 사라지지 않습니다. 이때는 관련 작업을 먼저 직렬 실행하고, 앞선 작업의 커밋 또는 검토 결과를 다음 세션의 기준점으로 삼아야 합니다.

Git worktree는 하나의 저장소에 여러 작업 트리를 붙이는 방식입니다. Git 공식 문서에 따르면 각 worktree의 HEAD와 index는 작업별로 유지되지만, 저장소 객체와 일반 refs는 공유됩니다. 기본 저장소 설정도 공유될 수 있으므로, worktree는 코드 체크아웃을 나누는 기능이지 완전한 실행 샌드박스가 아닙니다. Git 사용자 매뉴얼

개인 개발자의 기준은 간단합니다.

• 같은 저장소
• 짧은 수명의 작업
• 동일한 권한 수준
• 서로 다른 파일 또는 충돌 가능성이 낮은 변경
• 공용 의존성을 사용해도 되는 개발 환경

이 조건이면 작업별 브랜치를 만들고 worktree를 배정하는 편이 적합합니다. 예시는 다음과 같이 경로를 고정해 사용할 수 있습니다.

git worktree add -b <branch-a> <path-a> <base-branch>
git worktree add -b <branch-b> <path-b> <base-branch>
git worktree list --porcelain

각 DeepSeek Harness 세션은 <path-a> 또는 <path-b> 중 하나만 사용해야 합니다. 세션 설명에 브랜치와 경로를 함께 넣고, 셸 시작 단계에서 현재 위치와 브랜치를 확인하도록 하면 잘못된 작업 공간에서 수정하는 사고를 줄일 수 있습니다.

그러나 다음 항목은 worktree 사이에서 자동으로 분리되지 않습니다.

• 저장소의 공용 객체와 일반 참조
• 기본 저장소 설정
• 별도로 지정하지 않은 패키지 의존성 디렉터리
• 공용 빌드 출력 폴더
• 개발 서버의 포트
• 운영 중인 백그라운드 프로세스
• 사용자 홈 디렉터리에 저장된 자격 증명과 토큰

worktree별 설정이 필요하면 Git의 extensions.worktreeConfig와 config.worktree를 검토할 수 있습니다. 다만 설정을 전환하기 전에 core.worktree, core.bare, 희소 체크아웃 관련 값이 공용 설정에 남아 있는지 확인해야 합니다. Git 설정 공식 문서

팀 환경에서는 “폴더가 분리되어 있으니 안전하다”는 판단만으로 부족합니다. 작업이 끝난 뒤 누가 변경을 검토하고 어느 브랜치에 병합할지 정하지 않으면, 세션이 정상적으로 종료되어도 통합 단계에서 충돌이 발생합니다.

작업 유형별로 다음처럼 권한을 나누는 편이 좋습니다.

• 코드 수정: 독립 worktree, 독립 브랜치, 커밋 책임자 지정
• 읽기 전용 분석: 원본 또는 별도 worktree 사용, 파일 변경 명령 차단
• 테스트 수정: 테스트용 산출물과 임시 디렉터리 분리
• 대규모 구조 변경: 관련 모듈 담당자 승인 후 직렬 실행
• 공통 설정 변경: 한 세션만 수정하고 다른 세션은 결과를 기다림

병렬 Agent의 브랜치 충돌을 어떻게 줄일 수 있나요?

브랜치 이름보다 작업 계약이 중요합니다. 각 세션에 수정 파일 목록과 금지 영역을 전달하고, 공통 설정 파일이나 잠금 파일을 건드리는 작업은 별도 순서로 배치해야 합니다. 동일 파일에 대한 수정 빈도가 높거나, 한 작업이 다른 작업의 타입·인터페이스·의존성 버전을 바꾸는 경우에는 병렬 실행을 중단하고 직렬 흐름으로 바꾸는 것이 낫습니다.

병합 전에는 각 worktree에서 변경 상태를 확인합니다.

git status --short
git diff --check
git log -1 --oneline
git branch --show-current

작업 계약에 없는 파일이 나타나면 즉시 세션을 중지하고, 자동 병합을 진행하지 않아야 합니다.

worktree는 저장소 파일을 나누지만, 패키지 설치 위치와 빌드 시스템의 캐시까지 자동으로 분리하지 않습니다. 예를 들어 여러 작업이 같은 의존성 디렉터리의 잠금 파일을 갱신하거나, 하나의 빌드 폴더를 비우고 다시 생성하면 코드 작업 공간이 달라도 결과가 서로 영향을 받을 수 있습니다.

공유해도 되는 것은 검증된 읽기 전용 다운로드 캐시입니다. 패키지 파일을 다시 내려받는 비용만 줄이고, 실행 중인 산출물을 직접 덮어쓰지 않는 구조여야 합니다. 반대로 다음 경로는 작업별로 나누는 것이 안전합니다.

<task-root>/<task-id>/build
<task-root>/<task-id>/tmp
<task-root>/<task-id>/logs
<task-root>/<task-id>/artifacts

개발 서버와 테스트 서비스도 작업별 포트를 받아야 합니다. 포트 충돌은 Git 충돌로 표시되지 않으므로, 세션이 “빌드 성공”이라고 보고해도 실제로는 다른 작업의 서버에 연결했을 가능성이 있습니다.

주의: Git worktree를 샌드박스로 취급하면 안 됩니다. 코드 경로는 나뉘어도 프로세스, 홈 디렉터리, 키 체인, 환경 변수, 네트워크 접근 권한은 그대로 공유될 수 있습니다.

여러 worktree가 의존성 캐시를 함께 사용해도 안전한가요?

캐시가 읽기 전용이고 캐시 무효화와 잠금 규칙이 명확하면 공유할 수 있습니다. 그러나 설치 과정에서 캐시 내용을 변경하거나, 도구가 캐시 폴더 안에 임시 파일과 상태 파일을 쓰면 작업별 경로로 옮겨야 합니다. 의존성 재현성이 중요한 고객 프로젝트라면 공유 캐시보다 독립 클론과 작업별 설치 경로를 우선해야 합니다.

원격 맥에서 자동화할 때는 다음 순서를 고정하는 것이 좋습니다.

1. 기준 저장소와 기준 커밋을 확인합니다.
2. 작업 아이디와 브랜치 이름을 생성합니다.
3. git worktree add로 전용 경로를 만듭니다.
4. 세션 아이디와 경로를 한 쌍으로 기록합니다.
5. 의존성, 빌드, 임시 디렉터리와 포트를 작업별로 연결합니다.
6. 실행 전 브랜치와 경로를 다시 검사합니다.
7. 종료 후 변경 파일, 실행 중 프로세스, 산출물, 로그를 확인합니다.
8. 깨끗한 경우에만 git worktree remove <path>를 실행합니다.
9. 경로를 직접 삭제했다면 git worktree list --porcelain과 git worktree prune -n으로 메타데이터 상태를 점검합니다.
10. 회수가 완료된 뒤에만 세션 기록과 임시 자격 증명을 폐기합니다.

Git은 깨끗하지 않은 worktree를 기본적으로 제거하지 않으며, 강제 제거에는 --force가 필요합니다. 작업 트리를 직접 삭제하면 저장소 내부의 관리 정보가 남을 수 있으므로, 단순히 디렉터리가 사라졌다는 이유로 회수가 끝났다고 판단하면 안 됩니다. Git worktree 제거·정리 문서

회수 실패 시에는 다음 조건을 만족할 때 사람에게 넘깁니다.

• 추적되지 않은 파일이나 미커밋 변경이 남아 있음
• 실행 중인 빌드 또는 서버 프로세스를 확인하지 못함
• 작업 계약에 없는 자격 증명이나 고객 파일이 발견됨
• worktree 관리 정보와 실제 경로가 서로 다름
• 강제 제거를 해야 하지만 산출물 보존 여부가 불명확함

이때는 로그, 변경 목록, 마지막 커밋, 프로세스 목록을 보존하고 강제 삭제를 지연해야 합니다. Git은 수동으로 이동되거나 손상된 worktree를 repair로 다시 연결할 수 있지만, 복구 가능성을 확인하기 전에는 원본 메타데이터를 임의로 지우지 않는 편이 안전합니다. Git 저장소 구조 문서

worktree는 버전 관리 작업 공간의 충돌을 줄이는 도구입니다. 사용자 신원, 비밀 키, 고객 데이터, 네트워크 권한까지 분리하지는 않습니다. 다음 조건 중 하나라도 해당하면 독립 클론을 검토해야 합니다.

• 고객별 저장소와 내부 저장소를 같은 계정에서 다룸
• 세션별 접근 가능한 키 또는 토큰이 다름
• 서로 다른 권한 등급의 Agent가 같은 맥을 사용함
• 저장소 외부의 설정과 데이터까지 작업에 포함됨
• 빌드 도구가 홈 디렉터리나 전역 캐시를 수정함

더 강한 분리가 필요하면 독립 macOS 계정이나 독립 Mac 환경을 사용해야 합니다. 독립 클론은 저장소와 의존성 경로를 나누는 선택이고, 독립 환경은 프로세스·자격 증명·파일 접근·네트워크 경계를 함께 나누는 선택입니다.

장기 AI 코딩 작업에도 Git worktree가 적합한가요?

짧은 기능 수정, 검토용 패치, 임시 테스트에는 적합합니다. 반면 장기간 실행되는 Agent가 큰 빌드 산출물과 전역 캐시를 계속 생성하거나, 작업 종료 시점을 예측하기 어렵다면 독립 클론 또는 독립 환경이 관리하기 쉽습니다. worktree의 공유 구조를 계속 감시해야 하므로, 디스크 절약만 보고 장기 작업에 적용해서는 안 됩니다.

다음 기준으로 선택하면 일률적으로 한 가지 구조를 고르는 실수를 줄일 수 있습니다.

• Git worktree: 같은 저장소, 같은 신뢰 경계, 짧은 작업, 공유 가능한 읽기 전용 캐시
• 독립 클론: 의존성 설치와 빌드 산출물을 나눠야 하거나, 저장소 운영 상태를 서로 간섭시키면 안 되는 작업
• 독립 환경: 고객 데이터, 권한, 자격 증명, 프로세스와 네트워크까지 분리해야 하는 작업

선택 전에 두 개의 폐기 가능한 브랜치로 다음 검증을 완료합니다.

• [ ] 각 세션이 서로 다른 worktree 경로와 브랜치에 연결되는지 확인합니다.
• [ ] 한 세션이 파일을 수정하는 동안 다른 세션의 git status가 오염되지 않는지 확인합니다.
• [ ] 의존성 설치와 빌드 산출물이 작업별 경로에 생성되는지 확인합니다.
• [ ] 서로 다른 포트에서 테스트 서비스가 실행되는지 확인합니다.
• [ ] 한 세션을 취소해도 다른 세션의 프로세스가 중단되지 않는지 확인합니다.
• [ ] 미커밋 파일이 남았을 때 자동 회수가 중단되는지 확인합니다.
• [ ] 정상 종료 후 git worktree list --porcelain에 오래된 관리 항목이 남지 않는지 확인합니다.
• [ ] 고객 또는 권한이 다른 작업에서는 독립 클론이나 독립 환경으로 분리되는지 확인합니다.

기존 맥에서 이 검증을 수행할 공간과 프로세스 여유가 부족하다면, 원격 맥 환경 안내와 클라우드 맥 동시 실행 계획을 먼저 확인하는 편이 좋습니다. 장기 점유가 예상되면 맥 미니 렌탈 가격 안내와 비교해 작업별 환경을 임시로 분리할 수 있는지 판단할 수 있습니다.

현재 환경이 하나의 디렉터리와 하나의 계정만 제공한다면 파일 덮어쓰기, 공용 빌드 캐시 오염, 백그라운드 프로세스 회수 실패가 반복될 수 있습니다. 고객 프로젝트까지 같은 환경에서 처리하면 자격 증명 회수와 책임 추적도 복잡해집니다. 따라서 두 개의 단기 작업으로 먼저 회수 절차를 검증하고, 기존 Mac이 독립 작업 공간을 제공하지 못하거나 작업이 오래 점유될 때는 NUKCLOUD의 원격 맥 환경을 비교해 보는 것이 현실적인 다음 단계입니다.