본문으로 건너뛰기

Frontend AI Ops · EP 01

AI가 쓴 코드를 배포해도 되는가 — 검증 게이트 설계 이야기

AI 생성 코드가 배포 가능함을 증명하는 게이트 설계. 시나리오·증거·결정 3계층과 E2E·시각 회귀·스코어카드·체크리스트 4종 게이트를, 실제로 돌아가는 시스템의 기록과 함께 정리했다.

· 9분 읽기

AI가 쓴 코드를 배포해도 되는가 — 검증 게이트 설계 이야기

올해 2월, 프론트엔드 AI 실무 시리즈를 시작했다. 코드 리뷰, E2E Eval, UI 회귀, 스코어카드, 릴리즈 체크리스트, 브라우저 테스트 게이트. 여섯 편이 전부 다른 이야기 같았지만, 돌아보면 같은 질문을 여섯 번 물은 것이었다.

“AI로 만든 기능이 실제 사용자 시나리오에서 안전하다는 걸 어떻게 증명했나요?”

10월에 2년 회고를 쓰다가 이 시리즈의 문제를 정확히 봤다. 나는 처방을 쓰고 있는데, 처방의 근거가 될 실전 기록이 없었다.

그래서 다시 쓴다. 이 글은 위의 여섯 편을 한 편으로 합친 것이다. 프레임은 남기고, 그 사이에 실제로 돌아가는 시스템의 기록을 이식했다. 게이트 설계라는 처방이 내 저장소와 세션 로그 위에서 어떻게 동작하는지의 기록이다.

1. 생성은 빨라졌는데, ‘배포 가능’의 증명은 여전히 사람 몫이다

작년에 내린 결론 하나가 지금도 블로그 헤더에 붙어 있다.

생성이 저렴해지면, 검증과 운영이 비싸진다. 나는 비싼 쪽에 있어야 한다.

일상에서 이 구조를 가장 실감하는 곳이 이 블로그다. 발행 파이프라인은 아이디어 → 명세 → 초안 → 편집 → 발행으로 나뉘어 있는데, 초안은 에이전트가 쓰고 판단은 내가 한다. 글은 이렇게 나오지만, “이걸 발행해도 되는가”라는 마지막 질문은 여전히 내 차례로 남는다. 코드도 똑같다. 구현 속도가 몇 배가 되어도, 배포 가능 여부를 증명하는 일은 사람에게 남는다.

그 증명을 매번 사람이 처음부터 하면 지친다. 그래서 필요한 게 게이트다. 판단을 사람 머릿속에서 구조로 옮겨놓는 것. 게이트가 있다면 사람은 “전부 다시 검사”가 아니라 “게이트 결과를 읽고 결정”만 하면 된다.

코드 리뷰도 마찬가지로 설계했다. 나는 에이전트를 하나만 쓰지 않는다. 구현은 컨텍스트를 쌓아둔 주력 에이전트에게, 리뷰는 다른 에이전트에게. 코드를 쓴 모델은 자기 코드를 못 본다. 다른 모델의 눈이 필요하다. 둘의 의견이 갈리는 지점이 진짜 설계 결정이 필요한 곳이고, 거기서 사람이 판단한다. 이것도 게이트다 — 리뷰를 통과해야 다음 단계로 가는.

2. 게이트는 3계층이다 — 시나리오, 증거, 결정

게이트를 처음 설계할 때 자주 하는 실수는 “테스트를 추가한다”에서 끝나는 것이다. 돌아가는 게이트는 세 계층으로 이루어진다.

1) 시나리오 계층 — 무엇을 증명할지 고정한다. 파일 단위가 아니라 사용자 여정 단위로 묶는다. 회원가입/로그인, 결제 완료, 대시보드 진입, 설정 저장 후 재진입. 이렇게 묶어야 실패가 났을 때 제품 영향을 바로 설명할 수 있다.

2) 증거 계층 — 실패마다 같은 아티팩트를 강제한다. 스크린샷, 비디오, 네트워크 로그(HAR), 콘솔 에러 요약. 4종을 남기지 않는 실패는 해석할 수 없는 실패다.

3) 결정 계층 — 결과를 등급으로 바꾼다. P0~P3로 분류하고, 등급마다 차단/조건부/기록 후 진행을 미리 정해둔다. 결정 규칙이 없으면 게이트 결과는 또 사람의 재량이 된다.

