AI 코딩 전, 시니어 엔지니어가 설계에 30%를 쓰는 이유
최근 "AI가 코딩을 다 해주는데, 앞으로 개발자의 역할은 무엇인가?"라는 질문이 자주 등장합니다.
명령어 몇 줄로 보일러플레이트를 만들고, 에러 로그를 붙여 넣으면 수정 코드를 제안받는 경험은 이제 낯설지 않습니다.
그래서 AI 코딩 도구를 사용하면 소프트웨어 개발의 대부분이 자동화될 것처럼 보이기도 합니다.
하지만 복잡한 비즈니스 규칙과 실시간 데이터 정합성이 얽힌 프로덕션 개발에서는 이야기가 달라집니다. 단순한 화면 구현을 넘어, 도메인 로직과 상태 변화가 서로 연결된 시스템에서는 "일단 AI에게 고쳐 달라고 하는 방식"만으로는 안정적인 결과를 얻기 어렵습니다.
저희는 최근 회원 데이터와 거래 전표, 실시간 통계 대시보드가 연결된 시스템을 구축했습니다.
이 과정에서 AI를 단순한 코드 생성 도구가 아니라, 설계된 범위 안에서 활용하는 엔지니어링 자원으로 다루는 방식을 실험했습니다.
이 글에서는 AI 협업 개발로 프로덕션 품질을 확보하기 위해 어떤 설계와 테스트 체계가 필요했는지 공유하려 합니다.
1. '이 코드 고쳐줘' 식의 바이브 코딩이 무너지는 이유
많은 개발자가 AI에게 에러 로그나 일부 코드만 전달하고 "이것 좀 고쳐줘"라고 요청합니다. 작은 기능이나 독립적인 화면에서는 이 방식이 빠르게 느껴질 수 있습니다. 하지만 시스템의 책임이 커질수록 이런 바이브 코딩 방식은 구조적인 한계를 드러냅니다.
첫 번째 문제는 컨텍스트 윈도우의 한계입니다.
대화가 길어질수록 AI는 전체 시스템의 데이터 흐름과 이전 의사결정을 놓치기 쉽습니다. 화면 단위의 오류는 해결됐지만, 거래 전표 수정 후 대시보드의 누계 값이 맞지 않거나 특정 상태 전환에서만 데이터가 어긋나는 문제가 생길 수 있습니다.
두 번째 문제는 임시방편 코드의 누적입니다.
AI는 전체 데이터 라이프사이클이나 객체 간 참조 관계를 완전히 이해하지 못한 상태에서도, 당장의 런타임 에러를 피하는 코드를 제안할 수 있습니다. 아키텍처 기준 없이 이를 수용하면 한 곳을 고쳤을 때 다른 모듈이 깨지는 회귀 오류가 반복됩니다.
결국 AI 코딩 도구를 실무에 도입하려면, 먼저 도메인의 규칙과 시스템의 책임 경계를 명확히 정의해야 합니다.
이번 프로젝트에서는 전체 일정의 약 30%를 기획과 구조 설계에 배정했습니다. 설계, 개발, 디자인, 마크업, 테스트를 모두 포함한 일정에서 30%는 작은 비중이 아닙니다. 하지만 예외 상황과 엣지 케이스를 사전에 정의한 덕분에 개발 후반부의 재작업 비용을 줄일 수 있었습니다.
2. AI가 잘 이해할수 있는 언어로 정의하기
AI와 협업할 때 중요한 것은 더 긴 프롬프트를 작성하는 것이 아니라, AI가 일관되게 추론할 수 있는 구조화된 컨텍스트를 제공하는 것입니다. 모호한 자연어 기획서만으로는 복잡한 비즈니스 규칙을 안정적으로 구현하기 어렵습니다.
기획 디스크립션을 Markdown 명세로 정리하기
디자인 시안과 기능 설명이 담긴 피그마 디스크립션을 분석해, AI가 파싱하기 쉬운 Markdown 명세서로 정리했습니다.
화면 단위 설명, 상태별 규칙, 입력값 제약, 예외 케이스를 분리해 기록했고, AI에게 "무엇을 만들어야 하는지"를 설명하는 자료이자, 사람이 요구사항을 다시 검토하는 기준점이 되었습니다.
DDD 기반의 Ubiquitous Language 사전 만들기
소통 오차를 줄이기 위해 UI 용어, 백엔드 API 스키마, DB 필드명을 일대일로 매핑한 용어 사전을 만들었습니다. 같은 개념을 사람마다 다르게 부르면 AI 역시 다른 개념으로 해석할 가능성이 높아집니다. 그래서 도메인 주도 설계(DDD)의 Ubiquitous Language처럼, 프로젝트 안에서 사용하는 언어를 먼저 통일했습니다.
기획/UI 용어 | 백엔드 / DB 필드명 | 규칙 및 제약사항 |
|---|---|---|
거래 대상량 | purchasableQuantity | 파트너 등급 규칙에 의해 자동 계산, 수동 수정 불가 |
추가 유보금 | investmentDeduction | 기본 공제액과 초과 공제액의 합계로 산출 |
내역번호 | acquisitionItemNo | 전표 내역의 고유 식별 코드, 연도 내 고유성 보장 |
이 용어 사전은 AI 세션을 새로 열 때마다 함께 제공했습니다. 덕분에 프론트엔드, 백엔드, 데이터베이스의 명칭이 어긋나는 문제를 줄일 수 있었습니다.
ADR로 의사결정의 맥락 남기기
복잡한 예외 로직은 시간이 지나면 "왜 이렇게 구현했는지" 알기 어려워집니다. 이를 방지하기 위해 주요 설계 판단은 ADR(Architecture Decision Record)로 기록했습니다.
ADR은 새로 합류한 팀원에게도 도움이 되지만, AI에게 프로젝트의 제약과 히스토리를 주입하는 데도 효과적이었습니다. 단순히 현재 코드만 보여주는 것이 아니라, 왜 이런 구조를 선택했는지 함께 제공했기 때문에 AI의 제안도 프로젝트 맥락에 더 가까워졌습니다.
또한 기획 명세 단계에서는 AI에게 까다로운 수석 아키텍트 역할을 부여해 엣지 케이스와 논리적 모순을 질문하게 했습니다. 구현을 시작하기 전에 정책적 오류를 먼저 드러내기 위한 과정이었습니다.
3. 회귀 오류 막기 위한 테스트 자동화 구축
AI 기반 개발에서 프로덕션 품질을 결정짓는 마지막 기준은 테스트입니다. 사람이 화면을 눈으로 확인하고 넘어가는 방식만으로는 AI가 만든 코드의 미세한 엣지 케이스를 잡아내기 어렵습니다.
데이터 정합성을 검증하는 API E2E 테스트
백엔드 개발 단계에서는 테스트용 격리 DB를 독립적으로 구성했습니다. 그리고 거래 전표 발행, 파트너 데이터 갱신, 최종 대시보드 메트릭 반영까지 이어지는 데이터 라이프사이클을 시나리오 기반 E2E 통합 테스트로 검증했습니다.
핵심은 단일 API의 성공 여부가 아니라, 여러 기능이 연결된 뒤에도 데이터 정합성이 유지되는지를 확인하는 것이었습니다. 정산 금액, 누계 수치, 상태 전환 값처럼 작은 오차가 큰 문제로 이어질 수 있는 항목은 테스트 케이스로 명시했습니다.
Playwright로 UI 계산 로직 검증하기
프론트엔드에서는 회원 조건과 가중치에 따라 수수료율이나 공제액 비율이 리액티브하게 계산되는 영역이 있었습니다. 이 부분은 Playwright 기반 UI E2E 테스트를 도입해 브라우저 런타임 수준에서 계산 결과와 UI 상태를 검증했습니다.
폼 입력, 상태 변경, 자동 계산 필드, 반응형 화면에서의 표시 여부를 함께 확인했습니다. 이를 통해 리팩터링하거나 기능을 추가할 때 기존 비즈니스 로직이 깨지는 회귀 오류를 조기에 발견할 수 있었습니다.
4. 역할을 분리한 AI 협업과 컨텍스트 관리
설계와 테스트 체계를 갖춘 뒤에도 해결해야할 문제가 있었습니다.
하나의 AI 세션에 설계, 구현, 기술 조사, 디버깅을 모두 맡기면 대화가 길어질수록 컨텍스트가 섞이고 답변의 일관성이 떨어진다는 것이였습니다.
이 문제를 해결하기 위해 역할을 먼저 분리하는 방식으로 진행하고자 했습니다.
하나의 AI에게 모든 역할을 맡기지 않기
AI는 한 번에 하나의 역할에 집중할 때 더 안정적인 결과를 낼 수 있습니다.
반대로 설계, 구현, 기술 조사, 디버깅을 모두 하나의 대화에서 처리하면 중요한 컨텍스트가 밀려나고, 이전 결정과 충돌하는 답변이 나오기 쉽습니다.
이를 방지하기 위해 역할을 다음과 같이 나눴습니다.
어떤 모델을 사용하느냐보다, 각 역할이 서로 다른 책임을 갖도록 운영하는 것이 더 중요했습니다.
기술 조사는 별도 세션에서 처리하기
메인 개발 세션에서 라이브러리 사용법이나 API 문서를 계속 질문하면 핵심 소스 코드 컨텍스트가 빠르게 희석되기 떄문에 기술 조사와 코드 구현을 분리했습니다.
이 방식은 불필요한 컨텍스트 오염을 줄이고, 긴 개발 과정에서도 코드의 일관성을 유지하는 데 도움이 되었습니다.
마치며
AI가 코드를 작성하는 시대가 왔습니다. 하지만 좋은 소프트웨어는 여전히 사람이 문제를 정의하고, AI는 그 설계를 빠르게 구현하는 역할을 합니다. AI 시대의 경쟁력은 단순한 코딩 속도가 아니라, 복잡한 문제를 정확히 구조화하는 설계의 품질에 있다고 생각합니다.
AI는 주어진 맥락 안에서는 빠르게 작업하지만, 어떤 맥락을 제공해야 하는지, 어디까지 자동화하고 어디서 검증해야 하는지는 결국 엔지니어가 판단해야 합니다.
결국 AI를 잘 활용하는 엔지니어는 코드를 덜 쓰는 사람이 아니라, AI가 올바른 코드를 만들 수 있도록 더 명확하게 설계하는 사람이라고 생각합니다.