코드 리뷰를 수주 프로젝트의 품질 보증에 통합한 결과 — 납품 전 검토를 '사람의 선의'에서 분리하기

왜 이것을 만들었는가

수주 개발에서 가장 무서운 것은 버그 그 자체가 아닙니다. '검토했다고 생각하고 납품하는 코드' 입니다.

저는 혼자 수주 프로젝트를 진행합니다. 구현도 제가 하고, 리뷰도 저 자신이 합니다. 졸린 금요일 밤에 제가 작성한 코드를 제가 '뭐 괜찮겠지'라며 통과시킵니다. 이것을 수십 번 반복하면 반드시 한 번은 운영 환경에서 노출됩니다. 그때까지의 대책은 '조심하는 것'이었지만, 조심하는 것은 시스템이 아니므로 효과가 없었습니다.

그래서 Claude Code의 /code-review를 기분에 의존하지 않는 게이트로서 납품 플로우에 삽입했습니다. 효과를 본 것은 '버그 탐지 능력'이 아니라 '리뷰를 건너뛸 수 없게 만든 것' 입니다.

무엇에 얼마나 효과가 있었는가

도입 전후로 바뀐 점은 다음 3가지입니다.

다만 /code-review가 찾아내는 것은 '코드로서 파탄한 부분'일 뿐이며, '사양과 다른 부분'은 찾지 못합니다. 이곳을 혼동하면 AI 리뷰가 통과된 코드를 무검증으로 납품하는 최악의 운영이 됩니다.

구현: 납품 전 게이트를 하나의 스크립트로 만들기

저는 사내 자동화를 launchd + bash로 통일했기 때문에, 리뷰도 같은 형식으로 맞췄습니다. 기존 GitHub 모니터링 스크립트와 동일한 골격(상태 파일 + 로그 + Slack 알림)입니다.

#!/bin/bash
# 납품 전 코드 리뷰 게이트
# 사용법: ./review-gate.sh <프로젝트 디렉토리> <베이스 브랜치>
...

포인트는 3가지입니다.

1. --permission-mode plan을 추가한다. 리뷰에 쓰기 권한을 주지 않는다.

/code-review --fix는 편리하지만, 납품 전 게이트에서 자동 수정(auto-fix)을 실행하면 '누가 무엇을 고쳤는지 알 수 없는 diff'가 고객에게 전달됩니다. 읽기만 하게 한다. 2. 결과를 파일에 남긴다. 지적이 0건이라도 '이 시점에서 리뷰했다'는 증거가 남습니다. 수주 프로젝트에서는 사고 발생 시 '어디까지 확인했는지'를 설명할 수 있는 것이 탐지 그 자체만큼 가치가 있습니다.

3. exit 1로 중단시킨다. 알림만으로는 바쁜 주에 반드시 무시하게 됩니다. 멈추지 않는 게이트는 게이트가 아닙니다.

effort의 사용 구분

/code-review는 레벨을 지정할 수 있습니다. 저의 운영은 이렇습니다.

# 일일 커밋 단위: 속도 우선, 확실한 지적만
claude -p "/code-review low"
# 납품 전: 폭넓게 본다. 불확실한 지적이 섞여도 좋으니 포착한다
...

high 이상은 '아마 문제' 같은 것도 내놓습니다. 납품 전의 경우에는 그것이 옳습니다. 정밀도를 높이는 것보다 놓치는 것을 줄이는 것이 더 저렴합니다.

함정 (실제로 빠진 것)

diff가 너무 크면 품질이 떨어진다. 2주 분량을 한 번에 던지니 지적이 표층적으로 변했습니다. 대책은 베이스를 가깝게 하는 것입니다(기능 단위로 브랜치를 자르기). 리뷰를 기능하게 만들기 위해 브랜치 전략을 수정하는, 역방향의 변경이 되었습니다.

자동 수정을 섞은 날에 망가뜨렸다. --fix를 납품 전 플로우에 넣었던 적이 있고, 여러 파일에 수정이 들어갔습니다. 동작은 했지만, 제가 내용을 파악하지 못한 코드가 납품물에 섞였습니다. 과거 AI의 출력을 무확인으로 영업 메일을 전송하여 거래처에 부적절한 경어 사용 메일이 도착했던 것과 같은 구조입니다. 대외로 나가는 것은 draft → 확인 → 실행으로 되돌렸습니다.

리뷰가 통과되었으니 괜찮다고 생각하기 시작한다. 가장 위험한 부작용입니다. 게이트의 Slack 알림 문구에 매번 '사양 확인은 별도'라고 넣어, 시스템으로 자신의 방심을 상쇄하고 있습니다.

검증 방법

효과가 있는지 확인하려면, 알려진 버그를 통과시키는 것이 빠릅니다.

# 과거 운영 환경에서 발생했던 버그의 커밋을 재생하여 탐지 가능한지 확인
git checkout -b review-eval <버그를 포함하는 커밋>
claude -p "/code-review high <그 부모 커밋>...HEAD" | tee eval.md
...

저는 과거의 결함 3건을 테스트해 보았는데, 2건은 감지했고, 1건(사양 오인)은 감지되지 않았습니다. 이 '감지할 수 없는 1건'을 사전에 아는 것이 도입 판단 그 자체입니다. 감지할 수 없는 영역을 인간의 공정으로 남겨둘 수 있습니다.

맡긴 것 / 맡기지 않은 것

결론

혼자서 외주 작업을 진행하다 보면, 품질 보증이 '내가 제대로 하겠다'는 정신론에 빠지기 쉽습니다. 정신론은 바쁜 시기에 가장 먼저 무너집니다.

/code-review

을 통해 얻은 것은 뛰어난 리뷰어가 아니라, 바쁜 자신이 리뷰를 건너뛸 수 없는 구조입니다. 효과의 원천이 거기라는 것을 알고 있다면 도입 판단은 어렵지 않습니다. 스크립트 한 개와 30분 만에 테스트해 볼 수 있습니다.

이 글의 주제를 체계화한 도서

Claude Code를 사용한 자동화, 품질 보증, 권한 설계 구현 내용은 책으로 정리했습니다. 실제로 회사에서 구동하고 있는 구성이 기반이므로 그대로 손쉽게 재현할 수 있습니다.

Discussion