이 구조가 실제로 돌아가는 예를 하나 들자. 내가 만든 damon-agent-core는 에이전트 CLI 9개를 통합 제어하는 데몬인데, 120커밋쯤 쌓인 지금 크로스플랫폼 CI 위에서 돈다. 커밋이 열릴 때마다 정해진 검증 체인이 돌고, 통과하지 못하면 다음 단계로 못 간다. 요즘 하는 프로젝트(Spec Studio v2)의 E1 단계 작업 로그 기준으로는 유닛 테스트 218/218, 골든 테스트 30개, E2E 131개, two-device 검증 23/23이 게이트를 통과했다. 숫자 자체보다 중요한 건, 이 숫자들이 “에이전트가 구현하고 사람이 승인한다”는 흐름 위에서 게이트가 실제로 차단 장치로 동작했다는 사실이다.

3. 게이트는 한 종류가 아니다 — 4가지 게이트와 선택 기준

증명하려는 주장이 다르면 게이트도 달라야 한다. 내가 써온 4종을 정리하면 이렇다.

게이트증명하는 것언제 쓰나
E2E Eval핵심 흐름이 작동한다배포 직전, 매 PR
시각 회귀화면이 의도치 않게 변하지 않았다UI 변경이 있는 PR
스코어카드기준 점수를 넘는다기능 단위 완성 판정
릴리즈 체크리스트운영 가능하다배포 최종 승인 직전

E2E Eval — “모든 화면”이 아니라 “돈 되는 흐름”부터

처음부터 전체를 덮으려 하면 실패한다. 핵심 사용자 여정 3개만 고정한다. 로그인 → 대시보드 진입, 검색 → 상세 이동, 결제 → 완료 확인. 이 3개만 안정화돼도 릴리즈 리스크의 대부분이 관리된다.

검증 대상도 중요하다. “정답 HTML”이 아니라 “관찰 가능한 상태”를 검증한다. 마크업 구조에 의존하면 테스트가 쉽게 깨진다. 버튼 클릭 후 URL이 기대 경로로 바뀌는가, 에러 토스트가 실제로 노출되는가, 제출 후 응답 상태에 맞는 UI가 보이는가 — 사용자가 관찰할 수 있는 것만 단언한다.

간헐 실패(flaky)는 재시도로 덮지 않는다. 네트워크 지연인지, 애니메이션 타이밍인지, 비동기 상태 전이인지 원인을 분리한다. retry는 지표를 예쁘게 만들 뿐 품질은 나아지지 않는다.

시각 회귀 — 결정적 diff와 AI 비교의 이중 장치

한 가지 방법만 쓰면 놓치는 게 생긴다. 3단으로 쌓는다.

  1. 1차, 결정적 비교: Playwright 스크린샷 diff. 빠르고 재현성이 높다. 대신 의도된 변경도 전부 경고로 뜬다.
  2. 2차, AI 의미 비교: 결정적 diff가 잡은 것 중 “의미 있는 변화”(버튼 비활성화, 텍스트 유실, 대비 저하)만 분류한다.
  3. 3차, 사람 승인: 변경 의도(디자인 개편)인지 결함인지는 사람이 판정한다.
// tests/visual/home.spec.ts
import { test, expect } from '@playwright/test'

test('홈 화면 회귀 테스트', async ({ page }) => {
  await page.goto('/')
  await page.setViewportSize({ width: 1440, height: 900 })
  await page.waitForLoadState('networkidle')

  await expect(page).toHaveScreenshot('home-desktop.png', {
    fullPage: true,
    maxDiffPixelRatio: 0.01,
  })
})

핵심은 스크린샷 자체가 아니라 실패를 팀이 해석 가능한 정보로 바꾸는 것이다. 변경 영역, 영향 컴포넌트 후보, 접근성 영향, 릴리즈 위험도를 CI 코멘트로 남긴다. “몇 픽셀 달라졌다”가 아니라 “사용자에게 무슨 일인지”로 번역해야 리뷰가 된다.

스코어카드 — 감상 대신 결정 로그

