레거시 코드 한 줄 고치기 전 — 5분 점검

레거시 코드를 고칠 때마다 드는 생각이 있다. ‘이 한 줄짜리인데 뭐가 문제겠어.’ 그 확신이 가장 위험하다.

먼저 ‘이 코드가 실제로 불리는지’ 확인한다

죽은 코드를 고치다 장애를 낸 적이 있다. 정말로. 2026년 초, 결제 모듈 안에 10년 된 메서드가 있었는데 IDE에서 참조가 0으로 보였다. 안심하고 로직을 바꿨더니 새벽 배치가 직접 문자열로 메서드명을 호출하고 있었다. 리플렉션으로.

grep 한 번으로 끝낼 수 있다. grep -rn "methodName" 찍고 결과를 3초 읽으면 된다. IDE 참조 검색은 리플렉션·동적 호출을 못 잡으니 믿지 마라. 그날 이후 나는 코드 검색을 두 번씩 돌린다 — IDE로 한 번, 터미널 grep으로 한 번.
배치 스케줄러 설정 파일도 같이 본다. cron, Quartz, Airflow DAG 어디에든 하드코딩된 클래스명·메서드명이 숨어 있을 수 있다. 특히 레거시 프로젝트는 config/ 아래에 XML이 쌓여 있어서 Java 파일만 보면 절반을 놓친다.

수정하기 전에 딱 한 줄 — ‘나는 X를 Y로 바꾼다. 이유는 Z’ — 를 주석 혹은 PR 설명에 먼저 쓴다. 막상 써보면 Z가 모호할 때가 많다. Z가 모호하면 수정하지 않는다.

한 줄 요약이 안 되는 수정은 범위가 너무 크다는 신호다. 최근에 팀원이 ‘config 정리하려고요’라고 PR을 올렸는데 파일이 23개 바뀌어 있었다. 리뷰하다 중간에 놓쳐서 스테이징에서 NullPointer 하나 터졌다. 한 줄로 못 쓰면 커밋을 쪼개야 한다.
이 습관의 부수 효과가 있다. 사후 장애 보고를 쓸 때 PR 설명이 이미 반쯤 적혀 있다. 귀찮음을 두 번 나눠 쓰는 셈이다.

고칠 메서드가 무엇을 호출하고, 어디서 호출받는지. 양방향 2단계만 봐도 영향 범위의 80%가 보인다.

위로: 누가 이 메서드를 쓰는가. 컨트롤러인지, 서비스인지, 외부 API 콜백인지. 콜백이면 타임아웃·재시도 로직이 붙어 있을 가능성이 높다. 그걸 모르고 반환 타입을 바꾸면 호출부에서 조용히 실패한다.
아래로: 이 메서드가 부르는 것들이 side effect를 내는가. DB write, 외부 API call, 파일 I/O. 순수 계산 함수라면 부담 없이 고쳐도 되는데, 레거시에서 ‘순수 함수처럼 생긴 것’이 사실 내부에서 전역 캐시를 날리는 경우가 꽤 있다. 함수 이름만 믿지 마라.

레거시에는 테스트가 없다. 그게 레거시의 정의에 가깝다. 그렇다고 수정을 포기할 수는 없으니, 현재 동작을 먼저 기록해 둔다.

입출력 쌍을 3~5개 뽑아서 임시 테스트로 만든다. 이걸 ‘특성화 테스트(characterization test)‘라고 부르는데, 올바른 동작을 검증하는 게 아니라 ‘지금 이 코드가 이렇게 동작한다’는 사실을 고정하는 것이다. 수정 후에 이 테스트가 깨지면 동작이 바뀐 것이고, 그때 의도된 변경인지 아닌지 판단하면 된다.
실제로 지난 분기, 세금 계산 로직을 건드릴 때 이렇게 했다. 입력 10가지를 뽑아 기존 반환값을 하드코딩한 테스트를 먼저 커밋했다. 수정 후 테스트 3개가 깨졌고, 그중 2개는 의도된 것, 1개는 엣지 케이스를 놓친 것이었다. 그 1개를 배포 전에 잡았다.

수정이 잘못됐을 때 어떻게 되돌리는가. 이걸 모르고 배포하면 장애 중에 처음 알아보게 된다. 그때는 이미 너무 늦다.

feature flag 가 있으면 제일 편하다. 없으면 이번 커밋 하나만 되돌려도 되는 구조인지 확인한다. DB 스키마 변경이 섞여 있으면 코드 rollback 이 곧바로 안 된다. 그런 경우는 배포 전에 반드시 팀에 공유하고, DB 변경을 backward-compatible 하게 나눠서 진행한다.
롤백 명령어를 미리 터미널에 적어두는 습관을 올해부터 들이고 있다. git revert, kubectl rollout undo, 혹은 해당 flag 를 false 로 바꾸는 curl 한 줄. 배포 당일 슬랙에 올려두면 다른 팀원이 먼저 눌러줄 수도 있다.

다음에 레거시를 건드릴 때, 수정 전 5분 체크리스트를 PR 템플릿에 체크박스로 박아두기로 했다. ‘했나’를 물어봐야 ‘한다’.

🛒 이 글과 어울리는 추천 상품

위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.