Claude Code 터미널과 세션을 안전하게 이어 쓰는 법

한 화면에 보여도 같은 상태는 아닙니다

프롬프트에 “재시도 오류를 조사해 줘”라고 입력하면 대화가 시작됩니다. Claude가 파일을 읽고 테스트를 실행하면 그 결과도 대화 맥락에 들어옵니다. 사용자가 `! git status -sb`처럼 느낌표로 셸 명령을 직접 실행해도 명령과 출력이 현재 세션에 추가됩니다. 화면에서는 모두 위아래로 이어지기 때문에 하나의 작업 기록처럼 보입니다.

하지만 대화와 저장소는 따로 변합니다. 세션을 닫아도 수정한 파일은 디스크에 남고, 반대로 다른 터미널에서 브랜치를 바꾸거나 동료 변경을 가져오면 같은 세션을 재개해도 파일 내용은 달라집니다. 백그라운드 작업도 영구 상태로 보면 안 됩니다. 공식 문서에 따르면 백그라운드 작업은 Claude Code가 종료될 때 정리됩니다. 어제 실행하던 개발 서버나 테스트 감시기가 오늘도 살아 있다고 가정할 수 없습니다.

결제 오류 세션은 수정이 아니라 기준선 확인으로 시작합니다

사건의 조건은 구체적입니다. 첫 승인 요청은 성공하지만 클라이언트가 응답을 받지 못한 경우에만 사용자가 재시도를 누릅니다. 두 번째 요청은 같은 결제 의도를 가리켜야 하며, 새 승인으로 이어지면 안 됩니다. 먼저 Claude Code를 저장소 루트에서 열고 현재 상태를 확인한 뒤 읽기 중심 조사 요청을 보냅니다.

아래 예시는 단축키를 외우게 하기 위한 것이 아닙니다. 목표, 허용 범위, 금지 영역과 성공 조건을 첫 입력에 함께 두면 세션이 길어져도 판단 기준이 남습니다.

터미널에서 먼저 확인
$ pwd
/work/payments-api
$ git status -sb
## fix/payment-retry...origin/main
$ git diff --stat
(출력 없음)

Claude Code에 입력
증상: 승인 응답 유실 뒤 사용자가 재시도하면 승인 요청이 두 번 전송됩니다.
재현: tests/payments/retry.spec.ts의 'lost response' 사례

먼저 수정하지 말고 다음을 조사하세요.
- 재시도 요청에서 idempotency key를 만드는 위치
- 승인 공급자 호출 전후의 저장 순서
- 기존 재시도 테스트가 보장하는 것

허용: 관련 소스와 테스트 읽기, 해당 테스트 실행
금지: 실제 결제 API, 운영 DB, 환경 변수 값 조회, 배포
완료 조건: 수정 전 실패 재현, 최소 원인, 변경 후보와 위험 보고

탐색 결과와 관찰 결과를 분리하면 원인이 보입니다

파일 검색에서는 결제 재시도 함수가 재시도 횟수를 멱등성 키 뒤에 붙이는 코드가 발견됐다고 가정하겠습니다. 첫 요청과 두 번째 요청이 서로 다른 키를 사용합니다. 공급자 입장에서는 서로 다른 키이므로 두 요청을 별개의 승인으로 처리할 수 있습니다. 이것은 코드에서 읽은 관찰입니다.

이어 격리된 공급자 스텁으로 실패 테스트를 실행합니다. 수정 전 관찰은 테스트 실패, 공급자 호출 2회, 서로 다른 키 2개입니다. 이제 “네트워크가 느려 중복 결제가 났다”는 막연한 설명 대신 “동일 결제 의도의 재시도가 새 키를 만든다”는 검증 가능한 원인이 생겼습니다. 운영 결제 API를 호출하지 않았으므로 실제 공급자의 중복 방지 동작은 아직 미검증이라고 남깁니다.

수정과 검증은 같은 세션에서 한 목표로 묶습니다

수정은 재시도 번호를 제거하고 최초 결제 의도에서 생성한 키를 재사용하도록 제한합니다. 회귀 테스트는 응답 유실을 흉내 낸 뒤 두 번째 요청을 보내고, 공급자 스텁이 같은 키를 두 번 받았지만 승인 레코드는 하나만 만들었다고 확인합니다. 정상 결제와 사용자가 새 주문을 만든 경우에는 서로 다른 키가 생성되는 기존 테스트도 함께 실행합니다.

관찰 결과는 “테스트 통과” 한 줄보다 구체적으로 남깁니다. 가상 출력이라면 대상 회귀 테스트 1개가 수정 전 실패하고 수정 후 통과했으며, 예시로 든 결제 모듈 단위 테스트 42개가 통과했고, 실제 공급자 샌드박스와 브라우저 재시도 화면은 실행하지 않았다고 표시합니다. 검증하지 않은 영역과 가상 수치를 적어야 다음 사람이 통과 숫자를 운영 확인으로 오해하지 않습니다.

