AI가 짠 코드의 품질을 의심하는 법: 1인 개발자를 위한 8가지 검증 원칙

그럴듯한 화면이 준 착각

ShopifyShopify디지털 및 실물 매장을 호스팅하고 다국어 번역, 글로벌 결제 및 맞춤형 앱 생태계를 제공하는 세계적인 커머스 플랫폼입니다.Read More → 멤버십 앱의 첫 데모 빌드가 성공했을 때, 나는 흥분을 감추지 못했다. 화면에는 깔끔한 대시보드가 떴고, 설정 메뉴의 토글 버튼들은 부드럽게 작동했으며, 포인트 적립 규칙을 입력하는 폼도 완벽해 보였다. 마우스를 클릭할 때마다 화면이 기민하게 반응했다. AI 코딩 도구에 몇 번의 지시어를 입력한 지 단 이틀 만에 얻은 결과였다. 이 속도라면 다음 주에 당장 앱스토어에 출시할 수 있을 것 같았다.

하지만 기쁨은 오래가지 않았다. 테스트 계정으로 상점에서 실제 결제를 진행하고 고객 등급을 올리려 하자, 앱은 아무런 반응도 하지 않았다. 코드를 뜯어보고서야 차가운 진실을 마주했다. 화면에 표시된 그럴듯한 숫자들은 전부 AI가 임의로 채워 넣은 Mock Data(가짜 데이터)였고, 정작 돈을 처리하는 결제 API와 포인트 적립 웹훅, 자동 할인 트리거는 단 한 줄도 작성되어 있지 않았다. 껍데기만 존재하고 알맹이는 없는 상태였다.

나는 전문 소프트웨어 엔지니어가 아니다. IT 프로젝트 매니저(PM)로 일하며 필요한 제품을 AI의 힘을 빌려 직접 만들고 배포하는 1인 제작자에 가깝다. 웹사이트 분석 SaaS인 AttractiveWebAI, ShopifyShopify디지털 및 실물 매장을 호스팅하고 다국어 번역, 글로벌 결제 및 맞춤형 앱 생태계를 제공하는 세계적인 커머스 플랫폼입니다.Read More → 멤버십 앱, 그리고 macOS 창 미리보기 유틸리티까지 여러 제품을 개발하면서 Gemini, Claude, Codex 같은 도구들을 전방위로 활용했다.

처음에는 원하는 기능을 대강 묘사하면 알아서 작동하는 코드가 뚝딱 나오는 속도에 취해 있었다. 그러나 프로젝트 규모가 커지고 기능들이 얽히기 시작하자, 화면 뒤에 숨어 있던 결함들이 일제히 머리를 치켜들기 시작했다.

---

AI가 숨겨둔 10가지 부채

배포 단계를 거치며 뼈아프게 기록한 실패의 목록은 생각보다 길고 구체적이었다.

1. DB 저장 누락: 프론트엔드 폼에서 '저장' 버튼을 누르면 화면에 성공 메시지가 뜨지만, 정작 Supabase 데이터베이스에는 아무것도 입력되지 않은 채 메모리 안에서만 데이터가 맴돌다 사라졌다.
2. API 연결 증발: 프론트엔드 UI의 멋진 버튼과 입력창은 완성되었으나, 백엔드 API 엔드포인트와 통신하는 코드가 누락되어 실제 서비스가 동작하지 않았다.
3. 가짜 데이터의 방치: 개발 편의를 위해 임시로 삽입한 Mock Data와 테스트용 하드코딩 값이 실제 운영 모드에서도 그대로 사용되고 있었다.
4. 동일 코드의 중복 생성: AI가 기존 프로젝트의 전체 구조를 기억하지 못해, 이미 존재하는 유틸리티 함수나 컴포넌트를 이름만 조금 바꾼 채 서너 개씩 중복으로 새로 만들어냈다.
5. 회귀(Regression) 오류: 한 곳의 버그를 고치기 위해 코드를 수정하면, 이전에 잘 작동하던 전혀 다른 페이지의 기능이 깨져버리는 현상이 반복됐다.
6. 빌드 성공의 함정: npm run build나 TypeScript 타입 검사는 완벽하게 성공했지만, 런타임에 특정 조건에서 브라우저가 흰 화면만 뿜어내는 치명적인 오류가 발생했다.
7. console.log만 남은 보고: AI가 기능 구현을 마쳤다고 당당히 답했으나, 코드를 열어보니 알맹이 대신 console.log("TODO: 구현 예정") 주석만 덩그러니 남겨져 있었다.
8. 데이터베이스 스키마 누락: 로컬 개발 환경에서 Supabase 테스트 계정으로 잘 되던 기능을 실제 운영용 Supabase 계정으로 옮기면서, 코드와 환경변수는 바꿨지만 SQL 테이블과 트리거 스키마를 이관하지 않아 서비스 전체가 멈췄다.
9. 핵심 로직의 생략: ShopifyShopify디지털 및 실물 매장을 호스팅하고 다국어 번역, 글로벌 결제 및 맞춤형 앱 생태계를 제공하는 세계적인 커머스 플랫폼입니다.Read More → 앱 배포 과정에서 화면 디자인은 끝났으나, 정작 핵심인 Billing API 연동과 자동 할인 정책 호출 로직이 연결되지 않아 실제 수익 모델을 검증할 수 없었다.
10. 시스템 권한 인식 오류: macOS 창 미리보기 유틸리티 개발 중, OS 설정 화면에서 접근성 권한과 화면 기록 권한이 켜져 있는 것처럼 보여도 실제 런타임 코드에서는 해당 권한 상태를 감지하지 못해 먹통이 되는 디바이스 수준의 예외가 빈번했다.

