빌드 뒤 사라진 코딩 에이전트 수정

 

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

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

2026년 7월 10일 | 바이브코딩 Tips

---

결과 파일을 직접 고치면 다음 빌드에서 사라질 수 있다. 원본과 생성 명령을 찾아 같은 의도가 재생성 뒤에도 남는지 확인해야 한다.

수정은 보였는데 다음 빌드에서 사라졌다

src/client.generated.ts의 한 줄 수정은 리뷰 화면에서 멀쩡했지만, 다음 빌드에서 통째로 사라졌다. 코딩 에이전트가 타입 하나와 기본값을 정확히 바꿨고 테스트도 통과했는데, codegen이 다시 돌자 파일이 원래 모양으로 돌아온 것이다. 나는 이런 상황을 겪으면 에이전트가 코드를 틀리게 썼는지보다 수정한 파일이 원본이었는지부터 본다.

자동 생성 파일은 저장소 안에 있고 diff에도 잡히기 때문에 보통 파일처럼 보인다. 이름에 generated가 붙으면 알아보기 쉽지만, 실제로는 API client, ORM model, protobuf binding, OpenAPI schema 결과물, 번역 리소스처럼 평범한 경로와 이름을 가진 경우도 많다. 에이전트는 요청과 가장 가까운 코드를 찾아 빠르게 고치고, 사람은 눈앞의 diff가 의도대로라 안심한다. 문제는 다음 생성 명령이 그 수정의 수명을 결정한다는 데 있다.

실무에서 더 헷갈리는 장면은 테스트가 결과 파일을 직접 읽을 때다. generated 파일을 고치면 테스트는 정말로 통과한다. 리뷰 화면에도 원하는 타입과 문자열이 남는다. 그런데 깨끗한 checkout에서 빌드를 다시 돌리거나 CI가 생성 단계를 먼저 실행하면 방금 고친 줄이 사라지고 같은 테스트가 다시 실패한다. 그래서 나는 로컬 PASS보다 깨끗한 재생성 뒤 PASS를 더 강한 증거로 본다.

파일 머리말보다 생성 경로 전체를 찾는다

첫 확인은 파일 상단의 경고 문구다. “do not edit”, “generated by”, “changes will be overwritten” 같은 문장이 있으면 직접 수정은 일단 보류한다. 다만 경고가 없다고 사람이 관리하는 원본이라는 뜻은 아니다. 생성기가 오래됐거나 사내 스크립트가 결과물에 주석을 붙이지 않는 경우도 있다. 그래서 나는 같은 파일명을 빌드 스크립트, package script, Makefile, CI 설정에서 한 번 더 찾는다.

여기서 필요한 것은 검색 결과를 많이 받는 일이 아니다. 무엇이 이 파일을 쓰는지를 한 줄로 확인하는 일이다. 예를 들어 OpenAPI 문서가 client 코드를 만들고, schema가 model을 만들고, template이 설정 파일을 만든다면 수정 지점은 결과 파일보다 한 단계 앞에 있다. 생성 명령을 찾지 못한 채 결과물만 고치면, 다음 에이전트 세션은 그 diff를 이미 검증된 변경으로 오해하기 쉽다.

원본, 생성 규칙, 결과물을 세 층으로 나눈다

내가 에이전트에게 다시 확인시키는 대상은 세 가지다. 첫째는 schema나 template 같은 원본, 둘째는 generator 버전과 옵션 같은 생성 규칙, 셋째는 저장소에 남는 결과물이다. 이 셋을 섞으면 “결과가 맞다”와 “다시 만들 수 있다”가 같은 말처럼 들린다. 하지만 재현 가능한 수정은 결과가 한 번 맞는 데서 끝나지 않고, 같은 원본과 명령으로 다시 만들어도 같은 의도가 남아야 한다.

예를 들어 필드 타입이 잘못됐다면 generated client의 타입 선언만 고치는 대신 API schema의 타입을 먼저 본다. 출력 포맷이 이상하다면 결과 JSON보다 template과 generator 옵션을 확인한다. vendor 코드처럼 원본을 직접 고칠 수 없는 경우에는 post-generation patch나 wrapper를 별도 단계로 둔다. 중요한 건 어느 층을 고쳤는지 숨기지 않는 것이다. 나는 완료 보고에 원본 파일, 생성 명령, 결과 파일 세 경로가 나란히 없으면 아직 재생성 경계를 못 닫았다고 본다.

