레거시를 한 번에 바꾸지 않은 이유

셈웨어에서 웹사이트 리뉴얼과 교육 플랫폼을 다루던 시기, 기존 내장 라이브러리 의존을 API 기반으로 옮기는 작업도 했다. 새 구조를 생각하는 것보다 먼저 해야 했던 일은 기존 구조가 실제로 무엇을 하고 있는지 읽는 것이었다. 오래된 코드라는 사실만으로 그 안의 규칙까지 낡았다고 판단할 수는 없었다.

운영 중인 기능에는 문서 밖의 계약이 있었다

코드에 남아 있는 분기에는 사용자가 기대하는 동작이 섞여 있다. 입력이 비어 있을 때의 처리, 오래된 콘텐츠의 예외, 특정 호출 순서 같은 것들이다. 재작성할 때 이를 단순한 중복으로 보면 화면은 깔끔해져도 동작이 달라질 수 있다.

당시에는 기존 코드를 분석하고, API 응답 구조와 타입을 정한 뒤 기능 단위로 전환하는 방향을 택했다. 전체를 한 번에 바꾸는 방식보다 시간이 더 들 수 있지만 변경 범위를 설명할 수 있다는 장점이 있었다. 문제가 생겼을 때 어느 기능 경계로 돌아가야 하는지도 상대적으로 명확했다.

타입이 설명해 주는 것과 못 하는 것

응답 타입은 화면이 어떤 데이터를 기대하는지 공유하는 데 도움이 됐다. 다만 필드 이름과 자료형이 같아도 의미가 달라질 수 있다. 빈 배열이 정말 결과 없음인지, 조회 실패인지, 아직 준비되지 않음인지까지 타입과 응답 계약에서 구분해야 한다.

지금 다시 진행한다면 기존 응답과 새 응답의 예시를 나란히 놓고 비교하겠다. 정상 데이터만이 아니라 빈 값과 누락된 값도 포함하겠다. 필드 수가 맞는지보다 소비자가 같은 결정을 내릴 수 있는지가 중요하기 때문이다.

가장 아쉬운 부분은 자동 검증이었다

당시 회고에도 테스트와 문서화가 충분하지 않았다는 점을 남겼다. 점진적으로 전환한다고 해서 자동으로 안전해지는 것은 아니다. 작은 변경이라도 기존 동작을 확인할 기준이 없으면 위험을 잘게 나눴을 뿐이다. 다시 한다면 가장 중요한 기존 동작부터 재현 가능한 입력과 기대 결과로 남기겠다.

레거시 작업은 새로운 코드를 많이 쓰는 능력보다 바꾸지 말아야 할 것을 알아보는 능력을 요구했다. 나는 이 경험에서 코드의 연식보다 운영의 연속성을 먼저 보는 기준을 얻었다. 전환 계획에는 새 구조뿐 아니라 되돌아갈 경로도 있어야 했다.

관련 기록: 셈웨어 프로젝트 사례