Spec, Plan, Handoff
다음 session 이 매끄럽게 이어가도록 작업을 구조화하기
⏱ 예상 ~4분
01 · 읽기
결국 모든 Claude Code session 은 끝나요. context 가 다 찼을 수도, 노트북을 닫았을 수도, 팀원에게 일을 넘길 수도 있어요.
질문은 — 다음 session 이 매끄럽게 이어받을 수 있느냐예요.
답은 문서를 얼마나 잘 썼느냐에 달려 있어요. 이게 spec 이 등장하는 지점이에요. Spec 은 기능, 버그 수정, 또는 작업을 설명하는 markdown 파일이에요. Claude (또는 동료) 가 처음부터 이어받을 수 있을 만큼 충분히 자세하죠.
핵심 정리
- Session 은 끝나요 — context 는 임시, spec 은 영구
- Spec 이 있으면 다음 session (또는 사람) 이 다시 설명 없이 이어받을 수 있어요
- Spec 은 무엇, 왜, 어떻게를 설명하는 markdown 파일이에요
- repo 에 살고 (보통 specs/ 폴더), git 에 commit 돼요
02 · 코드 예제
좋은 spec 은 답해요 — 무엇을 만들고 있나, 어떤 파일이 관련됐나, "끝"은 어떻게 생겼나? 아래는 template 이에요.
Feature spec template
# Feature: OAuth Integration
## Requirements
- Support Google and GitHub OAuth
- Maintain session after page refresh
- Handle token refresh automatically
## Files to Modify
- src/auth/oauth.ts — OAuth client setup
- src/auth/session.ts — Session persistence
- server/routes/auth.ts — API endpoints
## Implementation Plan
1. Set up OAuth provider configuration
2. Add login flow UI components
3. Implement token refresh logic
4. Add integration tests
## Done When
- `npm test` passes
- Can log in with Google and GitHub
- Session survives page refresh
구조를 보세요 — 요구사항 (무엇), 파일 (어디), 계획 (어떻게), 완료 정의 (언제 멈출지). 이건 Claude가 새 session 에서 이 기능을 시작할 만큼 충분해요. Claude에게 spec 파일을 가리키며 "이걸 구현해" 라고 말해요.
03 · 읽기
복잡한 변경에는 Claude Code의 plan 모드 가 있어요. 바로 코드를 짜는 대신 Claude가 codebase 를 탐색하고, 기존 패턴을 이해하고, 구현 전에 계획을 제안해요.
작업을 checkpoint 할 수도 있어요. Esc+Esc 를 누르면 rewind 메뉴가 열려요 — 코드와 대화를 어떤 이전 시점으로 되돌리거나, checkpoint 부터 요약해서 context 를 비울 수 있어요.
Checkpoint 는 로컬 undo 같아요 — Claude 의 모든 변경을 추적해서 언제든 되돌릴 수 있어요.
핵심 정리
- Plan 모드: Claude가 구현 전에 탐색하고 계획을 제안해요
- Checkpoint: 각 변경 전에 자동으로 만들어져요
- Esc+Esc 가 rewind 메뉴를 열어요 — 코드, 대화, 또는 둘 다 되돌려요
- "여기부터 요약" 은 그 지점 이전을 압축해요
- Checkpoint 는 session 로컬이에요 (git 과 별개)
04 · 코드 예제
아래는 경험 있는 엔지니어가 Claude Code 에서 복잡한 작업을 어떻게 구조화하는지예요.
단계 1 — 탐색
You: "Read the auth module and explain how sessions work"
Claude: [reads files, explains architecture]
단계 2 — 계획
You: "Write a spec for adding OAuth support"
Claude: [creates specs/OAUTH_SPEC.md with requirements, files, plan]
단계 3 — 구현
You: "Implement the spec in specs/OAUTH_SPEC.md"
Claude: [implements against the spec, step by step]
단계 4 — 검증
You: "Run tests and verify against the spec"
Claude: [runs tests, checks each "done when" criterion]
Spec 은 session 사이의 다리가 돼요. 구현 중간에 context 가 다 차면, 새 session 을 열고 "specs/OAUTH_SPEC.md 구현을 계속해" 라고 해요. Claude 는 spec 을 읽고, git 으로 무엇이 끝났는지 보고, 이어서 일을 해요.
05 · 퀴즈
복잡한 기능을 절반쯤 하다가 context 가 다 찼어요. 새 session 에서 이어가는 가장 좋은 방법은?
- Claude에게 spec 파일을 가리키며 이어 달라고 요청하기
- 처음부터 모든 걸 다시 설명하기
- 이전 대화 전체를 복사해서 붙여넣기
- 기능을 포기하고 간단한 것 하기
06 · 빈칸 채우기
Esc 를 두 번 눌러 _____ 메뉴를 열면 코드와 대화를 이전 시점으로 되돌릴 수 있어요.
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.