DeepSeek Harness Worktrees: 첫 실행 가이드

에이전트가 이미 편집 중인 파일을 이동하지 않고 변경 사항을 시도하려는 경우 별도의 체크아웃이 유용합니다. DeepSeek Harness dsh-v0.2.1-alpha.2(2026 년 10 월 9 일 릴리스) 는 이러한 작업을 위한 실험용 Git Worktrees 플러그인을 추가합니다. 이 플러그인은 브랜치와 체크아웃을 생성한 후 호출 세션의 작업 디렉토리를 변경합니다.

이 튜토리얼은 버전 고정 플러그인 가이드 를 사용하여 작은 작업으로 동작을 확인합니다. 워크트리를 생성하고 문서 변경 사항을 하나 만든 후 검사한 뒤 원래 디렉터리로 돌아오는 과정입니다. 이는 문서 기반 워크플로우이며, Harness 데스크톱 애플리케이션을 테스트했다는 주장이 아닙니다. 코드 형태의 도구 예시는 에이전트 호출을 설명하며, 셸에 붙여넣는 명령어가 아닙니다.

플러그인 활성화 전 저장소 확인

테스트용 저장소나 현재 변경 사항을 이해하고 있는 프로젝트를 사용하세요. 워크트리 런타임 요구 사항 은 파일시스템 제공자가 사용하는 실행 환경에서 Git 2.45 이상과 Node 를 지정합니다. 원격 환경의 경우 노트북의 버전만으로는 해당 요구 사항이 충족되었는지 확인할 수 없습니다.

저장소 루트, 현재 브랜치, 현재 커밋 및 짧은 Git 상태를 요청하는 것으로 시작하세요. 이러한 읽기 전용 셸 명령어가 기본 검사를 제공합니다.

git --version
node --version
git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status --short

빈 브랜치 이름은 분리된 HEAD(detached HEAD) 를 의미할 수 있으므로 브랜치를 임의로 생성하지 말고 이를 기록하세요. 상태가 비어 있지 않다고 해서 자동으로 실패한 것은 아니지만, 커밋된 베이스라인 외에 일부 작업이 존재함을 의미합니다. 새 작업에 이러한 변경 사항이 필요한지 결정하세요. 필요하다면 워크트리가 이를 복사할 것이라고 가정하지 말고 먼저 적절한 커밋을 준비하세요.

플러그인은 스테이징된, 스테이징되지 않은, 추적되지 않거나 무시된 파일을 복사하지 않습니다. 따라서 소스 체크아웃이 성공적으로 실행되더라도 의존성, 로컬 환경 파일 및 생성된 결과물이 없을 수 있습니다.

직접 제작한 도식: 01은 원본 체크아웃, 02는 새 브랜치 체크아웃입니다. 커밋된 README는 사용 가능하지만 별표로 표시한 미커밋 메모는 복사되지 않습니다.

이 다이어그램은 문서화된 복사 경계를 나타내며 애플리케이션 스크린샷이 아닙니다. 두 체크아웃은 공유 Git 관리를 사용하며, 별도의 파일이 히스토리를 독립적으로 만들지는 않습니다.

Git Worktrees 활성화 및 작은 작업 선택

Plugins → Official → Git Worktrees 를 열고 스위치를 활성화하세요. 고정된 플러그인 가이드에 따르면 옵션 번들은 모든 제공 프로필에서 꺼져 있습니다. 이는 워크트리 런타임과 생성 도구를 함께 로드합니다.

첫 작업은 요청 범위를 작게 잡으세요. 문서 수정을 위한 워크트리를 생성하고 디렉토리와 베이스라인을 표시한 후 편집 전에 대기하세요. docs-worktree-trial 과 같이 새롭고 사용하지 않는 브랜치 이름을 요청하세요. 동일한 이름이 상대 체크아웃 디렉토리에 사용되므로 짧고 의미가 분명한 이름을 쓰면 나중에 찾기 쉽습니다.

생성 호출은 다음과 같은 형태입니다.

create_worktree({ name: "docs-worktree-trial", from: "HEAD" })

from 은 로컬에서 해결되어야 합니다. 호스팅 웹사이트에서 보이는 원격 브랜치 이름은 이 저장소에서 객체를 사용할 수 없다면 충분하지 않습니다. 이 작업은 누락된 객체를 가져오거나, 서브모듈을 초기화하거나, 패키지를 설치하지 않습니다. 생성 실패를 재시도하기 전에 부족한 선행 조건부터 확인하고 처리하세요.

Start using DeepSeek Harness

변경 사항 작성 전 반환된 디렉토리 검증

성공적인 호출은 path, branch, baseCommit 및 repositoryRoot 를 반환합니다. 이 네 가지 값을 함께 유지하세요. 하위 시스템 참조 는 세션이 디렉토리를 변경하기 전에 Git 설정이 완료됨을 지정합니다.

기본 대상은 현재 체크아웃 아래의 .agents/worktrees/<name> 에 있습니다. 세션이 연결된 체크아웃에서 시작되면 해당 체크아웃이 새 풀의 소스 루트가 됩니다. 반환된 표준 경로 대신 다른 세션에서 기억한 경로를 대체하지 마세요.

