"어디까지 했더라…?"
가게가 잘 돼서
매장 확장 공사를 하기로 했어요. 어제 Claude와 한참 공사 계획을 의논했는데 —
노트북을 덮었다가 오늘 다시 켜니, 그 대화가
전부 사라져 있어요. 어디까지 정했는지 처음부터 다시 설명해야 합니다.
긴 일은 대화로 끌고 가면 이렇게 끊겨요. 오늘은 일을 문서 한 장으로 지휘하는 법 — 스펙(spec)과 핸드오프를 배웁니다.
Claude Code 세션은 언젠가 끝나요(컨텍스트가 차거나, 노트북을 덮거나). 세션이 끝난 뒤에도 살아남는 건 무엇일까요?
맞아요. 대화는 임시(temporary), 파일은 영구(permanent)예요. 세션이 끝나면 책상 위 대화는 사라지지만, 파일에 적어둔 것은 그대로 남아 다음 세션이 다시 읽을 수 있어요. 그래서 긴 일은 대화가 아니라 문서로 시켜야 해요.
확장 공사처럼 며칠 걸리는 큰일을, 두 가지 방식으로 시켜봐요.
💬 대화로만 시키기: "홀을 넓히고, 주방도 키우고… 아 맞다 입구도…" 말이 길어지고 빠진 게 생겨요.
세션이 끊기면 어디까지 정했는지 통째로 증발. 다음에 처음부터 다시 설명.
📄 문서(스펙)로 시키기: 확장-공사-계획.md 한 장에 정리. 무엇을·왜·어떻게가 다 적혀 있어요.
세션이 바뀌어도 이 파일만 읽으면 차갑게(cold) 바로 이어받기 가능.
스펙(spec)은 거창한 게 아니에요. 해야 할 일 하나를, 처음 보는 사람도 바로 시작할 만큼 적어둔 마크다운 파일이에요. 핵심은 세 가지를 담는 것.
스펙에 들어가는 3가지
·
무엇을(what) — 홀 좌석을 12석 → 20석으로 늘린다
·
왜(why) — 점심 피크에 대기 줄이 생겨서
·
어떻게(how) — 창가 쪽 벽을 트고, 2인 테이블 4개 추가
이 세 가지가 적힌 문서 한 장이면, Claude든 동료든 "이게 뭐였더라" 없이 바로 일을 시작해요. 지시서가 곧 문서인 셈이죠.
같은 일을, 한 번은 "확장 공사 좀 해줘"라고 대화로, 한 번은 무엇·왜·어떻게가 적힌 스펙 파일을 주고 시켜요. 결과가 어떻게 다를까요?
맞아요. 명확한 계획(스펙)은 결과물 품질을 크게 끌어올려요. 무엇·왜·어떻게가 정해져 있으니 AI가 엉뚱한 방향으로 새지 않고, 무엇보다 매번 다시 설명할 필요가 없어요. 막연한 한 줄보다 잘 쓴 문서 한 장이 훨씬 강해요.
좋은 점 — 스펙도 Claude에게 쓰게 하면 돼요. 신메뉴 '봄나물 정식'을 출시할 건데, 바로 만들지 말고 기획서(스펙)부터 쓰게 시켜봐요.
신메뉴 '봄나물 정식' 출시를 하려고 해. 바로 만들지 말고, 무엇을·왜·어떻게가 담긴 스펙 문서를 specs/봄나물정식.md 로 먼저 써줘 — 만들기 전에, 무엇·왜·어떻게를 문서로 먼저
핵심은 "바로 만들지 말고 문서부터"예요. 손으로 코딩이 시작되기 전에, 무엇·왜·어떻게를 한 장에 못 박아 두는 거죠.
스펙이 생겼으면, 다음부터는 길게 설명할 필요가 없어요. 문서를 가리키며 시키면 끝이에요.
지시서가 곧 문서
"specs/봄나물정식.md 보고 그대로 메뉴 추가해줘" — 이 한 줄이면 Claude가
문서를 읽고 무엇·왜·어떻게를 파악해 일해요.
내가 매번 입으로 풀어 설명하지 않아도 되는 거예요.
스펙을 한 번 잘 써두면, 그 뒤의 모든 지시가 "그 문서대로" 한 줄로 압축돼요.
오늘 봄나물 정식 작업을 절반까지 하고 노트북을 덮었어요. 내일 새 세션(혹은 동료)이 이어받으려면, 무엇이 있어야 끊김 없이 이어질까요?
맞아요. 이게 핸드오프(handoff)예요. 세션이 바뀌어도 스펙 문서가 있으면 다음 세션이 그걸 읽고 차갑게(cold) 이어받아요. 대화는 사라져도 문서는 남으니까요. 사람한테 일 넘길 때 인수인계서 한 장 주는 것과 똑같아요.
스펙 문서는 메모장에 잠깐 적는 게 아니라, 코드와 같은 저장소(repo)에 두고 git에 커밋해요. 그래야 팀 누구든·다음 세션이든 꺼내 봐요. 스펙을 흔히 모아두는 폴더 이름은 무엇일까요?
정답! 보통 specs/ 폴더에 모아둬요. 코드와 함께 git에 커밋되니, 노트북이 바뀌어도·동료가 받아도 저장소만 열면 지시서가 거기 있어요. 대화와 달리 영원히 남는 거죠.
핸드오프를 직접 느껴봐요. 새 세션을 켰다고 치고(앞 대화는 모른다고 가정), 스펙 파일만 가리키며 이어서 시켜봐요.
specs/봄나물정식.md 읽고, 거기 적힌 대로 이어서 작업해줘. 지금 어디까지 됐고 다음에 뭘 할지부터 정리해줘 — 어제 대화 없이, 문서만으로 이어받기
앞 대화를 한 줄도 안 봤는데 문서만으로 어디까지 됐는지·다음에 뭘 할지 바로 파악했죠? 이게 핸드오프의 힘이에요.
한 줄로
긴 일은 대화가 아니라
문서(스펙)로 시켜요. 무엇·왜·어떻게를
specs/에 한 장 적어두면,
세션이 끝나도·사람이 바뀌어도 그 문서로
차갑게 이어받기(핸드오프)가 돼요. 지시서가 곧 문서예요.
다음 레슨에서
그런데 스펙이든 프롬프트든,
AI에게 무엇을 어떤 순서로 올려주느냐가 결과를 가른다는 걸 눈치챘나요?
다음
'컨텍스트 엔지니어링 — 프롬프트의 후속'에서 그 기술을 본격적으로 다뤄요. 가게는 계속 자랍니다. 🌱