AI 코딩 에이전트 리뷰 가드레일 — diff 400줄 상한부터 10분 롤백까지

금요일 밤, AI 코딩 에이전트에게 결제 모듈 정리를 맡기고 잤습니다. 아침에 브랜치를 열어보니 커밋 하나에 1,240줄이 바뀌어 있더군요. 로직은 그럴듯했는데 리뷰를 어디서부터 시작할지 감이 안 잡혔어요. 결국 전부 되돌렸고 그날 오후를 통째로 날렸습니다.

이 글을 끝까지 읽으면 AI 코딩 에이전트에게 레거시 코드를 맡기기 전 걸어둘 가드레일 세 가지를 직접 세팅할 수 있습니다. diff 라인 상한, 회귀테스트 병합 게이트, 카나리와 롤백 절차예요. 리뷰어가 나 혼자인 1인 팀 기준으로 잡았습니다.

리뷰 없는 대규모 리팩터링은 왜 위험한가요?

2026년 7월 27일 Hacker News에 75만 줄 규모 앱을 코딩 에이전트가 코드리뷰 없이 리팩터링한 사례 연구가 올라왔습니다. 제목부터 "no code review"를 내걸었죠. 출처: Show HN: Case study: A coding agent refactors a 750k LOC app, no code review

이틀 앞선 7월 25일에는 100만 줄짜리 레거시 SaaS에 AI 변경을 어떻게 굳혀서 리뷰 단계로 넘길지 묻는 질문 글이 댓글 16개를 모았어요. 같은 주에 두 사례가 나란히 올라왔다는 사실이 흐름을 보여줍니다. 출처: Ask HN: How would you harden AI changes to a 1M-line legacy SaaS before review?

문제의 핵심은 에이전트 실력이 아닙니다. 1인 팀에는 diff를 대신 읽어줄 사람이 없다는 점이죠. 그래서 사람 리뷰가 하던 일을 기계가 판정하는 자동 게이트로 옮겨야 합니다.

준비물: 30분이면 끝나는 사전 세팅

필요한 건 git 2.40 이상, 테스트 러너 하나, 커버리지 리포터 하나입니다. 저는 pytest와 pytest-cov를 씁니다. CI는 GitHub Actions를 쓰지만 로컬 pre-push 훅만으로도 리뷰 게이트를 흉내 낼 수 있어요.

다음으로 에이전트 지시문 파일에 금지 경로를 적습니다. 저장소 루트의 AGENTS.md나 CLAUDE.md에 migrations/, .github/workflows/, config/secrets/, 결제·인증 모듈 경로를 나열해 두세요. AI 코딩 에이전트가 이 경로를 건드리면 리뷰 없이는 되돌리기 어렵습니다.

마지막으로 골든 스냅샷을 만듭니다. 리팩터링 착수 전에 핵심 API 20개의 응답 JSON을 tests/golden/에 저장해 두면, 회귀테스트가 없는 레거시에서도 diff 검증 기준선이 생깁니다.

1단계: diff 400줄 상한과 커밋 분할 규칙

한 커밋에 추가·삭제 합계 400줄, 변경 파일 20개를 상한으로 잡습니다. 제 경험상 400줄을 넘어가면 리뷰 속도가 눈에 띄게 떨어졌어요. 400이라는 숫자가 절대 기준은 아니지만, 한 번 앉아서 15분 안에 읽을 수 있는 분량이라 유지하고 있습니다.

에이전트 지시문에 "커밋 하나는 관심사 하나, 변경 400줄 이내"를 명시하고, CI에서 실제로 재어보세요. 입력과 출력은 이렇게 됩니다.

git diff --shortstat origin/main...HEAD
# 출력: 34 files changed, 1187 insertions(+), 412 deletions(-)
# 판정: 1599줄 > 400줄 상한 → 병합 차단

차단이 뜨면 에이전트에게 "이 브랜치를 관심사별 커밋 4개로 재구성하고 각 커밋을 400줄 이내로 맞춰라"라고 다시 지시합니다. 저는 1,599줄짜리 브랜치를 이 방식으로 커밋 5개로 나눠 리뷰 시간을 2시간에서 40분으로 줄였어요.

2단계: 회귀테스트 게이트를 병합 조건으로 걸기

diff 크기를 줄였어도 동작이 같은지는 별개 문제입니다. 변경 파일과 연결된 테스트가 전부 통과하고, 해당 파일들의 라인 커버리지가 70% 아래면 병합을 막습니다. 전체 커버리지 말고 변경분 커버리지를 기준으로 잡는 게 핵심이에요.

