프로세스 단계 간 작업 인계 방법

"CSV 내보내기는 수정했고, 이제 확인만 남았습니다." 여기서 작업이 멈췄습니다. 다음 날 프로젝트를 열어 보니 어떤 파일을 바꿨는지, 어떤 버전으로 내보내기를 확인했는지, 확인 작업이 어디서 멈췄는지 알 수 없습니다.

같은 조사를 반복하지 않고 이어가려면 다음 단계에 저장된 결과와 확인 내역, 바로 다음에 할 작업이 필요합니다. 하나의 작업을 예로 들어 인계 방법을 살펴보겠습니다. 한 세션이 진행할 수도 있고, 여러 작업자가 나눠 맡거나 여러분이 두 번에 걸쳐 직접 진행할 수도 있습니다.

열어 볼 수 있는 결과를 넘기세요

쇼핑 목록의 CSV 내보내기가 고장 났습니다. 요구사항은 화면에 표시된 항목만 현재 순서대로 내보내는 것입니다. 목록이 비어 있으면 데이터 행은 없이 헤더 행만 남기기로 했습니다. 열 형식과 구분자는 바꾸지 않습니다.

"수정 완료, 확인만 남음"이라고 끝내는 대신, 변경 사항을 찾아 작업을 이어갈 수 있는 기록을 남겨 보겠습니다. 아래 해시와 결과는 설명을 위한 가상의 값입니다. 학습용 예시일 뿐, 실제 실행 결과는 아닙니다.

HANDOFF
목표: CSV에는 현재 순서대로 화면에 표시된 항목만 들어갑니다.
입력 버전: 기준 커밋 4f1c2ab.
인계된 상태: fix-export 브랜치의 커밋 9d3e740, 추가 변경 사항 없음.
결과: src/export-csv.js - 필터링과 정렬 후의 목록을 내보냅니다.
9d3e740에서 수동 확인: 원본 항목 A, B, C; 화면에는 C, A;
  CSV 데이터 행은 C, A이며 B는 없습니다. 헤더는 항목으로 세지 않습니다.
확인하지 않음: 빈 목록, "미완료 항목만" 모드.
결정: 열 형식과 구분자는 변경하지 않습니다.
다음 단계: 기본 세션에서 남은 시나리오 두 가지를 확인합니다.
전체 작업 상태: 확인 미완료.

A, B, C는 목록의 항목 세 개를 나타냅니다. 이 시나리오는 두 가지를 한 번에 확인합니다. 숨겨진 항목 B가 내보내기에 포함되지 않았고, C와 A의 순서가 화면과 일치합니다. 항목이 두 개뿐인 목록에서 두 행을 받았다는 것만으로는 충분하지 않습니다. 필터링하지 않고 내보내도 같은 결과가 나오기 때문입니다.

기록은 HANDOFF.md에 저장하거나 기존 작업 문서에 덧붙일 수 있습니다. 필수 필드 표준은 없습니다. 이전 대화를 볼 수 없더라도 다음 작업자가 필요한 파일과 함께 기록을 열어 볼 수 있어야 합니다.

명령으로 확인했다면 그 명령을 실제 결과, 코드 버전과 함께 적으세요. "12개 중 12개 통과"만으로는 어떤 동작을 확인했는지 알 수 없습니다. 위 예시처럼 수동 시나리오에는 입력 데이터와 동작, 관찰 결과가 필요합니다.

입력 조건과 출력 조건을 정하세요

다음 단계에서 받은 정보가 충분한지 알 수 있을 때 인계가 유용합니다. 이 작업에서는 세 줄로 정리할 수 있습니다.

여기서 핵심은 맨 오른쪽 열입니다. 확인 단계로 넘어갈 때 이 열이 "이제 확인을 시작해도 될까?"라는 질문에 답합니다. 수정 내용이 완전히 설명되어 있어도 잘못됐을 수 있습니다. 확인이 끝난 뒤에도 오류를 발견해 수정해야 할 수 있습니다. 제대로 된 보고서라고 꼭 성공을 알리는 것은 아닙니다.

