Hook

AI 에이전트에게 “이 페이지 만들어줘”라고 말하면 몇 초 만에 멋진 UI가 나옵니다. 하지만 막상 배포해보면 버튼이 안 눌립니다. 에러 상태가 없습니다. 데이터가 하드코딩되어 있습니다. 파일 하나가 7,600줄입니다.

세 개의 프로젝트 — SaaS 모노레포, AI 뉴스 서비스, 피트니스 PWA — 에서 AI를 주도로 개발하며 똑같은 패턴의 문제가 반복되었습니다. 이 글에서는 그 근본 원인을 진단하고, 10가지 원칙으로 통제한 방법을 공유합니다.

TL;DR

• 근본 원인은 “순서 역전” — 프리뷰(결과)를 먼저 만들고 데이터 구조(원인)를 나중에 맞추는 개발 방식이 모든 부채의 출발점입니다
• 10가지 원칙이 세 프로젝트에 공통으로 자리잡았습니다 — 코드가 진실, AI 컨텍스트 절약, 데드 버튼 금지, 점진적 마이그레이션 등
• 해법은 “게이트(Gate)와 자동화” — 사람이 규칙을 외우는 대신, CI와 pre-commit이 기계적으로 검증합니다
• 이 시리즈 7편에 걸쳐 각 원칙을 상세히 다룹니다

Background: 세 프로젝트에서 겪은 공통 문제

프로젝트 개요

세 프로젝트는 도메인과 규모가 다르지만, AI 에이전트로 개발하며 겪은 문제의 패턴은 동일했습니다.

반복된 6가지 문제 패턴

┌─────────────────────────────────────────────────────────┐
│           AI 주도 개발에서 반복되는 문제 패턴            │
├──────────────────┬──────────────────────────────────────┤
│ ① 순서 역전      │ 프리뷰 → 코드 → 데이터 (역순)       │
│ ② 데드 버튼      │ onclick={}, href="#", TODO 버튼     │
│ ③ 상태 누락      │ loading/error/empty/unauthorized 없음│
│ ④ 모놀리식 폭발  │ 단일 파일이 수천 줄로 성장           │
│ ⑤ 목 데이터 잔류 │ mock/dummy/fake 변수가 프로덕션에    │
│ ⑥ 시크릿 노출    │ API 키가 소스 코드에 하드코딩       │
└──────────────────┴──────────────────────────────────────┘

근본 원인 진단: “순서 역전”

✗ AI 도구의 기본 흐름 (문제):
  프리뷰(디자인) → 코드 작성 → 데이터 구조 설계

✓ 올바른 흐름:
  도메인 모델 → 데이터 스키마 → API 컨트랙트 → UI 구현 → 디자인

AI 디자인 도구는 성공 상태, 레이아웃, 색상만 보여줍니다. 데이터 구조, API 시그니처, 에러/로딩/empty 상태, 권한 모델은 보여주지 않습니다. 프리뷰를 먼저 만들면 이것들을 나중에 “맞추게” 되고, 그 과정에서 부채가 누적됩니다.

Solution: AI 주도 개발 10원칙

원칙 1: 코드가 진실이다

문서와 코드가 충돌하면 코드를 기준으로 하고 문서를 수정합니다.

AI 에이전트가 구식 문서를 근거로 잘못 구현하는 일이 빈번했습니다. “백엔드 없음”이라는 오래된 문서를 읽고 이미 존재하는 API를 무시하는 식입니다. 해법은 단순합니다 — 충돌 시 코드가 이기고, 문서가 코드를 따라갑니다.

원칙 2: AI 컨텍스트를 절약하라

거대 단일 파일을 기능별로 분할해 AI가 관련 파일만 읽도록 합니다.

피트니스 PWA에서 단일 HTML 파일이 346KB / 7,600줄까지 성장했습니다. AI 에이전트가 매 편집마다 이 파일 전체를 읽어야 해서 컨텍스트가 낭비되고, 응답 품질이 떨어집니다. 기능별로 파일을 나누니 AI가 필요한 파일만 읽게 되어 정확도와 속도가 모두 향상되었습니다.

원칙 3: 프리뷰가 데이터를 결정하지 않는다

도메인 → 스키마 → 컨트랙트 → UI → 디자인 순서를 강제합니다.

이 원칙은 다음 글(2)에서 4단계 게이트와 함께 상세히 다룹니다.

원칙 4: 데드 버튼을 배포하지 않는다

반응 없는 버튼/링크/폼는 프로덕션 금지. 미구현은 disabled + 사유 명시.

