테크 랩

에이전틱 개발 파이프라인 – 05. AI가 짠 코드, 어떻게 믿나: 검증 게이트 설계

2026.08.21

3줄 요약

AI는 빠르게 코드를 만들지만, 그럴듯한 오류를 조용히 심는다 — 검증 게이트 없이 신뢰하면 안 된다.
자체 셀프체크 → 자동화 CI → AI 코드리뷰 → 사람 최종 판정의 4단계 다층 게이트가 실전 해법이다.
보안·데이터·비용·외부계약·비가역 작업은 반드시 사람이 직접 판단해야 한다.

AI 코드 검증을 설계하지 않으면 생기는 일

에이전틱 코딩을 처음 써본 개발자 대부분이 같은 실수를 한다. AI가 코드를 완성하면 그냥 머지한다. 테스트가 녹색이니까, 빌드가 통과하니까. 그런데 며칠 뒤 프로덕션에서 예상치 못한 경로로 데이터가 노출되거나, 외부 API 호출이 예산을 초과하거나, 스키마 마이그레이션이 롤백 불가 상태로 실행됐다는 걸 알게 된다.

AI는 완전 위임 대상이 아니다. 사람이 검증 게이트를 설계하고, AI는 그 게이트를 통과해야 배포된다. 이 편에서는 주니크(GUNIQ)가 실제로 운영하는 다층 검증 구조를 구체적으로 설명한다.

왜 AI 코드 검증이 핵심인가: AI가 자주 저지르는 실수 유형

AI 코드 품질 문제는 크게 두 가지 패턴으로 나뉜다.

① 컨텍스트 밖 실수: AI는 현재 파일과 제공된 프롬프트만 본다. 레포 전체의 설계 원칙, 팀 내부 규약, 인프라 제약을 모른다. 인증 미들웨어를 우회하거나, 이미 deprecated된 내부 API를 그대로 호출하거나, 다른 서비스와 충돌하는 포트를 열기도 한다.

② 그럴듯한 오류(Plausible Bugs): 문법적으로 완벽하고 테스트도 통과하지만, 엣지 케이스에서 틀린 결과를 낸다. SQL 인젝션 방어가 빠진 쿼리, 정수 오버플로우를 고려하지 않은 계산, 암묵적 타입 캐스팅 버그가 대표적이다. 단순 린트로는 잡히지 않는다.

속도는 빠르지만 틀릴 수 있다. 검증 게이트는 이 두 가지를 잡기 위해 설계한다.

AI 코드 리뷰 자동화: 4단계 다층 검증 게이트

게이트는 순서가 중요하다. 앞 단계를 통과하지 못하면 다음 단계로 넘어가지 않는다.

단계	주체	검증 내용	통과 기준
① 셀프체크	AI (Claude Code)	테스트 작성·실행, 타입 오류 자가 수정	작성된 테스트 전체 통과
② 자동화 CI	파이프라인	정적분석·린트·타입체크·단위/통합 테스트	파이프라인 그린
③ AI 코드리뷰	AI (다른 컨텍스트)	보안 패턴·성능·설계 일관성 관점 리뷰	크리티컬 이슈 없음
④ 사람 최종 판정	개발자/리드	아키텍처 적합성·정책·비가역 영향	승인 머지

① AI 셀프체크: 테스트를 AI가 쓰게 하라

구현을 요청할 때 테스트 작성을 함께 지시한다. CLAUDE.md에 규칙으로 박아두면 매번 말하지 않아도 된다.

# CLAUDE.md 에 추가 (예시)
## 코드 작성 규칙
- 새 함수·엔드포인트 구현 시 반드시 단위 테스트를 함께 작성한다.
- 구현 완료 후 `pytest` (또는 프로젝트 테스트 러너)를 실행하고
  결과를 확인한 뒤 보고한다.
- 테스트가 실패하면 수정 후 재실행 — 통과 확인 전까지 완료 보고 금지.

이렇게 해두면 Claude Code가 구현 → 테스트 작성 → 실행 → 실패 시 자가 수정까지 루프를 돈다. 단, AI가 쓴 테스트도 AI가 통과시키기 쉽게 짜는 경향이 있다. 엣지 케이스·경계값 테스트는 사람이 추가하거나 별도로 지시해야 한다.

② 자동화 CI: 파이프라인이 게이트키퍼다

AI가 코드를 푸시하더라도 파이프라인이 통과하지 않으면 머지 불가 상태를 만드는 것이 원칙이다. 최소한의 CI 구성 예시(Gitea Actions 기준, GitHub Actions 문법과 동일):

