병렬 작업이 막힐 때

저장소 안에 만든 worktree가 untracked로 나타나 도구를 혼란시킵니다

무엇이 보이는가. git status에 worktree 디렉터리 전체가 커밋되지 않은 변경으로 나타나고, 이 때문에 다른 자동화(머지 전제 조건 검사 등)가 계속 막힙니다.

왜 그런가. worktree를 저장소 내부 경로에 만들면, .gitignore에 그 경로가 없는 한 git은 일반 디렉터리로 취급합니다. 그러면 저장소는 항상 dirty 상태로 보입니다. dirty 상태를 거부하는 절차는 통과할 수 없게 됩니다.

어떻게 확인하는가. git status의 untracked 항목이 worktree 컨테이너 디렉터리 자체인지 확인하십시오. 사용자가 만든 파일이 아니라 worktree 경로 한 줄이 원인인 경우가 많습니다.

어떻게 고치는가. worktree 컨테이너 경로를 커밋되는 .gitignore에 추가하십시오. 로컬 전용 제외 설정(.git/info/exclude)은 다른 머신에서 재발합니다. 메커니즘은 Worktrees를 참고하십시오.

모듈 해석이 worktree 밖 상위 저장소로 올라갑니다

무엇이 보이는가. worktree 안에서 node_modules를 지우거나 격리했다고 생각했는데, 실행된 바이너리나 모듈이 worktree가 아닌 상위 저장소의 것입니다.

왜 그런가. worktree가 저장소 내부 경로에 있으면, Node의 모듈 해석 규칙이 상위 디렉터리로 계속 올라가 상위 저장소의 node_modules를 찾아냅니다. worktree 안에 node_modules가 없다는 사실이 격리를 보장하지 않습니다.

어떻게 확인하는가. 실행 전에 모듈 해석 결과를 직접 확인하십시오(require.resolve 등). 격리를 가정하지 말고, 격리돼 있어야 할 대상이 실제로 해석 실패하는지를 단언하십시오.

어떻게 고치는가. 파괴적이거나 프로덕션에 영향을 줄 수 있는 명령을 테스트할 때는 저장소 밖 완전히 별도인 디렉터리로 복사해 실행하십시오. 상위 디렉터리로 올라가는 해석 경로가 남아 있으면 격리된 것이 아닙니다.

테스트 러너가 worktree 안의 테스트도 함께 수집합니다

무엇이 보이는가. 특정 파일을 지정해 테스트를 돌렸는데, 그 파일에 있는 테스트 개수보다 많은 결과가 나옵니다.

왜 그런가. 테스트 러너는 기본적으로 .gitignore를 존중하지 않습니다. worktree 디렉터리 안에 다른 세션이 만들어 둔 테스트 사본이 있으면, 대상 파일과 무관하게 함께 수집됩니다.

어떻게 확인하는가. 파일당 테스트 수가 기대보다 많은지, 코드에 심어 둔 로그가 안 찍히는지 확인하십시오. 축약된 출력은 경로를 잘라내므로, 전체 출력을 파일로 떨어뜨려 실패 헤더의 전체 경로를 확인하십시오.

어떻게 고치는가. 테스트 러너의 exclude 설정에 worktree 컨테이너 경로를 추가하십시오 (예: **/.claude/worktrees/** 형태의 패턴). .gitignore, 빌드 도구의 무시 설정과 같은 계열로 함께 관리하십시오.

원격 빌드 캐시 오류로 squash commit이 실패합니다

무엇이 보이는가. 테스트와 빌드는 통과했는데, 마무리 단계에서 커밋 자체가 0이 아닌 종료 코드로 실패합니다.

왜 그런가. pre-commit 훅이 원격 빌드 캐시에 접근하는 명령을 실행하는 경우, 그 캐시 서버가 오류를 반환하면 실제 코드 문제가 아니어도 훅 전체가 실패로 끝납니다.

어떻게 확인하는가. 실패 로그에서 원격 캐시 접근 관련 오류(예: HTTP 404)가 있는지 확인하십시오. 테스트·빌드 자체의 오류와 구분하십시오.

어떻게 고치는가. 캐시를 건너뛰는 환경 변수를 마무리 스크립트 앞에 붙여 하위 프로세스에 전파시키십시오. 원인이 캐시 서버라는 것이 확인됐다면, 다음 시도 전에 미리 적용해 두는 편이 안전합니다.

머지가 실패했을 때 어떤 복구가 안전한지 알 수 없습니다

무엇이 보이는가. squash 머지나 마무리 스크립트가 중간에 실패했는데, 재시도해도 되는지 아니면 이미 일부가 반영됐는지 판단이 안 섭니다.

왜 그런가. 실패 시점이 커밋 생성 이전인지 이후인지에 따라 안전한 대응이 다릅니다. 커밋이 이미 만들어진 뒤의 실패는 부분 성공이므로, 처음부터 다시 실행하면 중복이나 충돌을 일으킬 수 있습니다.

어떻게 확인하는가. 실패 로그에 커밋 해시가 이미 출력됐는지 확인하십시오. 커밋 생성 메시지가 있다면 머지 자체는 끝난 것이고, 남은 것은 정리 단계뿐입니다.

어떻게 고치는가. 커밋 이전 실패는 처음부터 재실행해도 안전합니다. 커밋 이후 실패는 재실행하지 말고, 정리 단계만 이어서 수행하십시오. 충돌 마커가 없는 파일에도 의미상 드리프트가 생길 수 있으므로, 머지 직후 상대편 커밋의 변경 통계를 한 번 훑으십시오.

exit-gate 문서를 머지 후에 정리했더니 머지 커밋이 두 개 생겼습니다

무엇이 보이는가. 계획 문서의 체크박스나 로드맵 상태 갱신을 머지 이후 main에서 따로 반영했더니, 같은 작업에 대한 머지 커밋이 두 개가 됐습니다.

왜 그런가. 브랜치를 병합한 뒤 main에 별도로 문서 변경을 추가하면, 그 변경 자체가 또 하나의 머지 이력을 만듭니다. 이를 되돌리는 명령은 저장소 전체에 영향을 주는 파괴적 명령이 될 수 있습니다. 그래서 안전하게 취소하기 어렵습니다.

어떻게 확인하는가. 같은 작업에 대해 머지 커밋이 두 개 이상 있는지 이력을 확인하십시오.

어떻게 고치는가. exit-gate에 해당하는 문서(계획 체크박스, 로드맵 상태)는 병합하기 전에 브랜치 안에서 끝내, 단일 머지로 만드십시오. 병합 후에 따로 반영하지 마십시오.