Herdr 실행 구조와 병렬 작업 격리: pane과 worktree를 구분하는 방법

Herdr 실행 구조에서 pane을 나누는 건 터미널을 하나 더 여는 일입니다. 병렬로 코드를 고치려면 작업마다 worktree를 만들고, 각 경로에서 에이전트를 실행해야 해요. 두 pane이 같은 작업 디렉터리를 가리키면 에이전트도 같은 파일을 수정할 수 있습니다. 그래서 화면이 몇 개 열려 있는지보다 실제 체크아웃 경로가 어디인지를 먼저 확인하는 편이 좋습니다.

pane, workspace, session, worktree는 각각 무엇을 나누나요

네 가지는 이름이 비슷해서 자주 섞이지만, 나누는 대상이 다릅니다. pane은 터미널이고, workspace는 프로젝트와 작업을 묶는 단위예요. named session은 독립적인 서버로 Herdr 실행 상태를 나누고, worktree는 Git 코드 체크아웃을 분리합니다. 흔히 헷갈리는 지점은 앞의 세 가지예요. workspace나 named session을 따로 만들었다고 해서 코드를 수정하는 공간까지 분리되지는 않습니다.

같은 저장소에서 두 작업을 동시에 진행한다면 작업마다 다른 worktree와 브랜치를 배정하는 구성을 권합니다.

서버, 클라이언트, pane은 어떻게 연결되나요

Herdr는 백그라운드 서버와, 여기에 연결하는 클라이언트로 동작합니다. pane과 프로세스 상태는 서버가 소유하고, 클라이언트는 터미널 UI를 보여 주는 역할만 맡아요. workspace 안에는 화면 배치 단위인 tab과 실제 터미널인 pane이 놓입니다. 에이전트는 이 pane 안에서 실행되는 프로세스로 인식되고요. 이 관계는 공식 Concepts 문서에 정리돼 있습니다.

클라이언트를 detach해도 서버와 에이전트는 계속 실행됩니다.

반대로 herdr server stop으로 서버를 멈추면 세션과 pane도 함께 정지해요. 여기서 구분해야 할 게 있습니다. 나중에 저장된 화면 구성을 복원하는 것과, 기존 프로세스가 계속 살아 있는 것은 같은 일이 아니에요. 작업은 그대로 두고 UI 연결만 끊고 싶다면 서버 중지가 아니라 detach 동작을 보면 됩니다.

named session은 pane, tab, workspace와 socket, runtime state를 따로 유지하지만 전역 설정 파일은 공유합니다. 실행 상태까지 나눌 필요가 있을 때 고르면 되고, 코드 작업이 분리됐는지는 어디까지나 worktree 경로로 확인하세요.

에이전트를 띄우기 전에 경로와 브랜치부터 봅니다

순서는 worktree 생성, 경로 확인, 에이전트 시작으로 잡는 걸 권합니다. 경로 확인을 가운데 두는 이유가 있어요. 기본 설정인 new_cwd = "follow"는 원본 pane이나 workspace의 작업 디렉터리를 이어받고, 명시적인 --cwd가 있으면 그 값이 우선합니다. 새 pane을 열었으니 원하는 작업 경로가 잡혔겠거니 생각하기 쉬운데, 실제로는 원래 있던 디렉터리를 따라갈 수 있다는 뜻이에요.

1. Git workspace에서 New worktree를 선택해 두 작업에 쓸 별도 체크아웃을 만듭니다. 작업마다 서로 다른 로컬 브랜치를 지정합니다. 입력한 브랜치가 있으면 체크아웃하고, 없으면 새로 생성합니다.
2. 각 pane의 실제 작업 디렉터리와 현재 브랜치를 확인합니다. 의도한 worktree를 가리키는지 살펴보고, --cwd를 지정했다면 그 경로도 대조합니다.
3. 대상 pane이 대화형 셸 프롬프트 상태인지 확인한 뒤 agent start를 실행합니다. 해당 경로에서 에이전트가 시작된 것을 확인하고 작업 지시를 전달합니다.

New worktree로 만든 체크아웃은 새 Herdr workspace로 열립니다. 한편 agent start는 이미 있는 shell pane을 대상으로 실행되고, 화면을 분할하거나 레이아웃을 만들어 주지는 않아요. 자동화로 workspace나 tab을 생성한다면 응답에 담긴 root pane ID를 받아 대상으로 쓰면 됩니다. 명령 인자와 pane의 시작 조건은 Agent automation 문서를 기준으로 맞추는 편이 정확해요.

done이 떴다면, 그다음 검토와 정리

done은 에이전트가 작업을 마쳤고 아직 확인하지 않은 상태라는 뜻입니다. 테스트가 통과했는지, 변경 내용이 맞는지까지 판정해 주는 표시는 아니에요. 이 상태를 검토의 출발점으로 삼고, 해당 worktree의 diff와 테스트 결과를 직접 살펴보세요.

자동화에서 agent prompt --wait가 반환될 때도 같은 시선으로 읽어야 합니다. 이 대기는 개별 요청의 완료를 추적하지 않아요. 이미 작업 중인 에이전트에 추가 요청을 보내면 기존 작업이 끝나는 시점에 대기가 풀릴 수 있고, 기본 종료 상태에는 blocked도 들어 있습니다. 그러니 반환 직후에는 에이전트 상태와 실제 변경 결과를 함께 확인하는 게 안전합니다.

정리 단계에서도 화면과 파일을 따로 생각하면 실수가 줄어요. workspace 그룹을 닫아도 체크아웃 폴더와 브랜치는 그대로 남습니다. 체크아웃 삭제는 별도 메뉴에서 git worktree remove로 처리하는데, 이 동작이 브랜치까지 지우지는 않아요. 변경 검토를 마친 뒤 workspace 닫기, worktree 삭제, 브랜치 삭제를 하나씩 따로 판단하세요.

끝으로 worktree가 무엇을 나누는지도 정확히 짚어 둘 필요가 있습니다. HEAD와 index 등은 분리되지만, 일반적인 브랜치 참조와 기본 저장소 설정은 공유해요. 파일 접근 권한을 막아 주는 격리 수단과는 다르다는 점을 염두에 두세요. 실제로 적용하기 전에는 설치된 버전의 명령과 동작을 공식 문서와 대조하고, 생성·정리 동작은 Configuration 문서에서 확인하는 편이 좋습니다.