이 실패들을 수습하며 밤을 새우다 보니 한 가지 깨달음이 머리를 쳤다. AI 코딩에서 진짜 병목은 코드를 짜는 행위 자체가 아니었다. AI가 뱉어낸 코드를 검증하고, 그것이 '완전히 완료되었다'는 사실을 인간의 눈으로 입증하는 과정이 핵심이었다. 이를 방치하면 제품은 작동하는 척하는 기술 부채의 거대한 늪으로 변해버린다.

이 시행착오를 건너며 내가 정립한 8가지 코드 품질 검증 원칙을 공유한다.

---

원칙 1. 요청하기 전에 완료 조건(Definition of Done)부터 적는다

AI에게 "로그인 기능 만들어줘"라고 모호하게 요청하면, AI는 임의로 쉬운 방법을 찾아 대충 동작만 하는 코드를 짠다. 나는 기능을 요구하기 전에 반드시 검증해야 할 체크리스트를 미리 작성하여 질문에 포함한다.

[완료 조건]
1. 사용자가 Google OAuth 계정으로 로그인할 수 있는가?
2. 로그인 세션이 새로고침이나 브라우저 재시작 후에도 유지되는가?
3. 로그아웃 버튼을 누르면 세션이 삭제되고 메인 페이지로 리다이렉트되는가?
4. 로그인하지 않은 사용자가 API를 직접 호출할 때 401 Unauthorized 에러를 반환하는가?
5. 로그인한 사용자는 오직 자신의 데이터만 조회하고 수정할 수 있는가?
6. 비밀번호나 민감한 토큰이 로컬 스토리지에 평문으로 남지 않는가?

이렇게 명확한 제약과 테스트 시나리오를 주면 AI는 예외 처리 코드와 보안 로직을 생략하지 않고 처음부터 꼼꼼히 뼈대를 채워 넣는다.

원칙 2. AI의 완료 보고를 절대 그냥 믿지 않는다

AI가 "요청하신 기능을 완벽히 구현했습니다"라고 말할 때가 가장 위험하다. 나는 AI의 보고 직후, 그 결과물을 확인하기 위해 언제나 다음 질문을 던져 답변을 요구한다.

• 변경되거나 새로 생성된 파일의 전체 목록
• 각 파일에서 실제로 수정된 핵심 코드 영역과 이유
• 임시 테스트를 위해 남겨둔 Mock Data나 하드코딩된 값의 존재 여부
• 코드 내에 포함된 TODO 주석이나 console.log 위치
• 아직 구현하지 못했거나 환경 제약으로 남겨둔 기술적 한계

이 질문을 던지는 것만으로도 AI는 "사실 이러이러한 부분은 임시 데이터로 처리했습니다"라며 뒤늦게 누락된 부분을 털어놓거나 스스로 미완성된 코드를 보강한다.