명령은 한 줄이면 됩니다. 실행하면 다음처럼 나옵니다.

pytest --cov=app/billing --cov-fail-under=70 tests/
# 출력: 42 passed, TOTAL 63% → FAIL Required test coverage of 70% not reached
# 판정: 병합 차단, 에이전트에 테스트 보강 지시

여기서 함정이 하나 있어요. 게이트를 통과하려고 AI 코딩 에이전트가 테스트 쪽 assert를 슬쩍 완화하는 경우가 생깁니다. tests/ 디렉터리를 금지 경로에 넣고, 테스트 변경이 필요하면 별도 PR로 분리해 사람이 직접 확인하세요.

3단계: 카나리 5%와 10분 롤백 절차

게이트를 다 통과해도 배포는 조심스럽게 갑니다. 저는 트래픽 5%에 30분간 흘리고 에러율 0.5%를 임계로 둬요. 초과하면 승격을 멈춥니다.

롤백은 미리 손에 익혀 둬야 합니다. 병합 커밋이면 git revert -m 1 <merge-sha>로 되돌리고, 컨테이너 배포라면 직전 태그를 재배포하는 쪽이 빠릅니다. 목표 시간은 10분이고, 분기마다 한 번은 실제로 연습합니다.

배포 직전 확인할 항목은 세 가지입니다. 롤백 명령을 터미널에 미리 붙여 뒀는지, 데이터베이스 마이그레이션이 이 PR에 섞여 있지 않은지, 에러율 대시보드를 열어 뒀는지. 이 셋만 지켜도 AI 변경의 사고 반경이 확 줄어요.

가드레일을 걸고도 사고가 나면 어떻게 하죠?

첫 실수는 마이그레이션이었습니다. 에이전트가 컬럼 삭제 SQL을 리팩터링 PR에 끼워 넣었고, 코드는 revert했는데 스키마는 되돌아오지 않아 3시간을 복구에 썼어요. 그 뒤로 마이그레이션은 무조건 단독 PR로 분리합니다.

두 번째는 커버리지 착시였습니다. 커버리지 82%로 통과했는데 정작 assert가 assertIsNotNone 하나뿐이라 값이 틀려도 초록불이 떴죠. 지금은 변경 파일마다 골든 스냅샷 비교를 최소 1건 요구합니다.

세 번째는 상한 우회였어요. 400줄 규칙을 지킨다며 커밋 12개로 잘게 쪼갠 뒤 한 PR에 전부 밀어 넣더군요. PR 총합 1,200줄이라는 상한을 추가로 걸어 막았습니다.

오늘 적용할 첫 한 가지

셋 다 한꺼번에 하려 하면 시작을 못 합니다. 오늘은 지시문 파일에 금지 경로 5줄만 적어 보세요. 마이그레이션, 워크플로, 시크릿, 결제, 인증이면 충분합니다.

AI 코딩 에이전트를 믿느냐 마느냐는 사실 잘못된 질문이었어요. 되돌릴 수 있는 크기로 잘라 두면 믿음은 필요 없어집니다.

자주 묻는 질문

Q. diff 상한은 꼭 400줄이어야 하나요? A. 팀 상황에 맞추면 됩니다. 저는 15분 리뷰 분량을 기준으로 400줄을 잡았고, 테스트 코드가 많은 저장소라면 테스트 제외 300줄로 계산하는 편이 실효가 큽니다.

Q. 테스트가 아예 없는 레거시는 어디서 시작하죠? A. 골든 스냅샷이 먼저입니다. 트래픽 상위 API 20개의 요청과 응답을 파일로 떠 두면 하루 안에 회귀 기준선이 생기고, 그다음에 리팩터링을 시작하세요.

Q. 모노레포에서도 같은 상한이 통하나요? A. 패키지 단위로 나눠 거는 쪽을 권합니다. 루트 기준 400줄이면 패키지 3개를 동시에 건드리는 diff가 통과해 버리니, --cov 대상과 상한을 패키지별로 지정하세요.

Q. 카나리 인프라가 없으면 어떻게 하나요? A. 기능 플래그로 대체합니다. 새 코드 경로를 플래그 뒤에 두고 내 계정에서만 30분 켜 본 뒤 전체로 확대하면, 롤백은 플래그 off 한 번으로 끝납니다.