재현 명령: 넘겨받을 작업의 첫 줄

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

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

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

---

에이전트 세션을 넘길 때 가장 위험한 문장은 “거의 다 됐다”였다. 사람끼리도 애매한 말인데, 코딩 에이전트에게는 더 위험하다. 다음 세션은 앞 세션의 감을 이어받지 못하고, 대화가 압축되거나 모델이 바뀌면 “거의”가 무엇을 뜻했는지 금방 사라진다. 나는 그래서 handoff를 남길 때 설명을 길게 쓰기보다 다음 실행자가 가장 먼저 돌릴 재현 명령을 한 줄로 고정하려고 한다.

여기서 말하는 재현 명령은 꼭 터미널 명령 하나만 뜻하지 않는다. 테스트 명령일 수도 있고, preview에서 눌러 볼 화면 경로일 수도 있고, 특정 입력을 넣었을 때 나와야 하는 로그 한 줄일 수도 있다. 중요한 건 “다음 사람이 무엇을 읽어야 하는가”보다 “다음 세션이 무엇을 실행하면 현재 상태를 다시 볼 수 있는가”를 먼저 적는 것이다.

handoff를 재현 명령, 기대 관찰, 실패 흔적, 멈출 기준 네 칸으로 접어 두는 흐름.

요약보다 먼저 실행면 고정

긴 작업을 넘길 때 나는 예전에는 배경 설명부터 길게 썼다. 어떤 파일을 봤고, 어떤 생각으로 고쳤고, 왜 이 방향이 괜찮아 보였는지를 꽤 성실하게 남겼다. 문제는 다음 세션이 그 설명을 읽고도 같은 상태를 재현하지 못한다는 점이었다. 설명은 많은데 첫 행동이 비어 있으면 에이전트는 다시 파일을 넓게 읽거나, 이미 틀어진 가정을 그대로 이어받는다.

재현 명령을 첫 줄에 두면 handoff의 성격이 달라진다. “이 테스트를 먼저 돌려라”, “이 preview에서 이 버튼을 눌러라”, “이 요청을 보내면 이 응답이어야 한다”처럼 상태를 되살리는 작은 손잡이가 생긴다. 그러면 다음 세션은 설명을 믿는 대신 바로 확인한다. 이 차이가 작아 보이지만, context가 길어진 작업에서는 꽤 크게 느껴진다.

네 칸으로 충분한 경우가 많았다

내가 자주 쓰는 형식은 네 칸이다. 첫째는 재현 명령이다. 둘째는 기대 관찰이다. 셋째는 실패 흔적이다. 넷째는 멈출 기준이다. 여기서 기대 관찰을 빼면 명령이 통과했는지 해석이 흔들리고, 실패 흔적을 빼면 다음 세션이 같은 삽질을 반복한다. 멈출 기준을 빼면 에이전트가 “조금 더 고치면 될 것 같다”는 식으로 범위를 넓히기 쉽다.

예를 들면 “UI 깨짐 수정”이라는 handoff보다 “로컬 preview에서 설정 화면을 열고 저장 버튼을 누른다. 성공이면 toast가 한 번만 뜨고 console error가 없어야 한다. 직전 실패는 저장 후 같은 toast가 두 번 뜨는 문제였다. 인증 흐름은 건드리지 않는다”가 훨씬 낫다. 이 정도면 다음 세션이 바로 움직일 수 있고, 틀린 방향으로 확장할 여지도 줄어든다.

실패 로그는 변명보다 유용했다

handoff에서 제일 아까운 정보는 실패한 시도다. 성공한 코드 설명은 다시 읽으면 어느 정도 복원되지만, 실패한 시도의 이유는 대화 밖으로 빠지면 거의 사라진다. 그래서 나는 실패 로그를 길게 붙이기보다, “마지막으로 틀린 관찰”을 한 문장으로 남긴다. 예를 들어 “테스트는 통과했지만 빈 데이터 케이스는 보지 못함”, “preview는 열렸지만 모바일 폭은 미확인”, “mock에서는 됐지만 실제 API 응답 스키마는 아직 모름” 같은 식이다.

이 한 줄은 에이전트에게 꽤 강한 제동 장치가 된다. 다음 세션은 새로 고치기 전에 이미 실패한 경로와 아직 확인하지 못한 가정을 같이 보게 된다. 나는 이걸 쓰고 나서 “방금 한 수정이 좋아 보이니 조금 더 넓혀 보자”는 식의 충동을 덜 믿게 됐다. 실패는 분위기를 망치는 메모가 아니라, 다음 실행의 범위를 좁히는 입력이었다.

