AI 코드 리뷰 에이전트를 파이프라인에 연결했고, 잘 작동했습니다. 누락된 null 체크를 짚어내고, 쓰이지 않는 import를 잡아내고, 네이밍에 대해 깔끔한 코멘트 세 개를 남겼죠. 그래서 병합했습니다. 그런데 이틀 뒤, 에이전트가 그냥 지나쳐 버린 버그를 고객이 겪었습니다. 변경 사항은 내부적으로 깔끔했지만 잘못된 일을 하고 있었습니다. 리뷰 에이전트는 코드를 검증했습니다. 의도는 검증하지 못했습니다.
이 간극이 바로 AI 코드 리뷰 에이전트에 관한 모든 이야기입니다. 이들은 검증 가능한 특정 부류의 문제에는 강하지만, diff에서는 똑같아 보이는 다른 부류의 문제에는 눈이 먼 상태입니다. 에이전트의 승인을 최종 수용으로 착각하면 눈먼 영역의 문제를 그대로 배포하게 됩니다. 경계가 어디에 있는지 알면, 리뷰어가 사람만이 내릴 수 있는 판단에 집중할 수 있도록 빠른 1차 검토를 확보할 수 있습니다.
이 글에서는 그 경계를 그려 봅니다. AI 코드 리뷰 에이전트가 검증할 수 있는 것과 없는 것, 그리고 이 둘을 혼동하지 않게 해 주는 운영 모델입니다. Sharkly는 여기서 살펴볼 레이어로, 에이전트 리뷰와 사람의 수용이 같은 Task 위에서 하나의 도장이 아니라 서로 다른 두 가지 상태로 존재하는 공유 워크스페이스입니다. 이미 코딩 에이전트는 갖고 계실 테니, 여기서 핵심은 두 번째 에이전트가 루프를 닫아 준다고 착각하지 않고 그 결과물을 리뷰하는 것입니다.
AI 코드 리뷰 에이전트가 검증할 수 있는 것
AI 코드 리뷰 에이전트는 diff를 읽고, 그에 대한 검사를 실행하고, 사람 리뷰어가 코멘트를 남기듯 결과를 보고하는 프로그램입니다. 이 에이전트가 신뢰할 수 있는 영역은 꼼꼼한 리뷰어라면 변경 사항과 그 인접 코드를 읽고 확인할 수 있는 모든 것입니다.
- 기계적 정확성: 문법, 타입, 명백한 null 및 경계 처리, 처리되지 않은 promise rejection, diff에서 드러나는 리소스 누수.
- 국소적 로직: off-by-one 오류, 뒤집힌 조건, 죽은 분기, 값이 설정되기 전에 읽히는 변수.
- 관례: 네이밍, 포맷팅, import 위생, 새 함수 옆에 테스트가 있는지 여부.
- 알려진 안티패턴: 문자열 연결로 만든 SQL, 평문으로 커밋된 시크릿, 입력 검증이 빠진 public 메서드.
이것들은 한 가지 공통점이 있습니다. 근거가 diff 안에 존재한다는 점입니다. 에이전트는 이런 문제를 잡아내는 데 여러분의 비즈니스를 알 필요가 없고, 오후 6시에 지친 사람보다 더 빠르고 일관되게 잡아냅니다. 이건 실질적인 가치이며, 팀들이 이런 도구에 손을 뻗는 이유입니다. Google의 코드 리뷰 가이드는 이런 기계적 검토를 기본 전제로 취급해, 사람의 관심이 설계에 쏠릴 수 있게 합니다. AI 리뷰어는 지치지 않고 매번 이 관문을 통과하게 해 주는 수단입니다.
검증할 수 없는 것
경계를 분명히 말하자면 이렇습니다. AI 코드 리뷰 에이전트는 그 변경이 올바른 변경인지 검증할 수 없습니다. 아래 항목들은 모두 diff에 담겨 있지 않은 맥락을 필요로 합니다.
- 의도 대 스펙. 코드는 완벽무결할 수 있지만 잘못된 문제를 풀고 있을 수 있습니다. 이를 판단하는 것은 오직 티켓의 인수 기준이며, 에이전트는 그것을 보는 경우가 드뭅니다.
- 비즈니스 정확성. 할인 규칙, 세금 계산, 권한 경계가 회사의 실제 업무 방식과 맞는지는 린트 규칙이 아니라 판단의 문제입니다.
- 시스템 간 동작. 한 파일에서는 문제없어 보이는 변경이 세 개 서비스 건너편의 호출자를 망가뜨릴 수 있습니다. OWASP Top Ten에는 diff가 아니라 전체 요청 경로를 추적할 때만 드러나는 접근 제어 실패 같은 결함이 가득합니다.
- 테스트가 정직한지 여부. 에이전트는 테스트가 존재하고 통과하는지 확인할 수 있습니다. 하지만 그 테스트가 정말 중요한 것을 검증하는지, 혹은 코드를 작성한 에이전트가 통과만 하도록 만든 테스트를 함께 작성했는지는 알려주지 못합니다.
마지막 항목이 AI가 작성한 코드에 특유한 함정입니다. 같은 부류의 시스템이 변경과 리뷰를 모두 만들어 내면, 깔끔한 diff와 초록 체크가 둘 다 사실이면서 둘 다 핵심에서 벗어나 있을 수 있습니다. 그래서 리뷰 에이전트의 승인은 결정이 아니라 신호입니다. 에이전트는 보고하고, 사람이 수용합니다.
그 간극을 메우는 운영 모델
해법은 더 나은 리뷰 에이전트가 아닙니다. 리뷰 에이전트의 역할과 사람의 역할이 서로 다른 상태이고, 어느 쪽도 건너뛰지 않는 운영 모델입니다.
Sharkly는 이러한 상태를 Task 상태로 명시합니다. Task는 In progress에서 Ready for review를 거쳐 Done으로 이동합니다. 규칙은 단순하지만 핵심을 떠받칩니다. 에이전트는 작업을 Ready for review로 옮기고, 사람이 Done으로 옮깁니다. 코드를 작성했든 리뷰했든, 에이전트는 자기 작업을 수용됨으로 표시할 수 없습니다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 수용합니다. 자동화는 팀의 판단이 필요한 지점에서 멈춥니다.
각 역할에는 하나의 임무가 있습니다. 코딩 Agent는 변경 사항을 만들어 냅니다. 리뷰 Agent는 기계적 검토를 실행하고 그 결과를 첨부합니다. 사람 리뷰어는 그 결과를 읽고, 변경 사항이 티켓의 의도에 맞는지 확인하고, 결정을 내립니다. 이 모든 것이 Task로 돌아옵니다. diff, 리뷰 Agent의 코멘트, 테스트 출력, 사람의 결정이 PR과 채팅, 누군가의 기억에 흩어지는 대신 하나의 타임라인에 남습니다.
변경이 기계적이고 자기 완결적일 때, 예컨대 리팩터링, 의존성 업데이트, 범위가 잘 정해진 버그 수정이라면 리뷰 에이전트를 첫 번째 게이트로 사용하세요. 잡음을 걸러내게 해서 사람의 검토가 빠르게 진행되도록 하면 됩니다. 반면 변경이 금전, 인증, 데이터 마이그레이션, 공개 계약에 닿는다면 그것만을 유일한 게이트로 삼지 마세요. 이 경우에는 사람이 먼저 읽고, 에이전트의 검토는 평결이 아니라 체크리스트입니다.
실제 예시: 티켓부터 병합된 PR까지
SH-312를 예로 들어 보겠습니다. "결제 시 만료된 쿠폰 코드를 거부한다." 사람이 인수 기준을 작성하고 Task를 할당합니다. 코딩 Agent가 이를 가져가 격리된 워크트리에서 작업하고, diff와 통과하는 테스트를 Task에 반환하며 상태를 Ready for review로 옮깁니다.
이제 리뷰 Agent가 실행됩니다. 타입을 확인하고, 빠진 null 가드 하나를 짚어내고, 테스트가 만료된 케이스를 다루고 있다는 점을 기록합니다. 깔끔한 통과입니다. 예전 습관대로라면 이 승인으로 병합됩니다.
하지만 사람 리뷰어는 Task를 열고 의도에 비추어 읽습니다. 코드는 작성된 그대로 만료된 쿠폰을 거부합니다. 그러나 인수 기준에는 이미 사용된 쿠폰도 거부해야 한다는 의미가 담겨 있었고, 코딩 Agent도 리뷰 Agent도 그 사실을 알지 못했습니다. 그 내용은 diff가 아니라 리뷰어의 머릿속과 제품 스펙에 있었으니까요. 리뷰어가 변경을 요청합니다. SH-312는 구체적인 메모와 함께 In progress로 돌아가고, Agent가 이를 확장한 뒤에야 사람이 Done으로 옮기고 pull request를 병합합니다.
리뷰 에이전트는 자기 일을 잘 해냈지만 그대로 배포되었다면 빈틈을 남겼을 것입니다. 이를 잡아낸 것은 운영 모델입니다. 수용은 맥락을 가진 사람이 별도로 하는 행위였으니까요. 이는 태스크 수준의 근거로 AI 생성 코드를 리뷰하는 방법에 담긴 것과 같은 원칙입니다. 리뷰의 단위는 고립된 diff가 아니라 Task와 그 의도입니다.
리뷰 게이트를 어디에 둘 것인가
실용적인 질문은 AI 코드 리뷰 에이전트를 쓸지 말지가 아닙니다. 어디에서 에이전트의 통과가 유효하고, 어디에서 사람이 먼저 읽어야 하는가입니다. 견고하게 유지되는 몇 가지 규칙이 있습니다.
- 모든 변경에 대해 스타일, 포맷팅, 기계적 버그는 에이전트가 게이트를 맡게 하세요. 에이전트가 가장 잘하고, 사람이 지쳤을 때 가장 못하는 검토입니다.
- 인증, 결제, 데이터 마이그레이션, 공개 API에 닿는 모든 변경에는 사람의 게이트를 요구하세요. 사각지대가 바로 그곳에 집중됩니다.
- 게이트의 규모는 리뷰 역량에 맞추세요. 에이전트는 사람이 수용하는 속도보다 빠르게 결과물을 만들어 내므로, 사람의 검토는 에이전트가 눈먼 곳에 써야 합니다.
- 게이트를 습관이 아니라 상태로 만드세요. Done을 막는, 문서화된 승인 게이트는 강제할 수 있지만 "누군가 봐야 한다"는 관행은 그렇지 않습니다. 휴먼 인 더 루프는 그 루프가 워크플로가 요구하는 단계일 때만 작동합니다.
AI 코드 리뷰 에이전트는 사람 리뷰어를 대체하는 것이 아닙니다. 사람의 검토를 더 빠르고 예리하게 만들어 주는 1차 검토입니다. 이미 여러 코딩 에이전트를 돌리고 있고, 그 결과물을 다섯 개의 PR 탭 대신 한곳에서 리뷰하고 수용하고 싶다면, 그것이 바로 Sharkly가 겨냥해 만들어진 문제입니다. 공유 Task에서 에이전트 작업을 할당하고 추적하고 리뷰하는 것, 리뷰 Agent의 결과와 사람의 결정이 모두 같은 기록으로 돌아오는 것입니다. 이미 쓰고 있는 코딩 에이전트와 리뷰 에이전트는 그대로 두고, 언제 그들의 통과로 충분한지 판단하는 레이어를 추가하세요.
