잘린 검색 결과를 전체 목록으로 믿은 코딩 에이전트

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

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

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

---

검색 도구가 137건 중 50건만 보여 줬는데, 코딩 에이전트는 그 50건을 전부라고 읽고 이름 변경을 끝냈다고 보고했다. 화면에 나온 결과만 보면 검색도 성공했고 수정도 깔끔했다. 문제는 응답 끝의 truncated: true였다. 나는 이런 장면에서 검색 명령의 성공 여부보다 검색 범위를 끝까지 확인했는지를 먼저 보게 됐다.

Figure 1. 같은 검색 응답에서도 truncation 신호를 읽느냐에 따라 완료와 추가 탐색이 갈린다.

50건이 전부처럼 보인 장면

공용 함수 이름을 바꾸는 작업이었다. 에이전트는 저장소 전체에서 이전 이름을 검색했고, 50개 호출부를 찾아 새 이름으로 고쳤다. 테스트 파일 몇 개도 통과했다. 그런데 배포 스크립트 아래의 호출부와 예제 설정은 그대로 남았다. 검색 도구가 기본 한도만큼 반환한 뒤 나머지를 잘랐기 때문이다.

나도 처음에는 “50건이나 찾았으니 충분히 훑었겠지”라고 생각했다. 하지만 많은 도구에서 50이나 100은 데이터 크기를 말해 주지 않고 출력 상한만 드러낸다. 결과가 상한과 정확히 같다면 오히려 더 남아 있을 가능성을 의심해야 한다. 특히 이름 변경, API 제거, 보안 패턴 감사처럼 “없음”을 증명해야 하는 작업에서는 첫 페이지가 많아 보인다는 사실이 완전성의 근거가 되지 않는다.

성공한 검색과 완전한 검색은 다르다

검색 호출의 exit code가 0이라는 말은 쿼리를 처리했다는 뜻이다. 전체 일치 항목 반환 여부는 별도 문제다. 그래서 나는 검색 응답을 내용과 경계 정보로 나눈다. 내용은 파일명과 일치 줄이고, 경계 정보는 total_count, returned_count, truncated, next_offset 같은 필드다.

이 네 값 가운데 하나라도 빠지면 에이전트는 보이는 목록만으로 전체를 추정하기 쉽다. 반대로 총 137건, 반환 50건, 잘림 true가 한 줄에 같이 있으면 다음 행동이 분명해진다. 수정은 잠시 보류하고 검색 범위를 더 좁히거나 다음 페이지를 읽어야 한다.

도구가 총 일치 수를 아예 제공하지 않는 경우도 있다. 이때 나는 반환 수가 기본 limit에 닿았는지부터 본다. 50개 제한에서 정확히 50개가 나왔다면 완전성을 확인하지 못한 상태로 표시한다. “더 있을 수도 있음”을 숨긴 채 수정으로 넘어가는 것보다, 미확인 상태를 짧게 남기고 두 번째 검색을 여는 편이 훨씬 싸다.

신호	읽는 뜻	다음 행동
returned = limit	상한에 닿았을 가능성	잘림 필드 확인
truncated = true	목록이 불완전함	쿼리 분할 또는 다음 페이지
total = returned	현재 쿼리 범위는 소진	다른 표기·경로로 교차 확인

페이지를 넘기기 전에 쿼리를 나눈다

무조건 offset만 올리는 방식은 빠뜨림은 줄이지만 잡음도 그대로 끌고 간다. 나는 먼저 검색 축을 코드, 테스트, 설정, 문서로 나눈다. 예를 들어 함수 이름을 바꾼다면 정의와 호출, 문자열 상수, 문서 예제를 각각 검색한다. 이렇게 하면 어떤 영역을 다 봤고 어떤 영역이 아직 남았는지가 결과 수에 묻히지 않는다.

생성 디렉터리나 의존성 캐시가 결과를 덮고 있다면 제외 조건도 명시한다. 제외한 경로는 의도적으로 보지 않은 범위로 기록한다. 완료 보고에 이 경로를 남겨야 다음 사람이 “검색 결과 0건”을 저장소 전체 0건으로 오해하지 않는다.