재현 명령은 작은 계약이다

코딩 에이전트에게 “잘 이어서 해줘”라고 맡기면 대부분 친절하게 이어서 하려 한다. 그런데 친절함이 늘 좋은 결과로 이어지지는 않는다. 세션이 바뀐 뒤에는 이어서 하는 능력보다 멈출 줄 아는 능력이 더 중요할 때가 많다. 재현 명령은 그래서 작은 계약처럼 쓴다. 성공이면 어디까지 진행하고, 실패이면 어디서 멈추며, 어떤 파일이나 영역은 아직 건드리지 않는다는 기준을 같이 둔다.

특히 모바일 빌더나 웹 AI 도구에서 만든 초안을 로컬 에이전트에게 넘길 때 이 방식이 잘 맞았다. 화면은 그럴듯한데 실제 상태 관리나 권한 경계는 아직 애매한 경우가 많다. 이때 “이 화면을 완성해줘”보다 “이 동작을 재현하고, 이 관찰이 맞을 때만 다음 수정으로 넘어가라”가 훨씬 안전하다. handoff가 작업 지시가 아니라 검증 가능한 첫 실행으로 바뀌기 때문이다.

handoff를 받는 쪽도 편해진다

재현 명령을 남기면 넘기는 사람만 편한 것이 아니다. 받는 쪽 에이전트도 훨씬 덜 헤맨다. 첫 행동이 정해져 있으면 파일을 넓게 다시 훑기 전에 현재 상태를 확인할 수 있고, 확인 결과가 예상과 다르면 곧장 질문하거나 멈출 수 있다. 나는 이 차이를 “잘 요약된 업무 지시”와 “바로 실행할 수 있는 작업면”의 차이로 본다.

또 하나 좋은 점은 사람의 리뷰가 쉬워진다는 것이다. handoff에 재현 명령과 성공 신호가 있으면, 내가 나중에 로그를 훑을 때도 판단이 빨라진다. 에이전트가 정말 이어서 작업했는지, 아니면 설명만 따라가다가 다른 문제를 만든 것인지 구분하기 쉽다. 특히 같은 저장소에서 여러 세션이 동시에 돌 때는 이 작은 형식 하나가 작업 간 경계를 꽤 또렷하게 만들어 준다.

나는 이 형식을 체크리스트처럼 엄격하게 쓰지는 않는다. 대신 세션을 닫기 전에 “다음 실행자가 이 작업을 다시 보려면 무엇을 먼저 눌러야 하지?”라고 한 번 묻는다. 답이 바로 나오지 않으면 아직 handoff가 덜 된 상태다. 그때는 설명을 더 쓰기보다, 작은 재현 경로 하나를 먼저 찾는 편이 낫다.

내가 남기는 짧은 형식

요즘 내 메모는 대체로 이렇게 줄어든다. “먼저 실행: …”, “성공 신호: …”, “직전 실패: …”, “멈출 조건: …”. 네 줄 이상으로 길어질 때도 있지만, 첫 줄의 재현 명령만은 최대한 짧게 둔다. 다음 세션이 그 줄을 실행하기 전에 긴 배경 설명을 읽어야 한다면 이미 handoff가 무거워졌다는 신호로 본다.

물론 모든 작업에 이 정도 형식이 필요한 건 아니다. 한 파일의 작은 오타 수정이나 단순 문구 교체에는 과하다. 하지만 에이전트가 여러 파일을 읽고, preview나 테스트를 거쳐야 하고, 사용자의 판단이 중간에 끼어 있는 작업이라면 이야기가 달라진다. 그때는 요약을 잘 쓰는 것보다, 다음 세션이 바로 상태를 되살릴 수 있는 첫 실행을 남기는 편이 회복 비용을 줄인다.

내 기준으로 좋은 handoff는 읽고 감탄하게 만드는 문서가 아니다. 다음 세션이 첫 줄을 실행하고, 기대한 관찰과 다르면 바로 멈출 수 있는 작은 장치다. 바이브코딩이 빨라질수록 이 작은 장치가 더 필요해진다. 속도가 빠른 도구일수록 잘못 이어받았을 때도 빠르게 멀리 가기 때문이다.

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

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