코딩 에이전트가 작성한 풀 리퀘스트 검토 방법

코딩 에이전트가 만든 풀 리퀘스트(pull request)는 피곤한 사람이 만든 것보다 훨씬 깔끔해 보인다. 설명은 완벽하고, 코드는 포맷되어 있으며, 테스트를 통과했고, 변경된 모든 줄에는 이유가 명시되어 있다. 바로 이 '완성도' 때문에 검토하기 어렵다. 뭔가 이상하다는 일반적인 신호(지저분한 diff, 모호한 설명, 누락된 테스트)가 전혀 없다.

에이전트가 저지르는 실수는 사람이 하는 실수와 다르다. 그들은 세미콜론을 잊어버리는 법은 거의 없다. 대신 팀이 반대하기로 결정한 방식으로 문제를 해결하거나, 다른 코드가 의존하고 있다는 사실을 인지하지 못한 채 무언가를 변경하는 경우가 많다. 이 두 가지 문제는 단순히 diff만 읽는다면 눈에 보이지 않는다.

우리가 사용하는 체크리스트는 다음과 같다.

1. 설명을 가장 나중에 읽기

에이전트는 자신이 무엇을 하려 했는지에 대한 자신감 넘치는 요약을 작성한다. 먼저 diff를 읽어보고 어떤 부분이 변경되었는지 스스로의 견해를 형성한 다음, 그것을 설명과 비교해야 한다. 이 둘 사이의 간극에서 버그가 발견된다: "재시도 로직(retry logic)을 리팩토링했다"고 했지만 타임아웃 기본값(timeout default)까지 변경했거나, "필드를 추가했다"고 했지만 기존 필드 중 하나를 선택 사항으로 만들었다는 식이다.

2. 무엇이 무엇에 의존하는지 질문하기

PR에서 변경된 모든 함수, 타입 또는 내보내기 값(exported value)에 대해 호출자(callers)를 찾아야 한다. diff에 있는 것들만 찾는 것이 아니라, 전부 다 찾아야 한다.

"loadSettings에 필수적인 orgId 매개변수를 추가하라"는 요청을 받은 에이전트는 함수와 찾은 모든 호출자를 업데이트할 것이다. 이들이 모든 것을 찾았는지 여부는 검색 방식에 달려 있다. 사용자의 편집기에서 제공하는 "참조 찾기(find references)" 기능이나 grep 명령어는 10초가 걸리지만, 에이전트 PR을 검토할 때 할 수 있는 가장 가치 높은 작업이다.

도구가 아무것도 호출하지 않는다고 말할 때는 의심해야 한다. 자체 측정 결과에 따르면, 실제 호출자가 존재했던 26개 함수 중 17개에 대해 코드 그래프가 호출자가 '0'이라고 보고하며 "정확함(exact)"이라는 레이블을 붙였다. 도구의 "결과 없음(No results)"은 "안전함"이 아니라 "알 수 없음(unknown)"을 의미한다.

3. 팀이 이미 결정한 사항과 비교하기

모든 코드베이스에는 컴파일러가 강제하지는 않지만 지켜야 할 규칙들이 있습니다. 모든 데이터베이스 접근은 레포지토리 계층(repository layer)을 거쳐야 하고, 프롬프트는 인라인 문자열이 아닌 파일에 존재해야 하며, 모델 호출은 공유 클라이언트 하나를 통해 이루어져야 하고, 논의 없이 새로운 종속성(dependency)을 추가해서는 안 됩니다. 사람들은 이런 규칙들을 리뷰 코멘트를 통해 배웁니다. 에이전트는 그렇지 않습니다. 에이전트가 읽을 수 있도록 어딘가에 글로 적혀 있지 않다면 말입니다.

리뷰할 때는 다음 질문을 던지세요: 이것이 우리 팀에서 하는 방식(how we do things here)을 따르는 것인가, 아니면 단순히 작동하는 방법일 뿐인가? 에이전트의 PR은 팀이 선택한 방식이 아니라 인터넷상에서 가장 흔한 패턴으로 흘러가려는 경향이 있습니다.

4. 범위 확장(scope creep) 확인하기

