에이전트가 함수 이름을 변경했을 때 놓치기 쉬운 문자열 참조

안전해 보이는 이름 변경

당신은 에이전트에게 process_payment를 settle_payment로 이름을 바꾸라고 요청합니다. 에이전트는 코드베이스 전체를 훑어보며 모든 임포트를 업데이트하고, 정의를 변경하며, 독스트링을 업데이트하고, 깔끔한 PR(Pull Request)을 열어줍니다. diff는 14개 파일이며, 모든 hunk는 깨끗한 이름 변경이고, linter도 통과하고, 단위 테스트(unit tests)도 통과합니다.

CI(Continuous Integration)에서 아무 문제도 플래그하지 않습니다. 이틀 후, 매시간 실행되도록 예약된 작업이 조용히 작동을 멈춥니다. cron 항목에는 여전히 handler = 'jobs.process_payment'라고 적혀 있습니다. 디스패처는 이름으로 문자열을 조회하여 아무것도 찾지 못하고, 조회 오류를 무시합니다.

정적 이름 변경이 놓치는 이유

이름 변경 도구(rename tool)는 심볼로 해결할 수 있는 식별자(identifiers)만 다시 작성합니다. 문자열 안에 존재하는 참조는 그 관점에서는 심볼이 아닙니다. 그것은 데이터입니다.

함수 이름이 문자열로 살아남을 수 있는 장소 목록은 사람들이 생각하는 것보다 길습니다:

• 핸들러를 점 경로(dotted path)로 해결하는 cron 작업 설정 및 태스크 러너
• URL 경로를 뷰 이름에 매핑하는 라우트 테이블
• 팩토리를 이름으로 조회하는 DI 컨테이너 및 서비스 로케이터
• 콜백 이름을 참조하는 기능 플래그(Feature-flag) 설정
• 이벤트 핸들러 또는 플러그인 시스템의 동적 디스패치(Dynamic dispatch)
• 에이전트가 보지 못하는 별도의 e2e 스위트에 있는 테스트 이름
• 오래된 이름을 출력하는 문서화 문자열 및 오류 메시지 (미관상의 문제일 수 있지만 혼란스러움)

process_payment에 대한 에이전트의 grep은 임포트 라인을 포착할 것입니다. 하지만 그 파일이 지정된 디렉터리 밖에 있거나, YAML 형식이라 이름 변경 도구가 그것을 불투명한 데이터(opaque data)로 취급하는 경우, cron.yaml 안의 문자열은 포착하지 못합니다.

놓친 것을 잡아내는 저렴한 가드

에이전트가 이름 변경 작업을 수행하기 전에, 한 가지 추가적인 일을 하도록 요청하세요:

이름을 바꾼 후, 전체 리포지토리(yaml, json, toml 및 모든 설정 디렉터리 포함)를 훑어보면서 이전 이름을 문자열 리터럴로 검색합니다. 발견된 모든 항목을 나열하고, 업데이트가 필요한지, 하위 호환성을 위해 유지해야 하는지, 아니면 제거해야 하는지 말해줍니다.

그러한 프롬프트 단계는 cron 항목, 라우트 테이블, 그리고 DI(Dependency Injection) 등록까지 포착합니다. 또한 이전 이름이 의도적으로 공개 별칭(public alias)으로 유지되는 경우에도 이를 포착하는데, 이 경우에는 에이전트가 조용히 누락시키는 것이 아니라 명시적으로 그렇게 말해야 합니다.

두 번째로, 훨씬 저렴한 검사는 이름을 변경한 후 애플리케이션의 시작 경로를 실행하는 것입니다. 대부분의 디스패처(dispatcher) 및 라우트 등록 오류는 cron 작업이 발동하기 훨씬 전에 앱이 부팅되는 순간 '모듈을 찾을 수 없음' 또는 '핸들러가 등록되지 않음'과 같은 형태로 나타납니다. 만약 에이전트가 npm start (또는 이에 상응하는 명령)를 실행하고 부팅 로그를 붙여넣을 수 있다면, 누락된 참조는 5초 만에 드러날 것입니다.

검토 시 확인해야 할 사항

이름 변경 PR(Pull Request)가 당신의 책상에 도착했을 때, 질문은 '모든 import가 업데이트되었는가?'가 아닙니다. 질문은 다음과 같습니다:

• 에이전트의 grep 검색 범위에 코드뿐만 아니라 설정 파일과 문자열도 포함되는가?
• 이름 변경 후 애플리케이션이 부팅되었는가?
• 기존 호출자들을 위해 유지되어야 하는 공개 별칭(public alias)이 있는가?

.py 또는 .ts 파일만 건드리고 부팅 로그를 보여주지 않는 이름 변경은 검증되지 않은 것입니다. 그것은 단지 정적으로 재작성되었을 뿐입니다. 런타임 참조는 정적 분석이 볼 수 없는 바로 그 부분입니다.

API 이름 변경에서도 동일한 격차가 발생합니다

에이전트들은 API 필드나 라우트 경로를 이름을 변경할 때도 같은 일을 합니다: 컨트롤러, 요청 유형(request type), 그리고 README의 OpenAPI 스니펫을 업데이트합니다. 하지만 프로덕션 클라이언트(모바일 앱, 브라우저 확장 프로그램, 타사 통합)가 여전히 이전 이름으로 데이터를 보내는지는 확인하지 않습니다.

우리가 Powerduck에서 적용한 로컬 가드(local guard)는 이름을 변경한 후 스펙을 라이브 엔드포인트에 재실행하는 것입니다. 프로덕션에서 여전히 작동하는 이전 클라이언트 페이로드(payload)가 검사를 깨뜨리면 (좋습니다, 출시 전에 알아냅니다) 또는 별칭이 여전히 허용됨을 확인하면 (좋습니다, 의도적으로 하위 호환성을 유지했음을 알게 됩니다). 어느 쪽이든, 코드베이스 외부에 존재했던 문자열 참조는 검토 시의 놀라움거리가 아니게 됩니다.

내일 변경할 사항

다음번에 에이전트가 이름 변경(rename) PR을 열면, 승인 버튼을 누르기 전에 부팅 로그와 문자열 검색(string-grep) 히트를 요청하세요. 이름 자체는 아마 정확할 겁니다. 런타임에 문제를 일으키는 것은 아무도 에이전트에게 찾아보라고 말해주지 않은 참조 부분일 거예요.