새 파일만 남고 연결이 빠진 수정

 

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

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

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

---

새 파일이 생겼다는 사실보다, 기존 진입점과 같은 검증 입력에 실제로 연결됐는지가 더 중요하다.

새 파일은 결과물이 아니라 후보일 때가 많다

코딩 에이전트가 helper 파일을 새로 만들었는데, 정작 기존 진입점에서 그 파일을 읽지 않는 경우가 있다. 파일 이름도 그럴듯하고 내부 함수도 깔끔해서 처음에는 일이 끝난 것처럼 보인다. 그런데 실제 앱을 다시 켜면 아무 변화가 없다. 원인은 대개 단순하다. 새 파일은 생겼지만 import, route, registry, export 같은 연결 지점이 비어 있었다.

나는 이걸 몇 번 겪고 나서, 에이전트가 “새 파일을 추가했습니다”라고 말하면 바로 완료로 올리지 않는다. 그 문장은 성과 보고로 바로 읽기보다 후보 산출물 보고로 두는 편이 낫다. 새 파일이 기존 흐름에 물렸는지, 같은 입력이 그 코드를 실제로 지나갔는지까지 봐야 수정이라고 부를 수 있다. 파일 생성은 시작이고, 연결 확인이 완료에 가깝다.

이 차이는 단순한 스타일 문제가 아니다. 에이전트가 새 파일을 만들면 사람은 “무언가 구조화됐다”고 느끼기 쉽다. 하지만 실제 서비스는 파일 존재 여부를 보지 않는다. import graph, router table, command registry, plugin manifest처럼 기존 실행면에 연결된 것만 사용한다. 그래서 나는 새 파일이 생긴 diff를 볼 때 파일 내용보다 그 파일을 처음 부르는 줄을 더 빨리 찾는다.

생성 파일과 호출 파일을 한 줄로 묶는다

내가 가장 먼저 보는 것은 파일 수가 아니다. “무엇을 만들었고, 어디에서 불렀는가”를 한 줄로 묶는다. 예를 들어 parser helper를 만들었다면 기존 loader나 route handler에서 그 helper를 호출하는 줄이 있어야 한다. UI 컴포넌트를 만들었다면 화면 registry나 parent component에서 실제로 렌더되는 경로가 있어야 한다. 새 설정 파일을 만들었다면 실행 코드가 그 설정을 읽는 지점이 있어야 한다.

이 한 줄이 비어 있으면 diff가 아무리 예뻐도 보류한다. 에이전트는 종종 “분리하면 깔끔하다”는 방향으로 새 파일을 만든다. 그 자체가 나쁜 건 아니다. 다만 기존 코드가 그 파일을 모르고 있으면 깔끔한 구조가 아니라 고아 파일이다. 고아 파일은 테스트를 속이기보다 사람을 속인다. 눈에 보이는 변화가 있으니 진도가 난 것처럼 느껴지기 때문이다.

검증은 새 파일이 아니라 기존 입력에서 시작한다

새 helper의 단위 테스트만 통과했다고 해서 충분하지 않은 날이 많다. 내가 고치려던 문제는 helper 자체가 아니라 기존 입력이 잘못 처리되는 흐름이었기 때문이다. 그래서 검증은 새 파일을 직접 호출하는 테스트보다, 원래 실패했던 입력이 기존 진입점에서 새 코드를 타는지 확인하는 쪽이 먼저다. 이 순서가 바뀌면 “새 코드는 맞는데 제품은 그대로”라는 애매한 상태가 남는다.

특히 에이전트에게 자연어로 “이 케이스 처리해줘”라고 맡기면, 모델은 문제를 작게 잘라 새 함수를 만들고 거기만 검증하려는 경향이 있다. 나는 이때 원래 호출 경로라는 말을 일부러 붙인다. “새 함수 테스트 말고, 기존 API 입력으로 다시 지나가게 해줘”라고 요구하면 확인 범위가 훨씬 덜 흐려진다. 새 파일은 구현 세부이고, 기존 입력은 사용자가 실제로 밟는 길이다.

