긴 휴가를 앞두고 인수인계 문서를 쓰던 마지막 하루
3주짜리 긴 휴가를 앞둔 마지막 근무일입니다. 자리를 비우는 동안 다른 팀원이 제 작업을 이어받아야 해서, 정리할 게 한가득이었습니다.
검색해보니 이런 상황에 딱 맞는 표현이 있었습니다.
자리를 비우기 전, 다음 사람에게 상황을 정확히 넘길 때, 핸드오프
markdown
1# 핸드오프 문서2- 진행 상황: 결제 모듈 80% 완료3- 남은 작업: 환불 API 연동4- 막힌 부분: 외부사 문서 응답 대기 중
지금까지 뭘 했고, 뭐가 남았고, 어디서 막혔는지를 다음 사람이 처음부터 다시 헤매지 않도록 정리해서 넘기는 작업이었습니다. 계주에서 바통을 넘길 때 그냥 던지는 게 아니라, 상대가 확실히 잡은 걸 확인하고 손을 떼는 것과 비슷했습니다.
문서를 정리하다가, 그동안 에이전트가 작업하며 남긴 임시 메모 파일이 눈에 들어왔습니다. 다시 열어보니 생각보다 알차게 쓰여 있었습니다.
정식 문서는 아닌데 계속 남아있는 메모 파일, 스크래치패드
text
1scratchpad.md2- 외부사 API 응답 형식이 문서와 다름 (실제로는 배열)3- 테스트 계정 비밀번호는 슬랙 #payment-dev 참고
정식 커밋에는 안 들어가는 이 파일을 다시 읽어보니, 정작 가장 실전적인 정보들이 여기 다 적혀 있었습니다. 공식 문서로 다듬기엔 부담스러운 잡다한 메모를, 나중에 참고하려고 편하게 끄적여두는 임시 노트였습니다. 격식은 없지만 당장 쓸모 있는 정보만 모여 있는, 회의 중 손바닥에 적어두는 메모 같은 파일이었습니다. 이 파일도 핸드오프 문서에 링크로 남겨뒀습니다.
마지막으로 큰 작업 하나를 에이전트에게 넘기려는데, 팀 채널에서 동료가 미리 주의를 줬습니다.
휴가 전 큰 작업을 몰아서 시키면 안 되는 이유, 토큰 버닝
동료가 "그거 지금 통째로 시키면 휴가 중에 한도 다 써버릴 수도 있어"라고 알려줬습니다.
text
1이번 달 사용량: ▓▓▓▓▓▓▓░░░ 72%
대화가 길어지고 작업이 복잡해질수록, 그만큼 처리해야 할 양도 많아져서 정해둔 한도를 그만큼 빠르게 소모하게 됩니다. 같은 목적지라도 어떻게 운전하느냐에 따라 기름이 더 드는 것과 같은 이치였습니다. 큰 작업은 나눠서 맡기기로 하고 일정을 다시 짰습니다.
일정을 다시 짜다가, 예전에 테스트해보려고 만들어둔 브랜치 하나를 열었더니 낯선 경고가 떴습니다.
브랜치 이름이 사라지고 커밋 번호만 뜰 때, 디태치드 헤드
text
1You are in 'detached HEAD' state at a1b2c3d
공식 문서를 찾아보니, 브랜치 이름이 아니라 특정 커밋 하나를 직접 체크아웃했을 때 이런 상태가 된다고 나와 있었습니다.
어느 브랜치에도 속하지 않은 채 특정 지점에만 붙어 있는 상태라, 여기서 커밋을 더 쌓으면 나중에 브랜치를 만들어두지 않는 한 그 기록이 붕 뜬 채로 잊히기 쉬웠습니다. 이름표가 붙은 배가 아니라 부표 하나에 잠깐 매인 상태와 같아서, 서둘러 새 브랜치를 만들어 옮겨뒀습니다.
이 브랜치를 정리하며 원격 저장소 설정을 다시 확인하다가, 예전 동료가 설정해둔 리모트 이름 하나가 눈에 띄었습니다.
원본 저장소를 계속 참고해야 할 때, 업스트림
bash
1$ git remote -v2origin (내 포크)3upstream (원본 저장소)
동료가 예전에 이 오픈소스 라이브러리를 포크해서 쓰면서 설정해둔 원격 저장소 목록을 보다가 궁금해서 찾아봤습니다.
내가 복제해서 쓰는 저장소 말고, 그 원본이 되는 진짜 저장소를 가리키는 이름이었습니다. 원작자가 새 버전을 낼 때마다 이 경로를 통해 최신 내용을 내 쪽으로 받아올 수 있었습니다. 강 상류에서 내려오는 물줄기를 뜻하는 말이 그대로 저장소 이름에 쓰인 셈이었습니다.
마지막으로 커밋 전 상태를 확인하는데,
git status에 계속 뜨던 로그 파일 하나가 신경 쓰였습니다.커밋하고 싶지 않은 파일이 자꾸 따라올 때, .gitignore
bash
1$ git status2Untracked files:3 debug.log4 node_modules/
매번 이 파일들을 무시하고 넘어갔는데, 이번엔 아예 안 보이게 만드는 방법을 찾아봤습니다. 도구가 알려준 대로 파일 하나에 목록을 적어두니 그 뒤로는 다시 안 나타났습니다.
커밋 대상에서 아예 제외하고 싶은 파일이나 폴더 목록을 미리 적어두는 파일이었습니다. 청소 대행 서비스에 "이 방은 건드리지 마세요"라고 미리 표시해두는 것과 비슷했습니다. 이걸로 인수인계 문서 정리가 끝났습니다.
퇴근 직전에야 인수인계 문서를 닫았습니다. 3주 뒤에 이 문서를 읽을 사람이 팀원이 아니라 저 자신일 수도 있겠다는 생각이 들어, 마지막 문단은 남에게 넘기는 글이 아니라 돌아올 저에게 쓰는 글처럼 다시 고쳤습니다.
자주 묻는 질문
핸드오프 문서는 어느 정도 자세히 써야 하나요?
받는 사람이 배경 설명 없이도 바로 이어받을 수 있을 정도가 기준입니다. 특히 막힌 부분과 그 이유는 자세히 적어야, 같은 시행착오를 반복하지 않습니다.
디태치드 헤드 상태에서 실수로 커밋하면 다 사라지나요?
바로 사라지지는 않고 한동안 시스템에 남아있어서 복구할 방법이 있는 경우가 많습니다. 다만 시간이 지나면 정리될 수 있어서, 알아챈 즉시 브랜치를 만들어 옮겨두는 게 안전합니다.
.gitignore에 이미 커밋된 파일을 나중에 추가하면 바로 사라지나요?
아닙니다. 이미 추적 중인 파일은 별도로 추적을 해제하는 명령을 한 번 더 실행해야 합니다. .gitignore는 앞으로 새로 추가될 파일부터 적용됩니다.
<a href="/glossary/code-generation" class="glossary-link" title="AI가 자연어 설명이나 기존 코드 문맥을 바탕으로 프로그래밍 코드를 자동으로 작성하는 기술입니다.">AI 코딩</a> 도구 용어 사전 연작의 11편입니다. 다음 편 예고 · 12편 여러 저장소를 넘나들며 통합 릴리스를 준비하던 날 오케스트레이터 vs 워커 · 델리게이트 · MCP · 포크 · 릴리스 태그 · 서브모듈