작은 표 하나도 도움이 됐다. 코드 73건, 테스트 41건, 설정 8건, 문서 15건처럼 구간별 수를 적으면 합계 137건과 맞는지 바로 볼 수 있다. 수정 뒤에는 이전 이름 0건과 새 이름의 구간별 수를 같은 표에 다시 적는다. 단순히 페이지를 끝까지 넘기는 것보다 누락 위치를 설명하기 쉽고, 결과가 달라졌을 때 어느 구간을 다시 봐야 하는지도 선명하다.

없다는 결론은 다른 모양으로 한 번 더 묻는다

전체 페이지를 소진한 뒤에도 이름의 다른 표기를 확인한다. 대소문자, 하이픈과 밑줄, import alias, 설정 키처럼 같은 대상을 다른 문자열로 참조하는 경우가 있어서다. 첫 검색과 같은 쿼리를 반복하면 단순 재실행에 머문다. 다른 표기와 다른 경로 축으로 한 번 더 물어야 누락 가능성이 줄어든다.

테스트도 비슷하다. 수정된 호출부의 단위 테스트 통과만으로 이름 변경을 닫기에는 근거가 부족하다. 이전 이름이 저장소에 0건인지, 새 이름의 정의와 호출 수가 예상 범위인지, 설정과 문서가 함께 바뀌었는지를 별도로 확인한다. 실행 동작과 옛 참조 제거 여부는 각자 판정해야 한다.

예를 들어 load_profile을 load_runtime_profile로 바꿨다면 함수 호출 검색만으로 끝내지 않는다. "load-profile" 같은 CLI 문자열, YAML 키, 문서의 명령 예시, 테스트 fixture 안의 이전 이름도 각각 묻는다. 텍스트가 0건이어도 동적 import나 문자열 조합이 의심되면 해당 진입점 테스트를 한 번 더 실행한다. 검색 결과를 코드 이해의 대체물로 쓰지 않는 선이다.

도구 응답에 완전성 계약을 붙인다

에이전트용 검색 도구를 만들 수 있다면 결과 목록 아래에 경계 정보를 강제로 붙이는 편이 낫다. 최소한 총 일치 수, 반환 수, 잘림 여부, 다음 위치, 적용한 제외 조건은 구조화된 필드로 돌려준다. 자연어 경고 한 줄은 긴 결과에 묻히지만, 필드는 하네스가 다음 호출을 강제하는 조건으로 사용할 수 있다.

하네스 쪽 규칙도 단순하게 둘 수 있다. truncated가 true인 동안에는 “전체 수정 완료” 상태로 전환하지 못하게 하고, 다음 offset 또는 더 좁은 쿼리 가운데 하나를 요구한다. 사용자가 일부 결과만 원한 작업이라면 예외로 통과시키되, 응답에 “첫 50건만 확인”을 자동으로 붙인다. 완전성 요구가 작업마다 다르다는 점까지 계약에 포함하는 셈이다.

나는 완료 조건에서 “검색을 실행했다”를 빼고 잘림이 false이거나, 분할한 모든 검색 구간의 수가 설명됐다를 넣는다. 도구가 총 일치 수를 제공하지 않는다면 파일 목록과 일치 건수를 따로 세고, 둘 다 기록한다. 이 정도만 해도 에이전트가 첫 화면을 전체 세계로 착각하는 일이 꽤 줄어든다.

내가 마지막에 보는 세 줄

작업을 닫기 전에는 짧게 세 줄만 확인한다. 첫째, 반환 건수가 도구의 기본 limit와 같지 않은가. 둘째, 잘림·다음 페이지·제외 경로가 남아 있지 않은가. 셋째, “없음”을 다른 표기나 경로로 교차 확인했는가. 셋 중 하나라도 답이 흐리면 완료 문장을 쓰지 않는다.

검색 결과의 첫 페이지는 증거의 시작일 뿐이다. 코딩 에이전트가 빠르게 수정하는 시대일수록, 나는 검색 속도보다 어디까지 봤는지를 기계가 말할 수 있는가를 더 중요하게 본다.

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

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