버전이 적혀 있지 않다면 먼저 현재 파일 상태를 확인하세요. 현재 상태를 검사할 수는 있지만, 대조 없이 예전 보고서를 그 상태에 적용해서는 안 됩니다. 단계마다 별도의 에이전트나 문서가 필요한 것은 아닙니다. 작은 작업은 메모 하나를 두고 한 세션에서 세 단계를 모두 진행할 수 있습니다.

확정된 상태를 보존하세요

인계할 때 서로 다른 세 가지를 혼동하기 쉽습니다.

• 저장된 코드 상태 - 복원할 수 있는 구체적인 버전;
• 작업 진행 메모 - 무엇을 했고, 무엇을 확인했으며, 어떤 사항에 합의했는지;
• 결과 승인 - 작업이 목표에 충분하다고 판단하는 결정.

커밋은 그 안에 저장된 파일을 가리킵니다. 하지만 커밋 이후 추가 변경 사항이 있다면 그 참조만으로는 인계할 상태 전체를 설명할 수 없습니다. 새 파일을 포함해 그 변경 사항도 저장하고 별도로 명시해야 합니다. 변경 사항 묶음을 넘길 때는 비교 기준이 되는 원래 버전도 적으세요. 브랜치 이름만 적는 것으로는 부족합니다. 브랜치는 계속 바뀌기 때문입니다.

기록에는 9d3e740이라고 적혀 있지만 그 뒤에 내보내기 파일이 수정됐다고 해 보겠습니다. 받는 사람은 익숙한 해시를 보지만 실제로는 다른 코드를 다루게 됩니다. 먼저 무엇이 바뀌었는지 확인해야 합니다. 수정이 행의 선택이나 순서에 영향을 줬다면 이전에 확인한 C, A 결과는 현재 동작을 보장하지 않습니다. 주석 문구만 바뀌었다면 그것만으로 시나리오를 다시 실행할 필요는 없습니다.

작은 작업을 하나 마칠 때마다 커밋하거나 자신의 변경과 다른 사람의 변경을 한 커밋으로 모을 필요는 없습니다. 인계할 상태 전체가 존재하고 받는 사람이 접근할 수 있어야 합니다. 저장 방법은 프로젝트 규칙에 따릅니다. 파일이 없다면 먼저 저장된 버전을 확인하세요. 변경 사항이 어디에도 저장되지 않았다면 메모만으로 복원할 수 없습니다.

대화를 재개해도 파일이 설명된 버전으로 돌아가지는 않습니다. Claude Code의 변경 스냅샷도 모든 변경 사항을 담지는 않습니다. Bash를 통한 수정은 추적되지 않고, 다른 작업자의 변경 사항을 복구하는 데도 제한이 있습니다. 그러므로 인계는 저장된 파일과 그 버전을 기준으로 합니다. 자세한 내용은 Checkpointing 문서를 참고하세요.

중단 원인을 파악하세요

"실패했습니다"에는 적어도 세 가지 상황이 있을 수 있습니다.

로컬 실행이 중단됨. 명령이 끝나지 않았거나 확인 작업이 중간에 멈췄습니다. 먼저 어디까지 실행됐고 무엇이 바뀌었는지 확인하세요. 원인을 해결했고 재시도해도 이미 완료된 작업이 중복되지 않는다면 중단된 단계를 다시 실행할 수 있습니다. 이 예시에서는 한 번만 재시도하기로 하겠습니다. 또 중단되면 원인과 계속하는 데 필요한 내용을 기록합니다. 횟수 제한은 작업에 따라 다르며, 무한 재시도로는 아무것도 설명되지 않습니다.

기대 동작이 불분명함. 예를 들어 필터가 켜졌을 때 어떤 행을 표시된 것으로 봐야 하는지 작업자가 모를 수 있습니다. 먼저 기록된 요구사항을 확인합니다. 답이 없다면 요구사항 담당자에게 질문합니다. 수정은 답변을 받은 뒤에 이어갈 수 있습니다. 다시 실행한다고 답이 나오지는 않습니다.