AI가 만든 UI에서 가장 흔한 문제가 “눌러도 아무 일이 일어나지 않는 버튼”입니다. 빈 onclick={}, href="#", TODO가 남은 인터랙티브 요소를 CI가 정적 탐지하여 자동으로 차단합니다.

원칙 5: 점진적 마이그레이션

“한 번에 전환 금지”. Phase별로 나누고 매 단계 회귀 검증.

빅뱅 리팩터는 부채를 숨길 뿐입니다. 피트니스 PWA의 파일 분할은 4-Phase로 진행했습니다: 데이터 분할 → CSS 분리 → core 로직 → screens. 매 Phase마다 검증 스크립트로 회귀를 확인했습니다.

원칙 6: gettext 원문 키 방식

키를 발명하지 않습니다 — 텍스트 자체가 키입니다.

` t(‘ui.a_065’) 같은 구조적 키의 가독성은 최악입니다. 대신 t(‘운동이 저장되었습니다’)`처럼 원문 자체를 키로 사용하면 키 발명 단계가 사라집니다. 이 방식은 글(4)에서 상세히 다룹니다.

원칙 7: 컴포넌트 격리 우선, E2E 최후

바텀업 테스트. 느리고 불안정한 E2E는 스모크 3~10개만.

전통적 E2E 우선 접근은 CI를 차단합니다. Unit → Component → Contract → E2E Smoke 순으로, 가장 빠르고 안정적인 테스트를 최우선으로. 이 전략은 글(5)에서 다룹니다.

원칙 8: 규칙은 기계가 지킨다

사람은 판단에만 쓰고, 규칙 검증은 기계에 위임합니다.

pre-commit → CI 게이트 → workflow 검증 기준으로 3중 강제 구조를 만들었습니다. “데드 버튼을 만들지 마세요”라는 팀원 간 약속보다, CI가 onclick="" 패턴을 감지해서 PR을 차단하는 것이 확실합니다. 글(6)에서 상세히 다룹니다.

원칙 9: 시크릿은 절대 소스에

하드코딩, 커밋, 채팅 평문 공유 — 세 가지 모두 절대 금지.

AI 에이전트는 API 키를 편의상 소스 코드에 박아놓는 경향이 있습니다. wrangler secret put으로만 관리하고, baseline 기반 시크릿 스캔을 pre-commit에 통합했습니다.

원칙 10: 플랫폼 추상화로 이식성

Cloudflare 서비스를 직접 임포트하지 않고, 추상화 인터페이스로 접근합니다.

벤더 종속을 최소화하고, 다른 플랫폼으로의 마이그레이션 가능성을 열어둡니다.

Result: 원칙 적용 전후

세 프로젝트의 거버넌스 성숙도

프로젝트        원칙 정교함    자동화 수준    ADR 수
─────────────────────────────────────────────────
SaaS 모노레포   ★★★          ★★★          5건
AI 뉴스 서비스  ★★★★        ★★★★        1건 (프로세스 중심)
피트니스 PWA    ★★★★★      ★★★★★      8건 (가장 정교)

프로젝트가 성숙할수록 자동화 검증(tools/check.js)과 AI 컨텍스트 절약 분할이 더 정교해집니다.

Takeaway

1. AI 주도 개발의 부채는 패턴이 있습니다 — 프리뷰 역설, 데드 버튼, 모놀리식 폭발, 목 데이터 잔류, 시크릿 노출은 우연이 아니라 AI 도구의 작동 방식에서 비롯된 구조적 문제입니다. 이 패턴을 인식하는 것만으로도 대응의 절반은 끝납니다. 세 프로젝트에서 동일한 패턴이 반복되었다는 것 자체가 이 문제들의 보편성을 증명합니다

2. 해법은 “더 좋은 약속”이 아니라 “기계적 게이트”입니다 — 팀원에게 “데드 버튼 만들지 마세요”라고 당부하는 것보다, CI가 onclick="" 패턴을 정적 탐지해서 PR을 자동 차단하는 것이 확실합니다. 사람은 판단(아키텍처, 도메인 설계)에만 집중하고, 규칙 준수 검증은 기계에 위임해야 합니다

3. 거버넌스는 살아있는 문서입니다 — 처음부터 완벽한 거버넌스를 만들 수 없습니다. 문제를 겪을 때마다 원칙을 하나씩 추가하고, 그 원칙을 자동화로 뒷받침하는 과정이 중요합니다. 피트니스 PWA는 8개 ADR과 765행 거버넌스 문서에 이르기까지 수주에 걸쳐 진화했습니다. 이 시리즈의 나머지 글들이 그 진화 과정의 핵심을 다룹니다