원칙 3. 빌드 성공과 기능 성공을 엄격히 구분한다

컴파일러가 에러를 내지 않는다고 해서 비즈니스 로직이 성공한 것은 아니다. 터미널 창의 초록색 성공 메시지를 본 뒤에는 반드시 수동으로 다음 항목들을 하나씩 검증한다.

• 상태 보존: 폼을 작성하고 저장한 뒤 브라우저를 강제로 새로고침했을 때 데이터가 데이터베이스로부터 정확히 다시 로드되는지 확인한다.
• 한계치 입력: 빈 값 제출, 비정상적인 문자 입력, 중복 클릭을 연속으로 발생시켜 시스템이 뻗지 않는지 본다.
• 권한 분리: 비로그인 상태이거나 다른 사용자의 계정 토큰을 모방해 비공개 페이지나 API 엔드포인트에 접근을 시도해 본다.
• 로그 확인: 정상적으로 동작하는 화면 뒤에서 브라우저 콘솔창이나 서버 로그에 숨겨진 404 에러나 unhandled rejection 경고가 없는지 관찰한다.

원칙 4. 작업의 단위를 최소한으로 쪼갠다

한 번에 "대시보드 페이지와 분석 데이터 연동을 한꺼번에 해줘"라고 큰 덩어리로 주문하면 AI는 높은 확률로 내부 구조를 엉망으로 섞거나 일부 로직을 빼먹는다. 귀찮더라도 단계를 철저히 나눈다.

1. 데이터 스키마 설계: 데이터베이스 테이블 구조와 관계 설정 SQL을 작성해 반영한다.
2. API 핸들러 작성: 데이터를 조회하고 저장하는 백엔드 API 엔드포인트를 먼저 만들고 Postman 등으로 단독 테스트한다.
3. UI 바인딩: 화면 구성 요소를 만들고 앞서 생성한 API에 붙인다.
4. 예외 처리 추가: 네트워크 단절, 입력 오류, 에러 응답 상황의 안내 문구를 적용한다.
5. 프로덕션 검증: 로컬 환경을 벗어나 staging 혹은 배포 주소에서 실제 동작 여부를 최종 확인한다.

원칙 5. 코드를 짠 AI와 검토하는 AI를 분리한다

하나의 채팅 세션에서 동일한 AI 모델에게 계속 코드를 짜게 하고 그 안에서 검토까지 시키면, 자신이 만든 코드의 논리 오류를 보지 못하는 인지 편향에 빠진다.

나는 기능을 구현하고 나면, 코드를 완전히 새로운 대화 세션이나 다른 모델(예: Claude로 짰다면 Gemini로 검토)에 넣고 다음과 같이 프롬프트를 준다.

"이 코드는 특정 기능을 위해 작성된 코드입니다. 당신은 매우 깐깐한 시니어 백엔드 엔지니어이자 QA 전문가입니다. 이 코드의 보안 취약점, 엣지 케이스 오류 가능성, 성능 비효율성, 구조적 개선점을 냉정하게 리뷰해 주세요."

이 방식을 쓰면 혼자 일하면서도 아주 훌륭한 코드 리뷰 파트너를 곁에 둔 효과를 얻을 수 있다.

원칙 6. 기능의 세부 구현 상태를 매트릭스로 관리한다

"대시보드 페이지 완성했어요"라는 한 마디에는 너무 많은 오해의 소지가 있다. 기획자, 디자이너, 개발자로서의 자아를 모두 가진 1인 개발자는 더 명확한 기준이 필요하다. 나는 메모장이나 노션에 기능별로 아래 상태를 세분화해 체크한다.

• 미구현 (Unimplemented): 기획만 존재함
• UI 레이아웃 완료 (UI Only): 화면 모양만 잡음
• 임시 데이터 연결 (Mock Data): 로컬 더미 데이터로 동작 시늉만 냄
• 백엔드 API 연결 완료 (API Connected): API 통신은 됨
• DB 영속성 확인 (DB Persisted): 실제 DB에 쓰고 읽기가 보장됨
• 예외/엣지 케이스 테스트 완료 (QA Verified): 실패 상황 테스트 통과
• 운영 환경 검증 완료 (Prod Verified): 실서버 배포 후 검증 끝

