화면을 그대로 옮기지 않았다 — 이관 전에 대상 시스템의 컨벤션부터 읽은 이야기

관련 프로젝트: 사내 Portal 어드민 이관·모노레포 설계

시설 관리 메뉴를 별도 시스템에서 사내 Portal로 옮기는 작업이었다. 가장 빠른 방법은 화면 코드를 그대로 복사해 붙여넣는 것이다. 동작은 한다. 그런데 그 방법을 쓰지 않았다.

문제 — 그대로 옮기면 저장소 안에 서로 다른 언어가 섞인다

두 시스템은 각자 다른 디렉터리 배치, 라우팅 방식, API 계층, 상태 관리 패턴을 갖고 있었다. 코드를 그대로 옮기면 동작은 즉시 확인되지만, 결과물은 한 저장소 안에 두 가지 코드 스타일이 공존하는 상태가 된다.

이게 왜 문제인가. 이관을 끝낸 뒤에 그 코드를 유지보수하는 건 내가 아닐 수도 있다. 다른 개발자가 그 메뉴 옆에 새 화면을 추가하려 할 때, 어느 쪽 패턴을 따라야 할지 코드만 봐서는 알 수 없다. 이관된 코드가 "옛날 방식의 화석"으로 남으면, 그 구역은 계속 다른 규칙으로 굴러가는 섬이 된다.

접근 — 옮기기 전에 먼저 읽는다

순서를 바꿨다. 코드를 옮기기 전에 대상 시스템의 소스를 먼저 읽었다.

• 디렉터리를 어떻게 나누는가
• 라우팅을 파일 기반으로 하는가, 설정 기반으로 하는가
• API 호출을 어느 계층에 두는가 (컴포넌트 직접 호출인지, 별도 서비스 레이어인지)
• 상태 관리를 전역으로 두는지, 화면별로 지역화하는지

이 패턴을 파악한 다음, 원본 시스템의 기능을 그 컨벤션 위에서 재구현했다. 코드를 복사한 게 아니라, 같은 기능을 대상 시스템의 언어로 다시 썼다는 표현이 더 정확하다.

효과 — 이관 후에도 코드가 한 가지 언어로 읽힌다

작업량만 보면 복사보다 느리다. 하지만 결과가 다르다. 이관이 끝난 뒤에도 그 메뉴는 원래부터 그 시스템에 있었던 것처럼 읽힌다. 다른 개발자가 그 옆에 화면을 추가할 때, 기존 이관 코드를 참고하면 대상 시스템의 패턴을 그대로 따라갈 수 있다.

이관 작업의 완료 기준을 "화면이 동작하는가"가 아니라 **"이 코드베이스를 다음에 만지는 사람이 규칙을 유추할 수 있는가"**로 잡은 것이 이 접근의 핵심이었다.

정리

빨리 옮기는 것과 잘 옮기는 것은 다른 목표다. 이관 작업의 산출물은 "동작하는 화면"이 아니라 **"다음 사람이 이어받을 수 있는 코드베이스"**라고 기준을 다시 잡으면, 컨벤션을 먼저 읽는 시간은 비용이 아니라 필수 단계가 된다.