상태 차이부터 넘기기

시리즈: 바이브코딩 Tips #29

이전: 28편 | 목록 | 다음 없음

2026년 6월 5일 | 바이브코딩 Tips

---

모바일 빌더나 웹형 코딩 에이전트에서 만든 초안은 생각보다 빨리 현재 상태를 잃어버린다. 화면은 그럴듯하게 떠 있고, 에이전트는 “수정했습니다”라고 말하지만, 다음 세션에서 다시 열어 보면 정작 어디가 기준선이고 어디가 새 변경인지 흐릿해질 때가 많다. 나는 이럴 때 최종 요구사항을 더 길게 설명하기보다, 먼저 상태 차이를 작게 써 두는 편이 훨씬 덜 흔들렸다.

처음에는 나도 handoff를 “이 기능을 완성해 줘”에 가깝게 넘겼다. 그런데 코딩 에이전트 입장에서는 그 문장이 너무 넓다. 완성이 무엇인지도 다시 추측해야 하고, 이미 잘 돌아가던 부분과 방금 깨진 부분도 다시 찾아야 한다. 특히 Lovable 같은 모바일·웹 빌더에서 UI 초안을 만들고, 데스크톱에서 실제 코드와 테스트를 이어 볼 때 이 간극이 크게 느껴졌다. 모바일 화면에서는 아이디어가 빨리 잡히지만, 저장소 전체의 맥락이나 실패 로그를 깊게 읽기는 어렵기 때문이다.

handoff bundle을 기능 설명이 아니라 기준선과 상태 차이 중심으로 접어 두는 흐름.

완성 요청보다 기준선 한 줄

내가 요즘 자주 쓰는 형식은 단순하다. “마지막으로 믿을 수 있는 상태는 A였고, 지금은 B만 달라졌다. C는 건드리지 말고 D 확인부터 시작.” 이 네 조각이면 다음 에이전트가 해야 할 일이 훨씬 좁아진다. 여기서 A는 기준선이다. 통과한 테스트, 정상 화면, 마지막 commit, preview URL처럼 다시 돌아갈 수 있는 지점이면 된다. B는 현재 상태다. 새 버튼이 생겼다, 라우팅만 깨졌다, 모바일 preview에서만 여백이 무너진다처럼 관찰 가능한 차이로 적는다.

중요한 건 C다. 바이브코딩에서 실패가 커지는 순간은 대개 “고치면 될 것 같은 주변부”까지 같이 만질 때 온다. 인증, 결제, 권한, 데이터 삭제, 배포 설정처럼 지금 초안의 목적과 멀지만 위험한 영역은 handoff에 금지선으로 넣어 둔다. 에이전트에게 “자유롭게 개선해 줘”라고 맡기면 이 선이 거의 사라진다. 반대로 금지선을 먼저 쓰면, 다음 세션의 첫 행동이 수정이 아니라 확인으로 바뀐다.

상태 차이는 diff보다 사람 친화적이어야 한다

여기서 말하는 상태 차이는 git diff를 그대로 붙이라는 뜻은 아니다. diff는 파일 기준이고, handoff는 작업 기준이어야 한다. 예를 들어 “src/components/Header.tsx 38줄 변경”보다 “모바일 폭에서 검색 버튼이 두 줄로 밀린다”가 다음 판단에 더 직접적이다. 파일명은 뒤에 붙여도 된다. 먼저 사용자 흐름, 화면, 테스트, 실패 메시지 같은 바깥 증상을 적고, 그 다음에 관련 파일을 붙이는 편이 낫다.

이 방식은 긴 세션 압축에도 잘 버틴다. 대화가 잘려도 “무엇을 만들려 했는지”보다 “어디까지 믿을 수 있고 어디부터 달라졌는지”가 남아 있으면 복구가 쉽다. 나는 특히 모델을 바꿔 이어 맡길 때 이 차이를 많이 본다. 빠른 모델에게 초안을 만들게 하고 강한 모델에게 검증을 맡길 때, 상태 차이가 없으면 강한 모델도 처음부터 추측을 다시 시작한다. 그러면 검증 세션이 어느새 두 번째 구현 세션으로 변한다.

네 줄이면 충분한 handoff bundle

