AI Prompt 가이드·약 3분 내외

대규모 리팩토링 및 언어 마이그레이션 시 AI 프롬프트 가이드

Python에서 Go로 마이그레이션하거나 대규모 리팩토링을 AI와 진행할 때 발생하는 데이터 누락 문제와 이를 예방하기 위한 핵심 프롬프트 작성 팁을 정리했습니다.

대규모 리팩토링과 AI의 한계

사용자님께서 짚어주신 의문점들은 대규모 리팩토링이나 언어 마이그레이션을 AI와 진행할 때 발생하는 아주 핵심적인 현상들입니다.

예를 들어, Python 백엔드에서 Go 백엔드로 마이그레이션을 진행할 때, 특정 API에서 "로그인한 유저의 좋아요 상태(is_liked)" 등의 데이터가 누락되는 버그가 발생할 수 있습니다.

버그의 진짜 원인 분석

이는 프론트엔드 프레임워크 전환의 문제가 아닙니다. 프론트엔드는 백엔드가 주는 데이터를 그대로 화면에 그리기만 하는데, 백엔드 서버가 특정 API에서 '현재 로그인한 유저의 좋아요 여부'에 대한 데이터를 누락한 채 보내주고 있었기 때문입니다.

원래 마이그레이션 전 백엔드 시절에는 이 상태를 병합해 주는 공통 유틸리티나 데코레이터가 있어서 모든 목록 반환 시 자동으로 붙여줬을 텐데, 다른 언어로 옮기는 과정에서 이 '공통 처리 로직'을 메인 API 한 곳에만 하드코딩하고 다른 곳에는 빼먹은 것이 원인이었습니다.

왜 AI는 완벽하다고 착각할까?

"AI가 "다 완료되었습니다"라고 확신에 차서 말했던 이유는 AI의 '완료 기준'과 사람의 '완료 기준'이 다르기 때문입니다."

표면적 성공 기준

AI는 모든 라우트(URL)가 새 코드로 작성되었고, 컴파일 오류가 나지 않으며, 프론트엔드가 요구하는 기본 JSON 형식(제목, 내용 등)을 반환한다는 사실만으로 "마이그레이션이 100% 끝났다"고 판단합니다.

단편적 시야 (Context Limit)

AI는 보통 파일을 하나씩 쪼개서 번역합니다. 기존 코드에 있던 '전역(Global) 로직'이나 '미들웨어'의 맥락을 완벽히 파악하지 못한 채, 개별 엔드포인트들의 껍데기를 옮기는 데 집중하다 보니 "인증된 유저일 때만 몰래 덧붙여지는 데이터(좋아요, 풀이 여부)" 같은 숨겨진 비즈니스 로직(Cross-cutting concerns)을 놓치게 됩니다.

해결책: 누락을 방지하는 AI 프롬프트 팁

이러한 문제를 예방하려면, 무작정 "마이그레이션 해줘"라고 지시하기보다 작업 순서와 검증 기준을 강제하는 프롬프트 기술이 필요합니다. 다음과 같은 방식의 지시를 추가하시면 훨씬 견고한 결과를 얻을 수 있습니다.

💡 팁 1: 코드 작성 전 공통 로직 분석 먼저 시키기

Go로 코드를 짜기 전에, 기존 Python 코드에서 공통으로 쓰이는 미들웨어, 의존성 주입, 데이터 병합 유틸리티(예: 유저 상태 주입)가 무엇이 있는지 먼저 분석하고 문서로 정리해. 그 이후에 코딩을 시작해.

💡 팁 2: 프론트엔드 스펙을 절대적인 기준으로 강제하기

단순히 에러 없이 실행되는 게 목표가 아니야. 프론트엔드의 apiClient.ts나 타입스크립트 인터페이스를 꼼꼼히 확인해서, 로그인한 유저일 때 반환해야 하는 is_liked, is_solved 같은 선택적 필드들이 모든 조회 API에서 100% 매핑되는지 검증해.

💡 팁 3: 시나리오 기반의 교차 검증 지시

마이그레이션이 끝났다고 판단하기 전에, '로그인하지 않은 유저'와 '로그인한 유저' 두 가지 관점에서 데이터를 조회했을 때 빠지는 필드가 없는지 스스로 코드 리뷰를 진행해.

요약하자면, AI에게 숲(전체 아키텍처와 공통 로직)을 먼저 보게 한 뒤 나무(개별 API)를 옮기도록 지시하고, 단순 컴파일 성공이 아니라 '데이터 무결성'을 완료 기준으로 삼도록 프롬프트를 주시는 것이 좋습니다.

이정마 에디터

AI Engineer

AI는 종종 에러 없이 구동되는 표면적인 결과에만 집중합니다. 숨겨진 비즈니스 로직이나 전역 미들웨어를 놓치지 않도록 전체 맥락(숲)을 먼저 파악하게 하는 프롬프트 기법이 중요합니다.