세 개를 구분해야 Claude Code가 제대로 돌아간다
Claude Code를 쓰다 보면 이름이 비슷한 개념들 때문에 헷갈리기 쉽다. Plan Mode와 plan.md는 다르고, plan.md와 handoff.md도 다르다. 셋의 역할을 명확히 구분하면 긴 작업도 세션이 끊겨도 흔들리지 않는다
Plan Mode – Claude의 실행 상태
Shift + Tab으로 전환하는 Plan Mode는 Claude Code의 동작 방식이다. 이 모드에서는 Claude가 파일을 실제로 수정하지 않는다. 코드베이스를 분석하고 어떻게 구현할지 계획만 출력하는 “읽기 전용 실행 상태”다
구현 전에 방향이 맞는지 확인할 때 쓴다. 계획이 마음에 들면 실행 모드로 전환해서 구현을 진행한다
단점이 하나 있다. 세션이 끝나면 사라진다. Plan Mode로 세운 계획은 대화창 안에만 존재한다
plan.md – 계획을 보존하는 파일
plan.md는 그냥 파일이다. Plan Mode로 세운 계획이든 사람이 직접 작성한 내용이든, “이번 작업에서 무엇을 어떻게 할지”를 기록해두는 텍스트 파일이다
파일이기 때문에 세션이 끊겨도 사라지지 않는다. 새 세션에서 plan.md를 읽으면 이전 계획을 그대로 이어받을 수 있다
Plan Mode와 plan.md는 함께 쓸 때 가장 효과적이다
Plan Mode로 계획 수립
↓
계획 내용을 plan.md에 저장
↓
세션이 끊겨도 plan.md는 파일로 남음
↓
새 세션에서 plan.md를 읽고 이어서 작업
Plan Mode는 어떻게 생각할지를 제어하고, plan.md는 그 결과를 보존한다
handoff.md – 작업 결과를 다음으로 넘기는 파일
handoff.md는 작업이 끝난 후 “무엇이 바뀌었고 무엇이 남았는지”를 기록하는 파일이다. 내일의 나, 또는 다음 세션의 Claude를 위한 인수인계 문서다
# Handoff ## 완료한 작업 - 회원가입 폼 빈 값 제출 버그 수정 - signup.test.ts 회귀 테스트 추가 ## 변경된 파일 - src/features/signup/SignupForm.tsx - tests/signup.test.ts ## 테스트 결과 - pnpm test -- signup: 통과 - pnpm lint: 통과 ## 남은 위험 - 이메일 중복 처리 로직 미검증 - 모바일 레이아웃 미확인
긴 작업이나 팀 협업에서 특히 중요하다. 세션을 새로 시작할 때 handoff.md를 먼저 읽으면 이전 작업 결과를 다시 설명하지 않아도 된다
세 개를 함께 쓰는 실전 흐름
작업 A 시작 → Plan Mode로 계획 수립 → 계획을 plan.md에 저장 → accept edits 모드로 전환해 구현 → 완료 후 handoff.md에 결과 기록 → /clear 또는 Ctrl+C로 세션 종료 작업 B 시작 → handoff.md 읽고 이전 작업 파악 → plan.md를 새 작업 내용으로 갱신 → Plan Mode로 새 계획 수립 → 구현 진행
세션을 새로 시작하면서 plan.md도 갱신해두면, Claude가 깨끗한 컨텍스트에서 정확한 방향을 잡고 시작할 수 있다. /clear나 Ctrl+C 후 재시작하는 습관과 plan.md 갱신은 한 쌍이다
세 개의 역할 정리
| 역할 | 지속성 | 갱신 시점 | |
|---|---|---|---|
| Plan Mode | Claude의 읽기 전용 실행 상태 | 세션 내에서만 존재 | – |
| plan.md | 지금 할 작업의 방향과 범위 | 파일로 영구 보존 | 작업마다 덮어씀 |
| handoff.md | 끝난 작업의 결과와 남은 위험 | 파일로 영구 보존 | 완료 후 누적 기록 |
plan.md는 앞을 보는 파일이고, handoff.md는 뒤를 기록하는 파일이다. Plan Mode는 그 계획을 세우는 시간이다