에이전트는 정리 정돈을 좋아합니다. 버그 하나를 수정하는 PR이라도 에이전트가 무언가를 '감지'했기 때문에 세 개의 관련 없는 파일을 건드리는 경우가 있습니다. 이러한 정리 작업은 아무도 리뷰해 달라고 요청하지 않은 작고 원치 않는 변경 사항입니다. 이 부분들을 분리하거나(split out) 되돌리도록(reverted) 요청하세요.

5. 테스트가 변경 사항을 테스트하는지 확인하기

에이전트는 테스트를 통과시키는 데 능숙하며, 때로는 그 과정에서 테스트 자체를 수정하기도 합니다. 코드의 diff만큼이나 테스트의 diff도 주의 깊게 살펴보세요: 느슨해진 단언(assertion), 새로운 skip 사용, 이제 코드가 기대하는 모든 것을 반환하는 모의 객체(mock). 자체적으로 테스트를 수정한 PR에 붙은 녹색 체크 표시는 생각보다 가치가 적습니다.

6. 성공 경로뿐만 아니라 오류 경로도 확인하기

에이전트가 작성한 코드는 요청받은 케이스를 처리하는 경향이 있습니다. 실패 분기(failure branches)에서 무슨 일이 일어나는지 살펴보세요: 삼켜진 에러(swallowed errors), 로그를 남기고 계속 진행하는 catch 블록, 조용히 빈 리스트를 반환하는 폴백(fallback). 이러한 것들은 성공 케이스만 테스트하는 모든 테스트를 통과합니다.

검사 항목을 더 앞당기기

이 체크리스트의 대부분은 리뷰어가 에이전트가 PR을 열기 전에 할 수 있었던 작업을 하는 것입니다. 이 많은 부분을 작성 시간(write time)으로 옮길 수 있습니다:

에이전트가 읽을 수 있는 곳에 결정을 기록하세요. 각 규칙뿐만 아니라 그 이유도 함께 CLAUDE.md, .cursor/rules 또는 AGENTS.md에 작성하세요. 에이전트는 자신이 볼 수 있는 규칙을 따릅니다.
"모든 호출자 찾기(find all callers)"를 작업의 일부로 만드세요. 에이전트에게 시그니처가 변경되는 모든 항목의 호출자를 나열하고 각각을 업데이트하거나 설명하도록 지시하세요. 스스로 하기를 바라는 것보다 훨씬 효과적입니다.
PR(Pull Request)은 작게 유지하세요. PR당 하나의 우려 사항만 다루세요. 에이전트에게 맡기면 기꺼이 한 번에 다섯 가지 일을 처리하지만, 다섯 가지는 하나보다 검토하기가 훨씬 어렵습니다.

두 가지 어려운 부분을 자동화하세요

단계 2와 3은 수동으로 처리하기 어려운 부분입니다. 변경된 모든 심볼의 호출자를 찾고 팀이 내린 모든 결정을 기억하는 것은 하루에 열 번째 에이전트 PR을 검토하는 리뷰어에게는 너무 많은 요구 사항입니다.

저희가 바로 이 문제를 해결하기 위해 Tently를 만들었습니다. 이는 GitHub용 AI 코드 리뷰어로, 각 풀 리퀘스트(pull request)를 해당 코드가 의존하는 코드와 팀의 결정 사항에 대해 검사합니다. 이 결정 사항은 병합된 PR, 리뷰 스레드 및 문서를 통해 학습됩니다. 발견된 내용은 증거(영향받는 호출자 또는 결정 내용과 출처)와 함께 PR에 표시됩니다. 기존에 사용하던 어떤 리뷰 도구 옆에서도 작동합니다.

동일한 결정 사항은 Claude Code, Cursor 및 Codex를 위한 오픈 소스 MCP 서버(tently-team/tently-mcp)를 통해 에이전트가 작성하는 동안에도 사용할 수 있어, PR에 도달하는 문제 자체가 줄어듭니다.

도구 유무와 관계없이, 다음 체크리스트는 여전히 중요합니다:

설명(description)보다 먼저 diff를 읽으세요.
변경된 모든 항목의 호출자를 찾으세요.
팀의 결정 사항과 비교하세요.
범위 확장(scope creep)에 대해 제동을 거세요.
테스트 변경 사항을 코드만큼 신중하게 검토하세요.
오류 경로를 읽으세요.