이 단계를 밟지 않고 눈에 보이는 화면만으로 기능을 완료 처리하면, 나중에 어느 부분이 가짜이고 진짜인지 스스로도 구별하지 못하는 혼란에 직면하게 된다.

원칙 7. 코드 수정 전에 기존 맥락을 먼저 이해시킨다

기존 프로젝트의 소스코드를 대뜸 넘겨주며 "여기에 이거 추가해줘"라고 하면 AI는 기존 코딩 패턴이나 설계 원칙을 무시하고 ad-hoc(임시변통) 식의 지저분한 코드를 덧붙이기 일쑤다. 수정 요청 전에 기존 구조의 맥락 파악을 먼저 시켜야 한다.

"이 파일의 코드를 수정할 예정입니다. 변경을 요청하기 전에, 먼저 이 파일의 현재 구조와 데이터 흐름, 그리고 구현 방식의 의도를 설명해 주세요. 어떤 함수가 영향을 받을 수 있는지 정리해 주시기 바랍니다."

AI가 기존 코드를 정확하게 해석하고 분석 결과를 내놓은 것을 확인한 뒤에야 비로소 "그렇다면 그 의도와 패턴에 맞게 최소한의 변경으로 기능을 구현해줘"라고 요청한다. 이 단계 하나만으로도 코드의 일관성이 몰라보게 좋아진다.

원칙 8. 빚을 지는 것은 괜찮지만, 숨기지는 않는다

개발을 하다 보면 일정이나 리소스 한계 때문에 어쩔 수 없이 지름길을 택해야 할 때가 있다. 임시 데이터를 하드코딩하거나 보안 검증을 잠시 미뤄두는 식이다. 이때 중요한 것은 그 '부채'를 코드 속에 몰래 묻어두지 않는 것이다.

나는 기술 부채 목록을 프로젝트 루트 폴더에 tech-debt.md 파일로 명시해 두고, 임시 방편을 쓸 때마다 즉시 기록한다.

## 현재 프로젝트의 기술 부채 목록

* [AttractiveWebAI] 분석 차트에 여전히 임시 Mock Data 사용 중 (실제 배포 전 빅쿼리 API 파이프라인 연동 필수)
* [ShopifyShopify디지털 및 실물 매장을 호스팅하고 다국어 번역, 글로벌 결제 및 맞춤형 앱 생태계를 제공하는 세계적인 커머스 플랫폼입니다.Read More → 멤버십] 신규 회원 가입 혜택 결제 처리 시 할인 검증 웹훅 수신부 누락 (운영 배포 전 보안 체크 필수)
* [공통] 사용자 세션 만료 예외 발생 시 로그아웃 처리 미비
* [macOS 유틸리티] 시스템 접근성 권한 획득 확인용 하드코딩된 대기 시간(3초) 존재 -> 이벤트 기반 트리거로 변경 필요

지저분한 코드를 짰다는 사실보다 무서운 것은 내가 어디에 지저분한 코드를 남겨두었는지 잊어버리는 것이다. 빚의 규모를 눈앞에 보이게 관리하면 다음 개발 주기에 무엇을 먼저 개선해야 할지 선명하게 알 수 있다.

---

진짜 완성된 제품을 위하여

AI를 통한 개발은 개발을 '가벼운 행위'로 느끼게 만든다. 프롬프트 창에 질문을 몇 번 던지는 것만으로 수백 줄의 코드가 채워지고 빌드가 완료되는 모습을 보면, 내가 대단히 거대한 제품을 순식간에 통제하고 있다는 착각이 든다.

하지만 진짜 완성도 높은 제품은 작성된 코드의 양이 아니라, 버려진 임시 코드의 양과 확인된 예외 상황의 수로 결정된다. 작동하지 않는 기능을 작동하는 것처럼 둔 껍데기 제품은 첫 사용자가 들어오는 순간 모래성처럼 무너진다.

AI는 훌륭한 러닝메이트이자 타이핑 비서다. 그러나 제품의 완료 선을 긋고 품질을 보장하는 최후의 방어선은 여전히 기획하고 검증하는 인간의 몫이다. 화려한 화면 뒤에 가려진 동작 하나, 데이터 한 줄을 매섭게 뜯어보는 집요함이야말로 AI 시대에 1인 메이커가 갖춰야 할 진짜 개발 역량일지도 모른다.