E2E와 시각 회귀가 “작동/무결”을 증명한다면, 스코어카드는 “이 기능이 배포 수준인가”를 점수로 만든다. 4개 축만 고정하면 충분하다.

  • 기능 정확성: 요구사항 충족, 예외·빈 상태 처리, API 실패 시 피드백
  • UX/접근성: 키보드 완주 가능, 폼 에러 메시지, 상태 일관성
  • 성능 안정성: LCP/INP/CLS 추이, 불필요한 렌더링, 번들 크기
  • 운영 안정성: 에러 추적 연결, 롤백 가능한 단위, 관측 로그

각 축 0~2점, 총 8점. 점수의 가치는 숫자가 아니라 “잘 만들었다”는 감상을 근거 있는 결정 로그로 바꾼다는 데 있다. 어느 축이 1점인지 보이면 무엇을 먼저 고칠지가 선명해진다. 성능 축의 기준은 성능 예산 릴리즈 게이트에서 다룬 예산치를 그대로 쓰고, 접근성 축은 프론트엔드 접근성 회귀 체크리스트가 기준이 된다.

## AI 산출물 검증 스코어카드 (8점 만점)

- 기능 정확성: 0|1|2
- UX/접근성: 0|1|2
- 성능 안정성: 0|1|2
- 운영 안정성: 0|1|2

총점: X/8

### 근거
- 테스트 결과:
- 측정 지표(LCP/INP/CLS):
- 에러 로그 링크:
- 남은 리스크:

릴리즈 준비도 체크리스트 — 마지막 관문

배포 직전에는 점수가 아니라 확인 목록이 맞는다. 5단계.

  1. 요구사항 정합성 — 빈 상태/에러 상태/로딩 상태가 분리돼 있는가, API 실패 시 회복 경로가 있는가
  2. 접근성/UX 최소 기준 — 키보드만으로 핵심 플로우 완주, 스크린리더 라벨, 피드백 지연 없음
  3. 성능 가드레일 — 불필요한 클라이언트 렌더링 증가 없음, Web Vitals 허용 범위 내, 번들 증가 합리적
  4. 관측 가능성 — 에러 로깅 연결(Sentry 등), 추적 키 존재, 롤백 가능 단위
  5. 협업 재현성 — “왜 이렇게 구현했는지”가 PR 본문에 있는가, 다음 작업자가 같은 방식으로 이어받을 수 있는가

AI 생성 코드에서 가장 자주 빠지는 게 2번(접근성)과 5번(결정 근거)이다. 그래서 이 두 항목은 체크리스트에서 지우지 않는다.

4. 실행보다 어려운 건 실패 해석이다

게이트 운영에서 처음 부딪히는 법은 테스트 추가가 아니다. 실패의 해석이다.

테스트를 돌리는 것보다, 실패를 빠르게 해석하는 체계가 더 중요하다.

그래서 증거 계층이 필요하다. 실패마다 아티팩트 4종(스크린샷·비디오·HAR·콘솔 요약)을 강제하는 이유는, 해석의 재료를 보존하기 위해서다. 그리고 해석의 산출물은 분류여야 한다 — 재현 가능한 실패인지, 환경성 플래키인지. 이 분류가 다음 액션을 결정한다.

내 세션 로그에 이런 기록이 두 개 있다. confluence-studio 작업 중의 것이다.

$ damon search "storage format 변환기 라운드트립"

[0.42s] 214 sessions scanned
#0821  confluence-studio   "XHTML→Markdown 라운드트립 실패 케이스 정리"
#0793  confluence-studio   "quick-xml 파서로 매크로 문법 보존하기"

