최근 웨비나에서 “AI 코딩, 실제로 생산성을 높였을까?”라는 주제로 발표를 진행했는데요.
발표 이후 생각보다 정말 많은 이야기들을 들을 수 있었습니다.
특히 인상 깊었던 건, 많은 사람들이 이미 AI를 꽤 적극적으로 사용하고 있음에도 실제 프로덕션 배포까지에는 어려움과 고민들이 굉장히 많다는 점이었습니다.
“처음엔 엄청 편했는데 점점 유지보수가 어려워져요.”, “PoC 단계에서는 잘 되는데 실제 프로젝트에선 자꾸 꼬여요.”, “AI가 만든 코드를 나중에 보면 왜 그렇게 짰는지 모르겠어요.”, “기능 하나 수정하려다가 프로젝트 구조 전체가 바뀌어요.”, “결국 다시 사람이 다 고치게 돼요.”
저 역시 실무에서 비슷한 작업들을 굉장히 많이 경험했습니다.
처음 AI를 사용할 때는 간단한 유틸리티 함수나 보일러플레이트 코드를 짜는 시간이 획기적으로 줄어 작업이 빨라진다고 느꼈었지만 시간이 지나면서, 오히려 프로젝트가 점점 불안정해지는 순간들이 생기기 시작했습니다.
사실 AI가 짜준 코드는 언뜻 보기에 당장 실행은 되는 80점짜리 완성도를 가집니다. 하지만 진짜 실무 프로덕션에 배포하기 위해 100점까지 필요한 나머지 20점(안정성, 보안, 아키텍처)은 결국 인간 개발자의 몫입니다.
이번 글에서는 제가 실무에서 AI와 협업하며 겪었던 ‘AI 코드를 망치는 대표적인 5가지 실수’를 짚어보고, 이를 어떻게 100점짜리 프로덕션 코드로 끌어올릴 수 있는지 그 구체적인 해결법과 프롬프트 가이드를 공유하고자 합니다.
1. 환각(Hallucination)이 만든 '가짜 라이브러리' 방치
AI는 존재하지 않는 메서드나 오픈소스 라이브러리를 마치 실존하는 것처럼 당당하게 추천하곤 합니다. 혹은 옛날 버전의 레거시 API를 최신 버전인 것처럼 사용해서 코드를 짜주기도 합니다. 당장 로컬 환경에서 에러가 안 난다고, 혹은 AI의 설명이 너무 그럴듯하다고 의심 없이 코드를 넘기면 프로덕션 환경에서 의존성(Dependency)이 꼬이며 대형 장애로 이어질 수도 있습니다.
해결법: 공식 문서 크로스 체크와 패키지 잠금
1) Import문부터 의심하기: AI가 제안한 코드 상단의 import문이나 처음 보는 메서드는 반드시 공식 문서(Official Docs)나 GitHub 저장소에서 현재 지원하는 버전인지 눈으로 확인해야 합니다.
2) 의존성 버전 명시: 패키지 관리 도구(package.json, poetry.lock, requirements.txt 등)에 버전을 명확히 고정하여, AI가 제안한 코드가 런타임 환경에서 튀지 않도록 통제해야 합니다.
개선을 위한 프롬프트 예시
“내가 요청한 기능을 구현하되, 현재 [Next.js v15]와 [Prisma v5] 환경에서 사용 가능한 최신 문법으로 작성해 줘. 존재하지 않는 임의의 메서드를 가상으로 만들어내지 말고, 공식 문서에 명시된 내장 기능만 사용해 줘.”
2. '해피 패스'(Happy Path)만 가득한 예외 처리(Error Handling)의 부재
AI에게 기능을 짜달라고 하면 대부분 외부 API가 무조건 성공하고, 네트워크는 항상 빠르며, DB는 늘 열려있다는 해피 패스(Happy Path) 가정하에 코드를 작성합니다. try-catch문이 있더라도 내부가 비어있거나 print(e) 수준으로 대충 뭉뚱그려 놓기 일쑤입니다. 아무런 검토 없이 사용하게 되면 실제 프로덕션 환경에서 마주하게 될 수 많은 오류들을 처리하지 못하게 됩니다.
해결법: 의도적인 에러 케이스 주입(Fault Injection)
호출 실패 시 재시도(Retry) 로직, 타임아웃 처리, 그리고 에러 발생 시 유저에게 보여줄 폴백(Fallback) 대응이 프로덕션 코드에는 반드시 포함되어야 합니다. 처음 코드를 받은 후, AI에게 의도적으로 ‘실패하는 상황’을 주어서 올바른 예외 처리가 되어 있는지 확인해야 합니다.
개선을 위한 프롬프트 예시
“방금 작성해 준 결제 API 연동 코드에서 만약 (1) 네트워크 타임아웃이 발생하거나, (2) 상대 서버가 500 에러를 반환하는 경우를 대비한 예외 처리 코드를 추가해 줘. 우리 서비스의 공통 에러 핸들러인 CustomException을 던지도록 작성해야 해.”
3. 우리 회사의 아키텍처와 컨벤션 무시 (일관성 붕괴)
AI는 전체 프로젝트의 거대한 아키텍처 맥락을 완전히 이해하지 못합니다. 물론 사용자가 컨텍스트로 전달해주겠지만 AI는 참고를 할 뿐 실제로 모든 맥락을 이해하고 있지 않습니다. 주어진 컨텍스트를 기반으로 가장 그럴듯한 패턴을 추론 할 뿐입니다. 따라서 어떤 파일에서는 함수형으로 짜주고, 다른 파일에서는 객체지향으로 짜주기도 하죠. 레이어드 아키텍처(Layered Architecture)를 쓰고 있는데 AI가 작성한 프론트엔드 코드나 Controller에 비즈니스 로직이 툭 침범해 들어오는 경우가 대표적입니다. 파일마다 스타일이 다른 ‘다중인격’ 프로젝트가 되어 버리는 경우가 많습니다.
해결법: 컨텍스트(Context) 제공과 역할 제한
필요한 컨텍스트를 미리 심어두거나, 질문할 때 AI의 페르소나와 코드의 위치를 명확히 제한해야 합니다. 회사에서 정의된 디자인 패턴이나 네이밍 규칙을 프롬프트에 녹여내거나 미리 규칙이나 페르소나에 설정해두는것이 좋습니다.
개선을 위한 프롬프트 예시
“너는 우리 프로젝트의 [Domain Layer] 코드를 작성하는 꼼꼼한 백엔드 엔지니어 전용 AI야.
우리는 DDD(도메인 주도 설계)를 따르고 있어. 방금 작성한 회원가입 비즈니스 로직에서 DB 접근이나 HTTP 호출 같은 인프라스트럭처 의존성을 완전히 제거하고, 순수한 도메인 엔티티와 비즈니스 규칙만 남기도록 리팩토링해 줘.”
4. '탭(Tab) 연타'가 불러온 생각의 외주화와 기술 부채
“돌아가긴 하는데 왜 돌아가는지 모름”
AI가 IDE에서 회색 글씨로 제안해주는 코드가 편리하다 보니, 깊은 생각 없이 Tab 키만 연타하며 구현하게 되는 경우가 있습니다. 기능은 구현되었지만, 정작 코드를 작성한 개발자가 내부 로직의 흐름을 설명하지 못하는 현상이 발생하게 됩니다. 이는 고스란히 코드 리뷰의 지연과 추후 유지보수의 지옥이라는 기술 부채로 돌아옵니다.
해결법: 스스로 하는 '한 줄씩 코드 리뷰'
1) 내가 설명할 수 없는 코드는 배포하지 않는다: AI가 짠 코드를 프로젝트에 합치기 전, 마치 동료의 코드를 리뷰하듯 모든 라인을 한 줄씩 읽으며 스스로에게 설명해 보세요.
2) 의도 파악하기: 왜 AI가 이 루프를 돌렸는지, 왜 이 자료구조를 선택했는지 의문을 품고 더 나은 대안(예: 시간 복잡도 최적화)이 있는지 고민하는 순간 코드가 100점짜리로 진화합니다.
개선을 위한 프롬프트 예시
“방금 제안해 준 대용량 가입자 통계 처리 알고리즘 코드가 아주 깔끔하네. 이 코드가 대량의 데이터셋에서 가질 수 있는 (1) 시간 복잡도와 공간 복잡도를 분석해 주고, (2) 메모리 누수가 발생할 수 있는 잠재적 위험 구간이 있다면 어디인지 마크다운 표로 정리해 줘.”
5. 보안(Security)과 성능(Performance)의 잠재적 위험 방치
AI는 데이터베이스 조회 코드를 짤 때 N+1 문제를 쉽게 일으키며, 문자열 포매팅으로 쿼리를 대충 이어 붙여 보안 취약점을 만들기도 합니다. 또한 편의를 위해 환경 변수로 빼야 할 API 토큰이나 비밀번호를 코드 내에 슬쩍 하드코딩해 두는 경우도 많아 보안이 허술해지는 경우도 있습니다.
예시로 “블로그 포스트 목록과 각 포스트의 작성자 이름을 가져오는 코드 짜줘”
라고 했을때 실제로 아래와 같은 N+1 형식으로 코드를 작성할 확률이 높습니다.
포스트가 1,000개면 DB 조회가 1,001번 일어나게 됩니다. “로컬에서 잘 돌아가네” 하고 넘어가지 말고, 프롬프트를 통해 JOIN이나 Include 문이 들어간 최적화된 쿼리로 수정해 내는 과정이 절대적으로 필요합니다.
해결법: 정적 분석 도구와 보안 체크리스트 가동
1) 보안 도구 연동: SonarQube, Snyk 등의 정적 분석 및 보안 진단 도구를 통해 AI가 놓친 취약점을 기계적으로 한 번 더 걸러내야 합니다.
2) 성능 스크리닝: 데이터의 양이 많아질 때를 가정하여 (예: 인덱스 활용 여부, 비동기 처리 적용 등) 대규모 트래픽에서도 견딜 수 있는 구조인지 검증하는 단계를 거쳐야 합니다.
개선을 위한 프롬프트 예시 :
“이 코드는 수만 명의 유저가 동시에 사용할 프로덕션 환경에 배포될 예정이야. 보안(SQL Injection, XSS, CSRF) 관점과 성능 관점(인덱스 활용, 불필요한 반복문 제거)에서 치명적인 결함이 없는지 시니어 개발자의 시선으로 엄격하게 코드 리뷰를 해주고, 수정된 코드를 제안해 줘.”
AI 덕분에 우리는 코드를 타이핑하는 ‘코더(Coder)’의 역할에서 벗어나, 코드를 설계하고 검수하는 ‘리뷰어(Reviewer)이자 감독관’의 역할로 빠르게 변화하고 있습니다.
처음 80점짜리 코드인 프로토타입을 만드는 속도는 모두가 비슷합니다. 하지만 나머지 20점을 채워 100점짜리 단단한 프로덕션 코드로 완성해 내는 디테일과 책임감이 앞으로 개발자의 진짜 실력을 가르는 기준이 될 것으로 생각합니다. 오늘부터 AI가 준 코드에 Approve 버튼을 누르기 전에, 위에서 제안했던 완성도를 높일 수 있는 질문들을 한 번 더 던져보시기 바랍니다.