실제로는 아래 네 줄 정도면 충분했다. 첫째, 기준선. “어떤 상태까지는 정상으로 본다”를 적는다. 둘째, 현재 상태. “지금 눈에 보이는 변화나 실패”를 적는다. 셋째, 금지선. “이번 세션에서는 건드리지 않을 영역”을 적는다. 넷째, 첫 검증. “다음 에이전트가 가장 먼저 볼 화면, 명령, 로그”를 하나만 고른다. 이 네 줄을 넘기면 다음 세션은 새 요구사항을 해석하는 데 시간을 덜 쓰고, 실제 차이를 확인하는 데 바로 들어갈 수 있다.

나는 이걸 너무 거창한 문서로 만들지는 않으려고 한다. handoff가 길어지면 또 다른 읽기 부담이 된다. 대신 PR 설명, 에이전트 첫 프롬프트, 작업 메모 맨 위에 기준선 / 현재 상태 / 금지선 / 첫 검증 네 칸만 남긴다. 이 정도면 모바일에서 시작한 초안도 데스크톱 검증으로 자연스럽게 넘어가고, 에이전트가 “좋아 보이는 개선”을 하느라 원래 문제를 흐리는 일이 줄어든다.

첫 프롬프트에 넣을 작은 체크

내가 실제로 넘길 때는 문장보다 순서를 더 신경 쓴다. 먼저 “읽기만 하고 판단해 달라”는 모드로 시작하고, 그 다음에 필요한 수정 범위를 열어 준다. 예를 들어 “현재 상태 차이를 확인한 뒤, 수정이 필요하면 파일 1개 안에서만 제안해 달라”처럼 권한을 나눠 둔다. 이 한 줄이 없으면 에이전트는 상태 확인과 수정을 한 번에 처리하려고 하고, 그러면 사람이 다시 읽어야 할 diff가 갑자기 커진다.

또 하나는 실패 로그를 handoff 안에 너무 많이 붙이지 않는 것이다. 로그가 길면 똑똑한 모델도 핵심을 놓친다. 대신 “처음 볼 로그는 이것 하나”를 고른다. 빌드 실패라면 첫 에러 블록, UI 문제라면 깨진 화면 이름, 데이터 문제라면 입력 샘플 하나면 충분하다. 나머지는 필요할 때 열어 보게 하는 편이 낫다. handoff bundle은 자료 창고가 아니라 다음 행동의 입구에 가까워야 한다.

이 습관은 사람에게도 좋다. 내가 다음 날 다시 열어 봐도, 긴 대화 요약보다 네 줄짜리 상태 차이가 훨씬 빨리 들어온다. 특히 여러 에이전트를 동시에 쓰거나 모바일에서 떠오른 아이디어를 밤에 데스크톱으로 옮길 때, “왜 이 작업을 하려고 했지?”보다 “어디까지 정상이고 어디가 달라졌지?”를 먼저 보면 재시작 비용이 줄어든다.

주의할 점도 있다. 상태 차이를 너무 판정문처럼 쓰면 안 된다. “원인은 인증 모듈이다”처럼 아직 확인하지 않은 결론을 넣으면 다음 에이전트가 그 가설에 끌려간다. 나는 가능하면 “로그인 후 리다이렉트가 두 번 발생한다”처럼 관찰로 적고, 원인 후보는 따로 둔다. 관찰과 가설을 나누는 것만으로도 handoff가 훨씬 안전해진다.

그래서 나는 handoff를 마감 문서가 아니라 시작 장치로 본다. 다음 세션이 첫 5분 안에 기준선을 다시 확인하고, 상태 차이를 말로 되풀이하고, 금지선을 어기지 않는지 보면 충분하다. 이 세 가지가 맞으면 그 다음 수정은 꽤 빠르게 열어도 된다.

반대로 이 첫 확인에서 기준선이 틀렸거나 금지선이 모호하면, 수정은 잠깐 멈춘다. 그때는 더 좋은 프롬프트보다 더 정확한 현재 상태 한 줄이 먼저다. 여기서 멈춤 판단까지 같이 남긴다.

바이브코딩은 속도가 장점이라서, 모든 걸 문서화하자는 말은 잘 맞지 않는다. 다만 속도가 빠를수록 상태가 섞이는 비용도 빨리 커진다. 그래서 나는 작업을 넘길 때 완성 설명을 길게 쓰기보다, 기준선과 상태 차이를 먼저 접어 둔다. 다음 사람이 사람이든 에이전트든, 결국 가장 먼저 필요한 건 “무엇을 새로 만들까”보다 “지금 무엇이 달라졌나”에 가깝다.

시리즈: 바이브코딩 Tips #29

이전: 28편 | 목록 | 다음 없음