날짜 필터가 하루씩 밀리는 버그를 고친다고 하자. 코드를 읽다 보면 그 옆에 TODO #417: 캐시 키 형식 정리 같은 주석이 보일 수 있다. 사람이면 이건 다음에 볼 일이라고 넘길 텐데, 코딩 에이전트에게는 그 한 줄도 지금 해결해야 할 문제처럼 읽힐 수 있다. 날짜 버그는 고쳐졌지만, 리뷰할 때 캐시 동작까지 새로 읽어야 한다면 일의 크기가 달라진다.
11월 6일 Google 개발자 블로그의 분석이 이 문제를 다뤘다. 사내에서 파일을 읽은 에이전트 세션의 13%가 버그 번호가 붙은 TODO나 FIXME를 만났다. 그런 주석을 만난 경우의 6%에서 해당 버그를 향한 후속 행동이 있었고, 그 행동 가운데 83%는 사용자가 요청하지 않았다. 이미 닫힌 버그를 뒤쫓기도 했지만, 아직 열린 버그를 자기 일로 가져오는 경우도 있었다. 티켓이 살아 있다는 것과 지금 고쳐야 한다는 것은 다른 얘기다.
Google이 비교한 것은 사내 도구에서 나온 기록이다. 모든 저장소에서 같은 비율로 새거나, 주석을 지우기만 하면 빨라진다는 뜻으로 읽기는 어렵다. 원문에서 티켓 상태뿐 아니라 파일과 변경 이력까지 살핀 것도 그 때문이다. 티켓은 닫혔어도 주석에 남은 제약은 지금 코드에 여전히 필요할 수 있다.
티켓 옆에 완료 조건을 한 줄 더 쓴다
앞의 날짜 필터를 예로 들면 이렇게 나눠 적겠다. ‘이번 변경은 날짜 필터의 경계 계산과 회귀 테스트다. 캐시 키와 응답 형식은 유지한다. #417이 수정에 꼭 필요하다면, 바꾸기 전에 어떤 입력이 왜 틀리는지 남긴다.’ 중요한 것은 파일 이름을 몇 개 허용하느냐보다, 바뀌어도 되는 동작을 먼저 합의하는 데 있다. 계산 함수가 다른 파일에 있는 것까지 금지할 필요는 없다.
검수할 때는 조회 기간을 2026-11-07 하루로 고정하고, 11월 7일 00:00 KST 직전과 직후에 생성된 두 레코드가 각각 제외되고 포함되는지 본다. 11월 8일 00:00 KST의 레코드는 다음 날 몫이다. 날짜 테스트는 통과했는데 키의 구분자나 만료 시간이 바뀌었다면, 그 변경을 날짜 수정의 일부로 받아들일 이유가 있는지 따로 확인할 수 있다. 기존 키 때문에 자정 계산이 실제로 어긋난다면 그때는 설명을 붙여 범위를 다시 정할 일이다. 주석 한 줄만으로 그 결정을 대신할 수는 없다.
지울 주석과 남길 제약을 구분한다
묵은 TODO를 정리할 때도 비슷하다. 티켓이 닫혔다고 그 줄을 모두 지우기보다, 왜 남겼는지 먼저 본다. 예를 들어 ‘구형 클라이언트가 값을 생략한다’는 메모가 아직 맞다면, 완료된 티켓 번호는 떼고 호환 제약을 문장이나 테스트로 남기는 편이 낫다. 반대로 더는 적용되지 않는 계획이라면, 다음 사람이 일을 시작하라는 신호로 읽기 전에 정리해 둘 만하다.
에이전트가 멈출 조건을 정하는 일과도 이어진다. 이번에는 시간이 아니라 변경의 경계를 먼저 그어 본다. 에이전트가 보고한 새 문제를 없던 일로 만들 필요는 없다. 본래 문제의 수정과 별개의 티켓으로 남겨두면, 다음에 맡길 일이 하나 더 생긴 것으로 충분하다.