# .gitea/workflows/ci.yml (예시)
name: CI

on: [push, pull_request]

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install deps
        run: pip install -r requirements.txt
      - name: Lint (ruff)
        run: ruff check .
      - name: Type check (mypy)
        run: mypy .
      - name: Test (pytest)
        run: pytest --tb=short

린트·타입·테스트 중 하나라도 실패하면 머지 버튼이 비활성화된다. AI가 생성한 코드도 예외 없이 이 파이프라인을 통과해야 한다.

③ AI 코드리뷰: 다른 관점의 AI에게 리뷰 맡기기

구현한 AI와 다른 컨텍스트(신선한 세션)의 AI에게 PR을 검토하게 한다. 같은 컨텍스트의 AI는 자신이 만든 코드의 맹점을 그대로 가지고 있어 효과가 떨어진다.

Claude Code 기준으로는 /code-review 명령이 diff를 기반으로 독립 관점에서 코드를 검토한다. 보안 패턴(SQL 인젝션·인증 우회·하드코딩 시크릿), 성능 병목, 기존 코드베이스와의 일관성 불일치를 잡는 데 효과적이다.

AI 코드리뷰 결과는 의견이지 결론이 아니다. 크리티컬 이슈가 없으면 다음 단계로 넘어간다.

④ 사람 최종 판정: AI가 대신할 수 없는 영역

모든 자동화 게이트를 통과해도 사람이 최종 승인해야 하는 항목이 있다. 빠르게 훑으려면 다음 체크리스트를 쓴다.

보안·인증: 새 엔드포인트에 인증 미들웨어가 걸려 있는가? 외부 입력이 그대로 SQL·쉘·파일 경로에 들어가지 않는가?
데이터 처리: 개인정보·민감 데이터가 로그에 찍히거나 외부로 전송되는가?
비용·외부 계약: 외부 API 호출 횟수가 급증하지 않는가? 요금제 한도를 초과하는 루프가 없는가?
비가역 작업: DB 스키마 변경·데이터 삭제·외부 서비스 구독 취소 등 되돌리기 어려운 작업인가?
아키텍처 적합성: 기존 서비스 경계를 침범하거나 MSA 원칙을 위반하지 않는가?

서비스 검증: 기능·통합 테스트까지 통과해야 배포다

단위 테스트가 통과해도 서비스 간 연동에서 깨지는 경우가 많다. MSA 구조에서는 특히 그렇다. 배포 전 최소한 다음 두 가지를 확인한다.

기능 테스트(Functional Test): 해당 서비스의 API 엔드포인트가 기대한 응답을 반환하는가? 경계값·오류 케이스까지 포함. 스테이징 환경에서 실서비스와 동일한 데이터 흐름으로 실행한다.

통합 테스트(Integration Test): 이 변경이 다른 서비스의 동작을 깨뜨리지 않는가? 의존하는 서비스와의 계약(API 스펙, 이벤트 스키마)이 유지되는가? 컨트랙트 테스트(Pact 등)를 사용하면 서비스마다 전체 실행 없이 계약만 검증할 수 있다.

이 두 단계를 통과한 코드만 Gitea에서 프로덕션 배포 파이프라인으로 넘어간다.

에이전틱 코딩 품질 관리: 흔한 함정 3가지

함정 1: 그린 테스트를 맹신한다

AI가 작성한 테스트는 구현을 그대로 반영하는 경향이 있다. 잘못된 로직도 테스트가 그 로직을 기준으로 작성되면 그린이 된다. 특히 AI가 만든 목(Mock) 객체는 실제 외부 시스템의 오류 케이스를 다루지 않는 경우가 많다. 커버리지 숫자보다 테스트 케이스의 의미를 확인해야 한다.

함정 2: AI 리뷰 없이 바로 머지한다

“CI가 통과했으니 됐다”는 생각으로 리뷰 없이 머지하는 습관이 생기면 코드베이스가 빠르게 오염된다. AI 코드리뷰는 5~10분이면 충분하다. 크리티컬 이슈 하나를 잡는 것만으로 충분히 가치가 있다.

함정 3: CLAUDE.md를 최초 1회만 쓴다

프로젝트가 커지면 새로운 규칙이 생긴다. CLAUDE.md를 살아있는 문서로 유지해야 AI가 과거 실수를 반복하지 않는다. “이 실수가 두 번 나왔다”는 시점에 CLAUDE.md에 규칙으로 추가하는 것이 원칙이다.