에이전트에게 수정 전에 원본 후보를 말하게 한다

이 문제는 작업을 다 한 뒤에 잡으면 되돌릴 diff가 커진다. 그래서 생성 가능성이 있는 파일을 건드릴 때는 수정 전 짧은 확인을 넣는다. “이 파일을 직접 관리하는가, 다른 입력에서 만들어지는가, 다시 만드는 명령은 무엇인가”를 먼저 답하게 한다. 답이 모호하면 edit보다 search를 한 번 더 시킨다. 코드 한 줄을 늦추는 대신 잘못된 층에 수정 열 줄이 생기는 일을 막는 쪽이 낫다.

특히 여러 에이전트를 번갈아 쓰면 이 확인이 유용하다. 앞 세션은 결과 파일만 보고 패치하고, 뒤 세션은 빌드를 돌려 그 패치를 지운 뒤 “변경이 없습니다”라고 말할 수 있다. 두 세션 모두 자기 관찰 안에서는 맞다. 사람이 원본과 결과물의 관계를 고정하지 않았기 때문에 작업만 이어지지 않은 것이다. 나는 generated, build, schema라는 단어가 하나라도 보이면 직접 수정 가능 여부를 먼저 물어 수정 순서를 좁힌다.

검증은 재생성 전후 diff로 닫는다

테스트 통과만으로는 이 문제를 잡기 어렵다. 직접 고친 결과 파일도 현재 작업트리에서는 정상 동작할 수 있기 때문이다. 내가 믿는 검증은 더 단순하다. 원본을 고친 상태에서 생성 전 diff를 확인하고, 프로젝트가 쓰는 공식 생성 명령을 한 번 실행한 다음, 생성 후 diff에 같은 의도가 남는지 본다. 필요한 변경이 사라지거나 예상 밖 파일 수십 개가 같이 바뀌면 완료가 아니라 원인 확인으로 돌아간다.

이 절차는 스냅샷 업데이트와도 비슷하다. 기대 결과가 바뀌었다는 사실만으로 구현이 맞아진 것은 아니다. 생성 결과가 달라졌다면 어떤 입력과 옵션이 그 차이를 만들었는지 설명할 수 있어야 한다. 그래서 나는 “테스트 PASS” 옆에 “재생성 뒤 diff 유지”를 따로 둔다. 실행 성공과 수정 생존은 서로 다른 검증 항목이다.

재생성 뒤에는 바뀐 파일 수도 같이 본다. 요청은 타입 한 줄 수정인데 generated 파일 수십 개가 갱신됐다면 generator 버전, 정렬 방식, 실행 환경이 달라졌을 가능성이 있다. 이 상태에서 큰 diff를 그대로 받아들이면 실제 기능 수정과 도구 버전 흔들림이 섞인다. 나는 필요한 원본 변경만 남기고 같은 generator 버전으로 다시 실행해, 예상한 결과물만 바뀌는지 확인한다. diff 크기도 생성 계약이 맞는지 알려 주는 신호다.

직접 수정이 필요한 예외도 이유를 남긴다

물론 생성 파일을 절대 건드리면 안 되는 것은 아니다. upstream 버그를 급히 막아야 하거나, 배포 환경에서 generator를 돌릴 수 없거나, 생성 뒤 적용하는 패치가 공식 절차인 프로젝트도 있다. 다만 이때는 예외를 숨기지 않는다. 왜 원본을 못 고쳤는지, 다음 재생성 때 어떤 명령이 패치를 다시 적용하는지, 어느 파일을 비교해야 하는지 남긴다.

나는 생성 파일 diff를 보면 코드의 정답보다 먼저 수정의 수명을 묻는다. 다음 빌드, 의존성 갱신, CI codegen 뒤에도 남는가. 그 질문에 답하려면 결과 파일 한 장으로는 부족하다. 원본과 생성 규칙이 같이 보여야 한다. 코딩 에이전트가 빠르게 만든 수정일수록, 한 번 더 재생성해 같은 변경이 살아남는지 확인하는 편이 결국 덜 돌아간다.

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

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