이때 테스트 이름도 조금 더 구체적으로 요구한다. “helper 테스트 통과”보다 “기존 API 요청이 helper를 지나가며 같은 실패 입력을 처리함”이 낫다. 화면 작업이라면 새 컴포넌트 스냅샷보다 기존 화면에서 그 컴포넌트가 렌더됐는지를 본다. CLI 작업이라면 새 모듈 단위 테스트보다 원래 명령이 새 모듈을 import하는지 확인한다. 검증 문장이 원래 사용자 경로를 포함하면, 새 파일 착시가 훨씬 줄어든다.

완료 보고에는 연결 지점이 들어가야 한다

좋은 완료 보고는 “파일을 추가했다”에서 끝나지 않는다. “새 파일을 만들었고, 기존 진입점의 어느 줄에서 호출되며, 어떤 입력으로 그 경로를 확인했다”까지 들어간다. 이 세 칸이 있으면 리뷰가 빨라진다. 반대로 새 파일 이름과 테스트 이름만 있으면, 나는 다시 연결 지점을 묻는다. 그 질문이 빠지면 다음 수정에서 같은 파일이 또 하나 생기기 쉽다.

이 절차의 목적은 에이전트를 몰아붙이는 데 있지 않다. 에이전트가 만든 구조를 사람이 믿기 쉽게 만드는 작은 계약에 가깝다. 생성 파일, 연결 파일, 검증 입력이 나란히 있으면 diff를 읽는 순서도 자연스럽다. 먼저 새 파일을 열고, 그다음 호출 지점을 보고, 마지막으로 같은 입력의 결과를 본다. 보고서가 길 필요는 없지만 연결 좌표는 빠지면 안 된다.

새 파일이 두 개 이상이면 더 일찍 멈춘다

새 파일이 하나일 때도 연결이 빠질 수 있는데, 두 개 이상이면 착시는 더 커진다. adapter, schema, service, test helper가 한꺼번에 생기면 구조는 풍성해 보인다. 하지만 실제 기존 경로에 물린 파일은 하나도 없을 수 있다. 나는 그래서 새 파일이 여러 개 생긴 diff에서는 “각 파일의 첫 호출자”를 먼저 확인한다. 호출자가 없는 파일은 이번 수정의 일부인지, 다음 작업의 준비물인지 분리해야 한다.

분리가 애매하면 바로 삭제하라는 뜻은 아니다. 다만 완료 상태로 섞어 두지 않는다. “이번 수정에서 사용됨”, “다음 단계 후보”, “생성됐지만 미연결” 정도로 나누면 된다. 이렇게 적어 두면 리뷰어도 불필요한 구조를 성급히 받아들이지 않고, 에이전트도 다음 턴에서 미연결 파일을 이미 완료된 근거처럼 재사용하지 않는다.

물론 모든 미연결 파일이 잘못은 아니다. 다음 단계에서 쓰려고 일부러 쌓아 둔 scaffold일 수도 있다. 다만 그 경우에는 이름을 바꿔야 한다. 완료 파일로 묶기보다 “다음 단계 후보”라고 적어야 한다. 이 작은 이름 차이가 중요하다. 후보를 완료로 부르는 순간, 다음 세션은 그 파일을 이미 검증된 전제로 삼기 쉽다.

작은 연결표 하나가 재작업을 줄인다

요즘은 새 파일이 들어간 에이전트 diff를 볼 때 머릿속으로 작은 표를 만든다. 왼쪽에는 생성 파일, 가운데에는 기존 호출 지점, 오른쪽에는 확인한 입력을 둔다. 세 칸 중 하나라도 비면 아직 완료가 아니다. 이 표를 실제 문서로 길게 남길 필요는 없다. 완료 보고 안에 한 줄씩만 들어가도 충분하다.

이 습관은 작은 버그 수정에서 특히 체감이 컸다. 새 파일을 만드는 일은 모델에게 쉽고, 기존 흐름에 조심스럽게 끼워 넣는 일은 상대적으로 어렵다. 그래서 나는 새 파일이 생긴 순간을 “진도가 났다”보다 “연결을 확인할 차례가 왔다”로 읽는다. 에이전트가 빨리 코드를 늘릴수록, 사람 쪽에서는 새 코드가 실제 길 위에 올라왔는지를 더 건조하게 확인해야 한다.

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

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