GUNIQ 실제 사례: 검증 통과분만 Gitea → 배포

주니크는 Claude Code로 개발하고, 셀프호스팅 Gitea에서 코드를 관리한다. 배포 흐름은 단순하다.

Claude Code가 코드를 작성하고 셀프체크(테스트 실행)까지 완료한다.
Gitea Actions CI가 린트·타입·테스트를 자동 실행한다. 파이프라인이 실패하면 PR 머지 불가.
/code-review로 AI 코드리뷰를 돌려 크리티컬 이슈가 없는지 확인한다.
사람이 PR을 최종 검토하고 승인한다 — 특히 데이터 처리·외부 API·비가역 변경을 직접 확인한다.
통과한 PR만 머지 → Proxmox VM으로 분산 배포된다.

이 흐름에서 AI는 구현 속도를 책임지고, 사람은 게이트를 설계·운영한다. 어느 한쪽이 빠지면 파이프라인 전체가 위험해진다.

🎓 바로 쓰기: 최소 검증 게이트 체크리스트

CLAUDE.md에 “테스트 작성 후 실행, 통과 확인 전까지 완료 보고 금지” 규칙 추가
CI 파이프라인에 린트·타입·테스트 스텝 구성, PR 머지 조건으로 설정
AI 코드리뷰(/code-review 또는 별도 리뷰 세션)를 PR 루틴에 포함
보안·데이터·비용·비가역 작업은 사람 체크리스트로 수동 확인
스테이징에서 기능·통합 테스트 통과 후 프로덕션 배포

FAQ

AI가 테스트까지 쓰면 테스트 신뢰도가 떨어지지 않나?

떨어질 수 있다. AI는 자신이 구현한 방식을 기준으로 테스트를 쓰기 때문에 “구현이 틀렸는데 테스트도 같이 틀린” 경우가 생긴다. 이를 보완하려면 엣지 케이스를 별도로 지시하거나, 사람이 케이스를 추가하거나, TDD 방식으로 테스트를 먼저 작성하고 AI에게 통과시키게 하는 방법을 쓴다.

AI 코드리뷰가 사람 코드리뷰를 대체할 수 있나?

대체가 아니라 보조다. AI 코드리뷰는 패턴 기반 이슈(보안 취약점 패턴, 코드 스타일 불일치, 중복)를 빠르게 잡는다. 그러나 비즈니스 맥락, 팀 합의된 설계 원칙, 조직 정책은 사람만 판단할 수 있다. 소규모 팀이라면 AI 리뷰로 1차를 걸러내고 사람이 빠르게 최종 확인하는 구조가 현실적이다.

CI/CD 없이 로컬에서만 개발하는 1인 팀은 어떻게 해야 하나?

파이프라인이 없어도 최소한 세 가지는 수동으로 할 수 있다. ① AI에게 구현 후 테스트 실행을 지시하고 결과를 보고받는다. ② 배포 전 /code-review 또는 새 세션에서 diff를 붙여 리뷰를 요청한다. ③ 보안·데이터·비가역 작업 체크리스트를 텍스트 파일로 만들어 머지 전 수동 확인한다. 파이프라인은 이 과정을 자동화할 뿐, 원칙 자체는 동일하다.

AI가 보안 취약점을 스스로 발견하고 고칠 수 있나?

알려진 패턴은 잡는다. SQL 인젝션, 하드코딩된 시크릿, 인증 없는 엔드포인트 같은 교과서적 취약점은 AI 코드리뷰에서 잘 걸러진다. 그러나 비즈니스 로직에 숨은 권한 상승 버그, 서비스 간 신뢰 관계 오용처럼 컨텍스트가 필요한 취약점은 사람이 직접 봐야 한다. SAST 도구(Semgrep, Bandit 등)를 CI에 추가하면 보완이 된다.

AI 개발 파이프라인에서 속도는 AI가 책임진다. 품질은 게이트가 책임진다. 게이트를 설계하는 것은 사람의 몫이다. 검증 구조를 갖추고 나면 AI에게 더 많은 작업을 위임할 수 있다 — 오히려 게이트가 있어야 위임이 안전해진다.

주니크에 AI 개발 파이프라인 도입을 검토하고 있다면 문의로 연락하면 된다. 팀 규모와 현재 개발 흐름에 맞는 방법을 같이 찾는다.

『에이전틱 개발 파이프라인』 시리즈
← 이전: 04. Claude Code로 MSA 설계·구현
→ 다음: 06. GitHub 대신 Gitea: 셀프호스팅 CI/CD

다른 글 보기