터미널 조작은 흐름을 돕지만 작업 상태를 대신하지 않습니다

현재 공식 터미널 문서에서 `Ctrl+C`는 입력이나 생성을 취소하고, `Esc`는 진행 중인 응답이나 도구 호출을 중단하는 일반 조작으로 안내합니다. `Ctrl+O`는 도구 사용이 포함된 대화 내용을 펼쳐 확인하고, 입력 맨 앞의 `!`는 셸 명령을 직접 실행해 출력까지 세션에 넣습니다. 종료에는 `Ctrl+D` 또는 `/exit`를 사용할 수 있습니다.

다만 키 조합은 터미널과 플랫폼에 따라 달라질 수 있고 사용자가 재지정할 수도 있습니다. 특히 Option·Alt 계열과 여러 줄 입력은 터미널 설정의 영향을 받습니다. 아티클의 표를 절대값으로 외우기보다 현재 설치판에서 `/help`를 열고, 대화 내용 보기에서는 제공되는 도움말을 확인하는 편이 안전합니다. 중단 키를 눌렀다고 이미 끝난 파일 수정까지 되돌아가는 것도 아닙니다. 중단 뒤에는 `git diff`와 테스트 상태를 다시 봐야 합니다.

퇴근 전 메모는 대화 요약보다 재현 가능해야 합니다

세션은 자동 저장되지만 “월요일의 현재 코드”까지 보존하지는 않습니다. 그래서 금요일 종료 시점에 저장소가 정한 작업 노트나 이슈에 짧은 인계 메모를 남깁니다. 민감한 고객 정보나 실제 결제 식별자는 쓰지 않고, 다른 사람이 같은 명령으로 상태를 확인할 수 있을 만큼만 적습니다.

## 목표
응답 유실 뒤 재시도가 새 승인을 만들지 않게 한다.

## 확인한 원인
재시도 횟수가 idempotency key에 포함돼 같은 결제 의도가 새 요청으로 보였다.

## 변경
- src/payments/retry.ts: 최초 결제 의도의 키 재사용
- tests/payments/retry.spec.ts: 응답 유실 회귀 추가

## 가상 관찰 결과
- 수정 전: 회귀 실패, 공급자 스텁 호출 2회·키 2개
- 수정 후: 회귀 통과, 호출 2회·키 1개·승인 레코드 1개
- 결제 모듈 테스트: 42개 통과

## 남은 검증
공급자 샌드박스와 브라우저 재시도 화면은 미실행

## 재개 기준
저장소 루트에서 브랜치와 변경 차이를 다시 확인한 뒤
npm test -- tests/payments/retry.spec.ts

## 중단 기준
운영 자격증명 또는 실제 승인 호출이 필요하면 진행하지 말고 승인 요청

최근 세션 재개가 잘못된 브랜치로 이어진 사례

월요일에 같은 저장소 경로에서 `claude --continue`를 실행하면 그 디렉터리의 가장 최근 세션을 이어 갑니다. 문제는 금요일 뒤 다른 사람이 이 경로에서 문서 작업 세션을 열었을 수 있다는 점입니다. “결제 얘기가 안 보인다”면 대화가 사라진 것이 아니라 가장 최근 세션의 기준이 달라진 것입니다. 이때 새 대화에 기억을 추측하게 하지 말고 `claude --resume`으로 선택 화면을 열어 이름, 요약, 시각과 브랜치를 보고 고릅니다. 중요한 작업은 세션에 알아볼 수 있는 이름을 붙여 검색하기 쉽게 만드는 것도 도움이 됩니다.

올바른 결제 세션을 선택해도 즉시 수정을 계속하면 안 됩니다. 이 사례에서는 월요일 현재 기본 브랜치에 있으며 작업 파일은 깨끗하고, 원격에는 동료가 결제 응답 모델을 바꾼 커밋이 추가됐습니다. 대화 속 “재시도 처리 파일만 고치면 된다”는 금요일의 결론은 현재 코드에 그대로 적용할 수 없습니다. 먼저 현재 위치, 브랜치, 변경 파일과 원격 차이를 확인하고, 종료 메모의 재현 테스트를 다시 실행한 뒤 변경안을 조정해야 합니다.

재개할 때 세 가지가 맞지 않으면 멈춥니다