새로운 사실이 확정된 결정을 뒤집음. CSV를 다른 프로그램이 읽는다는 사실을 알게 됐습니다. 요구사항을 다시 구체화한 뒤 다른 열 구성에 합의했고, 순서 요구사항은 철회했습니다. 작업은 요구사항 구체화 단계로 돌아갑니다. 새 기준을 기록하고, 그 기준에 의존하는 수정과 확인을 다시 살펴봐야 합니다. 이전에 통과한 시나리오가 여전히 유용할 수는 있지만, 갱신된 작업 전체를 더 이상 보장하지는 않습니다.

이 경우에는 원래 결정이 바뀌었으므로 요구사항 구체화로 돌아갑니다. 요구사항은 그대로인데 구현에서 오류를 찾았다면 변경 단계로 돌아가면 됩니다. 영향을 받은 결정에 의존하는 결과만 다시 살펴보세요.

현재 지점에서 이어가세요

작업을 재개할 때는 다음 다섯 단계를 거치세요.

1. 확인하지 않은 항목까지 인계 기록 전체를 읽습니다;
2. 인계된 상태를 접근 가능한 파일과 추가 변경 사항에 대조합니다;
3. 중단된 작업이 있었다면 그 결과를 파악합니다;
4. 이전 결과 중 아직 유효한 것을 확인합니다;
5. 바로 다음 미완료 단계를 수행하고 기록을 갱신합니다.

요구사항이 바뀌지 않은 원래 예시로 돌아가 보겠습니다. 다음 세션은 인계 기록을 열고 상태를 대조했습니다. 커밋 9d3e740에 접근할 수 있고 추가 변경 사항은 없으며, 데이터와 확인 조건도 그대로입니다. C, A 시나리오는 이미 완료됐고 결과는 여전히 유효합니다. 수정 작업을 처음부터 다시 할 필요는 없습니다.

이제 받는 사람이 빈 목록을 확인합니다. 요구사항에 따라 CSV에는 데이터 없이 헤더 행만 남아야 합니다. 이 학습 예시에서도 같은 결과가 나왔습니다. 기록에 결과를 추가하고 남은 단계를 바꾸면 됩니다.

9d3e740에서 수동 확인: 빈 목록을 내보내면 헤더만 포함됩니다.
이전에 확인한 C, A 시나리오는 여전히 유효합니다.
확인하지 않음: "미완료 항목만" 모드.
다음 단계: 기본 세션에서 이 모드를 확인합니다.
전체 작업 상태: 확인 미완료.

작업의 진행에 따라 인계 기록도 바뀌었습니다. 남은 시나리오 두 가지 중 하나는 완료했고, 다른 하나는 여전히 남아 있습니다. 부분 결과만으로 원래 목표를 달성한 것은 아닙니다. 확인 작업을 다른 작업으로 옮기려면 범위 변경을 별도로 결정해야 합니다.

실행이 중단되면 해당 시나리오를 처음부터 다시 진행해야 할 수 있습니다. 모든 도구가 중간부터 재개할 수 있는 것은 아닙니다. 완료된 이전 확인은 코드와 입력 데이터, 조건이 유효한 동안 계속 유효합니다.

인계 기록은 누가 작성하나요?

Claude Code는 사실을 정리하고 다음 단계의 입력을 대조하며 이미 합의된 작업을 수행할 수 있습니다. 기록이 파일과 실행 결과에 부합하는지 확인하는 것은 여러분의 몫입니다. 의견이 갈리는 요구사항과 범위 변경은 사람이나 지정된 담당자가 결정합니다. 이 과정에서 최종 승인은 사람이 맡습니다.

저장된 버전은 작업을 이어가는 데 도움이 되지만 작업자의 권한을 넓혀 주지는 않습니다. 내보내기를 확인하라는 요청을 받았다면 복구 지점이 있다고 해서 열 형식까지 바꿔도 되는 것은 아닙니다. 인계 후에도 작업 범위는 그대로 적용됩니다.