Confluence 문서를 Markdown으로 내보내는 이 파이프라인에서, XHTML→Markdown 라운드트립 실패(#0821)와 매크로 문법 유실(#0793)은 한 번에 해결된 문제가 아니었다. 실패 케이스가 쌓일 때마다 정리해 둔 기록이 지금은 0.42초 만에 회수된다. 실패 해석을 매번 새로 하는 팀과, 축적해두는 팀의 차이는 여기서 벌어진다. 게이트가 실패를 차단하는 장치라면, 세션 로그는 실패를 기억하는 장치다. 둘은 세트다.

5. 차단 규칙 — 전부 차단하면 게이트는 금방 무너진다

게이트의 마지막 설계 질문은 “무엇을 막을 것인가”다. 실패가 나면 무조건 배포를 막으면 팀이 지쳐서 게이트를 우회하기 시작한다. 반대로 전부 허용하면 게이트가 아니다. 내 기준은 이렇다.

  • 차단(P0/P1): 결제, 인증, 데이터 손실 가능성
  • 조건부 차단(P2): 핵심 UX 저하, 우회 경로 존재
  • 기록 후 진행(P3): 낮은 우선순위 UI 이슈

그리고 원칙이 하나 있다. AI가 차단하지 않는다. AI는 분류하고, 사람이 최종 승인한다.

이 원칙을 나는 테스트 게이트보다 먼저 다른 곳에 시스템으로 만들었다. damon에서 파일 쓰기, 커밋, 네트워크 같은 파괴적 행위는 에이전트가 임의로 하지 못하고, 승인 요청이 쓰고 있는 채널(웹 UI, CLI, 텔레그램 버튼)로 릴레이된다. “이 커밋 날려도 될까요?”가 오면 확인하고 버튼 하나로 승인한다. 릴리즈 게이트의 머지 승인과 완전히 같은 구조다 — 자동화는 분류와 요청까지, 결정은 사람이.

게이트 결과는 이런 형식으로 PR에 남긴다.

## Release Gate Report

### 1) 배포 후보 범위
- 기능/화면:
- 비범위:

### 2) 사용자 여정 테스트 결과
- 인증 플로우:
- 결제 플로우:
- 핵심 조회 플로우:

### 3) 실패 아티팩트
- Screenshot:
- Video:
- Network(HAR):
- Console summary:

### 4) 분류 결과
- P0 / P1:
- P2:
- P3:

### 5) 최종 결정
- 배포 여부:
- 차단/완화 근거:
- 후속 이슈 링크:

6. 게이트를 통과한 다음 — 결과는 기록이 되어야 한다

게이트가 남기는 건 통과/차단의 순간이 아니라 기록이다. 그 기록이 쌓여야 게이트가 처음 생겼을 때의 질문 — “AI 코드라고 다르게 실패하는가” — 에 데이터로 답할 수 있다. 변경 실패율(CFR)을 ai-assisted 태그로 분리 추적하는 이야기와, 게이트 통과 근거를 로그북으로 쌓는 이야기는 이어지는 글에서 다룬다.

기록이 자산이라는 건 블로그 운영에서도 확인했다. 글 70편에서 가장 성과가 좋은 건 개별 글이 아니라 링크 구조였다. 관련 글을 연결해두니 유입 하나가 평균 2~3 페이지를 읽고 간다. 게이트 기록도 같다 — 개별 게이트 리포트가 아니라, 그것이 다음 결정의 재료가 될 때 값이 생긴다.

시작 체크리스트

게이트를 도입한다면, 이 순서로 시작한다.

  1. 핵심 사용자 여정 3개를 고정한다
  2. PR마다 lint·build·E2E 스모크를 강제한다
  3. 실패마다 아티팩트 4종을 남긴다
  4. P0~P3 차단 등급을 팀과 합의해둔다
  5. 게이트 결과를 PR 본문 템플릿에 기록한다

“테스트를 하나 더 추가한다”가 아니라, 이 다섯 개가 하나의 구조로 묶여야 게이트다.

남는 것

2년 전에 쓴 문장이 있다. 검증은 생성보다 비싸다. 지금도 유효하고, 앞으로도 그럴 것 같다. 생성 속도가 올라갈수록 증명의 값은 올라간다.

이 글의 프레임 — 3계층, 4종 게이트, 차단 규칙 — 은 사실 누구나 쓸 수 있는 처방이다. 근거가 될 기록만 나의 것이다. 세션 #0821의 실패 정리, 0.42초의 회수, 승인 버튼으로 릴레이되는 커밋. 처방과 병력을 함께 두는 것, 그게 이 시리즈를 다시 쓰는 이유다.

Related

· 3 min read

접근성 회귀를 막는 프론트엔드 PR 체크리스트

AI로 UI 구현 속도가 빨라질수록 놓치기 쉬운 접근성 회귀를 PR 단계에서 잡는 방법을 정리했습니다. 키보드, 포커스, 이름, 상태, 에러 메시지를 실무 체크리스트로 연결합니다.

프론트엔드접근성
→