레거시 시스템에서 AI와 안전하게 협업하기

오래된 레거시 코드베이스 위에서 신규 기능을 개발하고 동시에 기술 부채를 갚아나가는 것은 모든 개발자의 숙명과도 같다. 나는 이 복잡하고 어려운 과제를 해결하기 위해 AI를 적극적으로 활용한다. AI를 단순 코드 생성기가 아닌, 프로젝트의 파트너이자 비평가, 심지어 과외 선생님으로 삼아 레거시 시스템을 헤쳐나가는 나만의 워크플로우를 공유한다.

기획과 설계: AI 비평가 군단을 통한 리스크 최소화

레거시 시스템에 새로운 기능을 추가할 때 가장 두려운 것은 예측하지 못한 사이드 이펙트다. 이를 방지하기 위해 나는 기획 및 설계 단계에서부터 AI를 적극적으로 활용한다. 특히 PRD(제품 요구사항 정의서) 작성 과정에서 AI와 협업하면 놓치는 부분을 크게 줄일 수 있다.

나만의 AI 협업 PRD 작성법

컨텍스트 제공 및 시각 자료 요청: 먼저, 제미니(Gemini)에게 기획서 초안을 마크다운 형식으로 전달한다. 이때 플로우차트나 ERD(개체-관계 다이어그램)가 있다면 함께 제공하는 것이 좋다. 만약 없다면, "이 기획서 초안을 바탕으로 예상되는 사용자 플로우차트와 데이터베이스 ERD를 먼저 만들어줘" 라고 요청하여 시각적인 자료를 확보한다.
구체적인 실행안이 담긴 PRD 생성: 확보된 컨텍스트(초안, 플로우차트, ERD)를 바탕으로, "기존 시스템과의 하위 호환성을 고려하여, 신규 기능을 구현하기 위한 구체적인 실행안이 포함된 PRD를 마크다운 파일 형식으로 상세하게 작성해줘" 라는 프롬프트를 실행한다. 이 단계에서 AI는 개발자가 고려해야 할 기술적 제약사항이나 필요한 API 명세 등을 포함한 초안을 생성해준다.
피드백을 통한 PRD 정제: AI가 생성한 PRD 초안을 꼼꼼히 검토한다. 불필요하거나 잘못된 내용, 혹은 비즈니스 로직상 맞지 않는 부분을 발견하면 구체적인 피드백을 추가하여 수정을 요청한다. "로그인 파트의 로직이 현재 우리 시스템의 인증 방식과 달라. 이 부분은 OAuth 2.0을 사용하는 방식으로 수정하고, 관련된 시퀀스 다이어그램도 추가해줘." 와 같이 명확한 피드백을 통해 PRD의 완성도를 높여나간다.

이러한 과정을 통해 생성된 PRD는 단순한 아이디어의 나열이 아닌, 실제 개발에 바로 적용할 수 있을 만큼 구체적이고 기술적인 깊이를 갖추게 된다.

구현의 시작: 명확한 목표를 제시하는 '기능 프로토타입'

본격적인 코딩에 들어가기 전, 나는 추가하려는 신규 기능의 '기능 프로토타입(Functional Prototype)'을 먼저 만든다. 이는 기존 레거시 시스템과의 연동은 최소화하고, 추가될 기능의 핵심 로직과 사용자 인터페이스(UI)를 독립적으로 구현한 버전이다. 이 프로토타입은 앞으로의 개발 과정에서 AI와 내가 나아가야 할 방향을 명확하게 보여주는 길잡이가 된다.

AI에게 상세한 요구사항과 함께 이 프로토타입 코드를 제공하며 개발을 시작한다. 이때 "기존 코드는 이러이러한 스타일로 작성되어 있으니, 이 컨벤션을 따라서 새로운 코드를 작성해줘" 와 같이 충분한 맥락(Context)을 제공하는 것이 매우 중요하다.

개발과 리뷰: 실시간 AI 페어 프로그래밍

레거시 시스템을 다룰 때 가장 중요한 원칙은 '하위 호환성 유지'다. 섣부른 수정은 대규모 장애로 이어질 수 있기 때문이다. 따라서 AI와 협업할 때는 이 원칙을 명확하게 주지시켜야 한다. AI는 기존 코드를 분석하고 더 나은 방향을 제시하는 데 능하지만, 비즈니스 히스토리나 전체 시스템에 미칠 영향을 고려하지 않고 기존 코드를 바로 수정하려 들 수 있다.

따라서 나는 AI에게 다음과 같이 명확한 가이드라인을 제시한다.

"절대로 기존 코드를 직접 수정하지 마. 대신, 새로운 기능을 추가하거나 기존 기능을 개선할 때는 반드시 하위 호환성을 유지하는 방향으로 제안해줘. 예를 들어, 기존 함수를 수정하는 대신 새로운 함수를 만들고, 점진적으로 전환할 수 있는 마이그레이션 계획을 함께 제시해줘."

이러한 가이드라인 하에, 나는 클로드(Claude)에게 코드 작성을 맡기고, 제미니(Gemini)를 통해 실시간 코드 리뷰를 진행하는 방식으로 AI 페어 프로그래밍을 수행한다. 제미니는 다음과 같은 역할을 한다.

코드 일관성 검토: "새로 추가된 코드가 기존 코드베이스의 컨벤션과 스타일을 잘 따르고 있는가?"
잠재적 버그 탐지: "이 코드가 기존 로직에 영향을 주어 예상치 못한 버그를 만들 가능성은 없는가?"
리팩토링 제안: "새로운 기능을 추가하면서 개선할 수 있는 기존의 비효율적인 코드는 없는가? 단, 하위 호환성을 해치지 않는 선에서 제안해야 해."

물론 AI의 제안을 맹신해서는 안 된다. AI는 종종 그럴듯한 거짓말(Hallucination)을 하므로, 제안된 모든 코드는 동료 주니어 개발자의 코드를 리뷰하듯 꼼꼼히 살펴보고, 직접 테스트하는 과정이 필수적이다.

길을 잃었을 때: 다시 프로토타입을 바라보라

레거시 시스템의 복잡한 구조 속에서 개발을 하다 보면 방향을 잃기 쉽다. 오류가 반복되면 AI는 문제 해결 자체에만 매몰되어 전체 구조를 해치는 코드를 제안하기도 한다. 이때 다시 '기능 프로토타입'을 보여주며 우리의 최종 목표를 상기시킨다. "우리가 만들려는 기능의 핵심은 이것이야. 지금의 접근 방식이 이 목표에 도달하는 가장 효율적이고 안전한 방법이 맞아?" 라고 물으며 큰 그림을 보도록 유도하는 것이다.

결론적으로 나의 AI 활용 전략은, AI를 레드팀, 코드 리뷰어, 그리고 나의 과외 선생님으로 적극 활용하여 레거시 시스템이라는 거대한 산을 넘는 것이다. AI의 한계를 명확히 인지하고, 체계적인 워크플로우를 통해 그 능력을 극대화하는 것. 이것이 복잡한 시스템 위에서 새로운 가치를 만들어내야 하는 우리 개발자들에게 필요한 지혜가 아닐까 생각한다.