반환된 필드	검증 내용
`path`	세션이 이제 이 체크아웃에 있음
`branch`	요청한 새 브랜치임
`baseCommit`	의도된 로컬 시작 리비전임
`repositoryRoot`	시작한 체크아웃을 식별함

에이전트에게 현재 디렉토리에서 루트, 브랜치 및 커밋 검사를 다시 실행하도록 요청하세요. 이를 생성 결과와 비교하세요. 일반 저장소는 의도된 시작 콘텐츠를 가져야 하지만, 런타임은 저장소 로컬 대체 참조가 체크아웃된 콘텐츠에 영향을 줄 수 있다고 명시합니다. 커밋 식별자만으로는 변경하려는 파일 검사를 대체하지 않습니다.

하나의 편집 수행 및 diff 검사

기존 README 단락을 선택하고 사실관계를 한 가지 보충하도록 요청하세요. 의존성 업그레이드나 저장소 전체 포매터로 시작하지 마세요. 이러한 것은 디렉토리 실수를 발견하기 어렵게 만드는 큰 diff 를 생성합니다.

편집 후 현재 브랜치 및 변경 사항을 검사하세요.

git branch --show-current
git status --short
git diff --check
git diff -- README.md

작업이 다른 파일을 변경한다면 실제 파일 이름을 사용하세요. 마지막 명령어는 스테이징되지 않은 변경 사항을 보여줍니다. 에이전트가 편집을 스테이징했다면 스테이징된 diff 도 검사하세요. 깔끔한 git diff --check 는 공백 오류만 확인합니다. 단락이 정확하거나 프로젝트가 빌드됨을 보장하지는 않습니다.

변경 사항에 필요한 경우 가장 작은 관련 프로젝트 검사를 실행하세요. 명령어, 디렉토리 및 결과를 기록하세요. 문서 전용 변경 사항의 경우 관련 없는 테스트 스위트 실행보다 렌더링된 텍스트를 읽는 것이 더 유용할 수 있습니다.

직접 제작한 절차도: 01 생성, 02 반환 필드 네 개 확인, 03 편집, 04 변경 사항 검토, 05 복귀. 나가도 체크아웃과 브랜치는 남습니다.

번호가 매겨진 경로는 연습 과정을 따릅니다. 생성, 검증, 편집, 검사, 종료. 유지된 브랜치와 디렉토리는 여전히 통합 또는 정리에 대한 후속 결정이 필요합니다.

원래 디렉터리로 돌아가고 검토 기록 남기기

반환하려면 에이전트에게 원래 절대 체크아웃 경로로 working_directory 를 호출하도록 요청하세요. 예를 들어, 샘플 경로를 기록된 repositoryRoot 로 대체합니다.

working_directory({ cd: "/absolute/path/to/original-checkout" })

현재 디렉토리를 다시 검증하세요. 종료한다고 해서 변경 사항을 병합하거나 체크아웃을 제거하거나 브랜치를 삭제하는 것은 아닙니다. Git Worktrees 플러그인을 비활성화해도 기존 워크트리는 그대로 유지되며, 내장 작업 디렉토리 도구는 계속 사용할 수 있습니다.

통합 방법을 결정하기 전에 diff 를 검토하세요. 일반 저장소 워크플로우에 따라 커밋 및 병합 또는 체리픽하세요. 체크아웃이 더 이상 필요하지 않을 때 상태를 검사하고 변경 사항을 보존한 후 Git 의 일반 워크트리 제거 프로세스를 사용하세요. 미커밋 변경 사항이 있다는 이유로 곧바로 강제 삭제하지 마세요.

브랜치를 반복적으로 생성하지 않고 오류 진단

기존 브랜치 또는 체크아웃 경로는 오류를 발생시킵니다. 특히 취소 후 다른 이름을 시도하기 전에 이미 존재하는 것을 검사하세요. 설정 실패는 부분적인 산출물을 남기고 위치를 보고할 수 있습니다. 이름을 반복적으로 생성하면 유지하려는 작업이 포함된 체크아웃이 무엇인지 모호해질 수 있습니다.

권한 오류는 다릅니다. 생성에는 기존 샌드박스 정책이 대상 및 공유 Git 메타데이터에 대한 쓰기를 허용해야 합니다. 플러그인은 이러한 권한을 넓히지 않습니다. 구성을 변경하기 전에 거부된 위치를 식별하세요.

마지막으로, 저장된 Git LFS 포인터 또는 암호화된 블롭은 체크아웃이 구성된 clean, smudge 및 process 필터를 건너뛰기 때문에 확장되지 않은 상태로 남을 수 있습니다. 실제 파일 다운로드나 복호화를 별도의 작업으로 취급하세요. 체크아웃은 유효할 수 있지만 작업에 필요한 실행 가능한 환경이 여전히 부족할 수 있습니다.

검토된 diff 및 검사 결과와 함께 반환된 4 개 필드 기록을 유지하세요. 이는 에이전트가 어떤 디렉토리나 베이스라인을 사용했는지 추측하지 않고 연습을 재개하기에 충분한 컨텍스트입니다. 더 넓은 릴리스 및 SDK 변경 사항에 대해서는 alpha.2 업그레이드 가이드 를 참조하세요.