첫째, 디렉터리나 브랜치가 종료 메모와 다르면 멈춥니다. 세션 선택을 다시 확인하거나 올바른 작업 공간으로 이동합니다. 둘째, 관련 파일에 예상하지 못한 사용자 변경이나 원격 변경이 있으면 덮어쓰지 않습니다. 현재 변경의 의도와 충돌 지점을 보고한 뒤 통합 방식을 정합니다. 셋째, 재현 테스트가 더는 같은 방식으로 실패하지 않으면 과거 원인을 그대로 고치지 않습니다. 문제가 이미 해결됐는지, 테스트 환경이 바뀌었는지부터 조사합니다.

운영 자격증명, 실제 승인 요청, 데이터 수정이나 배포가 필요해지는 순간도 중단선입니다. 세션에서 이전에 받은 일회성 허용이나 오래된 합의가 오늘의 운영 작업을 자동 승인하지 않습니다. 공식 문서에서도 세션을 분기하면 세션 단위로 허용한 권한은 새 분기로 따라오지 않는다고 설명합니다. 이 제약은 불편이 아니라 오래된 맥락이 새 외부 효과를 승인하지 못하게 하는 안전장치입니다.

세션의 역할은 기억이 아니라 조사 경로를 잇는 것입니다

좋은 재개는 어제의 답을 그대로 이어 쓰는 일이 아닙니다. 어떤 증상에서 출발했고, 무엇을 관찰했으며, 어느 검증까지 통과했는지를 되살린 뒤 오늘의 저장소에서 다시 확인하는 일입니다. 대화 기록은 왜 그 결론에 도달했는지를 보여 주고, Git과 테스트는 그 결론이 지금도 유효한지를 보여 줍니다.

결제 재시도처럼 영향이 큰 작업에서는 세션 하나에 목표 하나를 두는 편이 좋습니다. 도중에 “관리자 화면도 고쳐 달라”는 요청이 들어오면 같은 대화에 섞지 않고 별도 작업으로 나눕니다. 종료 시에는 다음 세션이 추측 없이 재현할 수 있는 메모를 남깁니다. 이 원칙만 지켜도 터미널의 편리한 연속성을 저장소 상태에 대한 잘못된 확신으로 바꾸는 실수를 크게 줄일 수 있습니다.

처음 여는 세션에는 종료 조건까지 적습니다

다음은 결제 재시도 오류를 읽는 세션 예시입니다. 현재 파일과 Git 상태를 먼저 확인하되 운영 결제는 호출하지 않습니다.

cd /path/to/project
claude --permission-mode plan

CLAUDE.md, 결제 재시도 서비스, 관련 테스트를 읽으세요.
현재 브랜치와 변경 파일을 확인하고 코드는 수정하지 마세요.
허용 도구: Read, Glob, Grep, 승인한 git status와 테스트 조회
반환 형식: 재현 조건 / 읽은 파일 / 가설 / 수정 후보 / 검증 명령 / 종료 메모 초안

계획을 승인한 뒤 한 가설만 실행합니다

계획에서 재시도 키 재사용 가설만 남았다면 그 가설을 깨는 실패 테스트부터 만듭니다. 수정 파일은 결제 서비스와 해당 테스트로 제한하고 외부 승인망은 호출하지 않습니다. 조사 중 발견한 다른 결함은 현재 변경에 섞지 않고 파일 위치와 재현 단서만 남깁니다.

재개 직후에는 대화보다 저장소를 확인합니다

검증과 변경 차이를 확인하고 종료 메모에 실제 명령 결과를 남깁니다. 다음 날 재개해도 같은 명령을 먼저 반복합니다.

git status --short
git branch --show-current
npm test -- payment
git diff -- src/payments tests/payment

세션 기록을 믿고 진행하지 않을 때

브랜치, 기준 커밋, 동료 변경이 종료 메모와 다르면 중단하고 현재 코드를 다시 읽습니다. 같은 가설과 파일 범위라면 재개할 수 있지만 다른 결제 장애나 배포 작업은 새 세션으로 분리합니다.

세션은 길게 유지하기보다 이름 붙여 다시 연다

작업 목표가 분명할 때 `/rename`으로 세션을 식별하고, 중단한 작업은 `/resume`으로 찾습니다. 주제가 바뀌면 `/clear`로 새 컨텍스트를 시작하고, 같은 목표에서 기록만 길어졌다면 `/compact`로 핵심을 압축합니다. 한 세션에 서로 다른 프로젝트를 계속 붙이는 방식은 비용과 오판 가능성을 함께 키웁니다.

`/usage`는 사용량 점검, `/insights`는 로컬 작업 습관을 돌아보는 데 쓸 수 있습니다. 다만 두 결과 모두 완전한 조직 청구 명세가 아닙니다. 중요한 결정과 인계 정보는 세션 기록에만 남기지 말고 저장소 문서나 팀이 공식 기준으로 삼는 문서에 옮깁니다.