에이전트가 PR 설명을 작성하지만, 코드의 기능만 설명할 뿐이다

마치 코드 투어처럼 읽히는 설명

당신은 에이전트로부터 PR을 엽니다. 설명은 깔끔합니다:

• /checkout 엔드포인트에 입력 유효성 검사(input validation) 추가
• calculateTax를 별도의 모듈로 리팩토링
• 새로운 엣지 케이스(edge case)를 커버하도록 단위 테스트 업데이트
• 마이너 의존성 버전 올리기(Bumped minor dependencies)

읽기에는 깨끗합니다. 이 설명은 diff가 무엇을 하는지 알려줍니다. 하지만 다음 내용은 알려주지 않습니다:

• 왜 지금 유효성 검사가 추가되었는지 (사고가 있었나요? 고객 티켓이 있었나요? 보안 문제가 발견되었나요?)
• 무엇이 거부되었고 그 이유는 무엇인지 (먼저 미들웨어 레벨(middleware-level) 유효성 검사를 시도했었나요?)
• 작성자가 확신하지 못하는 부분이 무엇인지 (새로운 세금 모듈이 국제 주소를 처리할 수 있나요?)
• 리뷰어가 실제로 봐야 할 부분은 무엇인지 (마이그레이션이 되돌릴 수 있나요? 만료된 세션(stale sessions)에는 무슨 일이 일어나나요?)

두 번째 목록이야말로 당신이 사람에게 리뷰를 요청하는 이유 전체입니다. 첫 번째 목록은 git diff --stat가 이미 알려준 것입니다.

리뷰어는 '왜'를 역추적할 수 없다

설명이 단지 diff를 서술만 할 때, 리뷰어는 두 가지 나쁜 선택을 하게 됩니다:

1. 느낌에 따라 승인한다(Approve on vibes). 코드는 합리적으로 보이고, 테스트가 통과하며, 배포하자.
2. diff를 주의 깊게 읽으며 의도를 역추적하고, 작성자가 걱정했을 수 있는 엣지 케이스를 추측한다.

옵션 1은 미묘한 버그가 배포되는 방식입니다. 옵션 2는 15분짜리 리뷰를 한 시간으로 만들며, 리뷰어는 여전히 댓글로

PR을 열기 전에 다음 각 항목에 대해 짧은 섹션을 작성하세요:

1. 무엇이 깨졌거나 이 변경이 필요한 요청 사항 — 단락이 아닌 한 문장으로 작성합니다.
2. 시도했지만 포기한 것 — 처음에 시도했던 접근 방식과 그것이 왜 더 나빴는지 설명합니다.
3. 여전히 확신하지 못하는 것 — 가장 자신 없는 엣지 케이스(edge case), 마이그레이션 단계, 버전 증분 등을 언급합니다.
4. 리뷰어가 실제로 확인해야 할 것 — 전체 diff가 아니라 눈을 가져다주고 싶은 특정 함수나 동작 하나를 지정합니다.
5. 어떻게 검증했는지 — "테스트 통과" 같은 추측이 아닌, 정확한 명령어와 그 출력을 제시합니다.

앞의 세 가지는 시니어 엔지니어가 옆에 앉아 있을 때 PR에 작성할 내용입니다. 마지막 두 가지는 리뷰어가 한 시간 대신 15분 만에 작업을 완료하는 데 필요한 최소한의 노력입니다.

왜 이것을 건너뛰기 쉬운가

이것은 추가적인 과정처럼 느껴집니다. 실제로는 에이전트가 이미 실행하는 프롬프트에 단락 하나를 추가하는 것에 불과하며, 리뷰의 형태를 "diff를 읽고 추측하기"에서 "작성자가 이미 제기한 우려 사항에 응답하기"로 바꿉니다.

에이전트가 자신이 확신하지 못하는 것을 나열하면, 리뷰 자체가 더 좋아집니다. 리뷰어들은 명백한 버그를 찾는 데 에너지를 낭비하는 대신 실제 열린 질문에 집중하게 됩니다. 검증 명령을 인라인으로 작성하면, "테스트 통과"라는 말만 믿는 것이 아니라 해당 명령어를 직접 실행할 수 있습니다.

diff 설명은 목차(table of contents)로 유용합니다. 이는 리뷰가 존재하는 목적, 즉 엔지니어링 판단의 대체재가 될 수는 없습니다.

API 변경에서도 같은 간극이 나타난다

에이전트가 API를 건드릴 때도 패턴은 같습니다. 새로운 필드를 문서화하고, 새로운 상태 코드를 나열하지만, 해당 변경 사항이 **하위 호환성(backward compatible)**을 갖는지 여부, 이전 형태를 보내는 구형 클라이언트에게 무슨 일이 발생하는지, 그리고 스펙이 라이브 엔드포인트와 재확인되었는지 등의 정보는 빠뜨립니다. 단순히 계약 드리프트(contract drift)만을 서술하는 설명은 리팩토링(refactor)을 서술하는 것만큼이나 쓸모가 없습니다.

우리는 마지막 검사를 Powerduck의 로컬 플로우에 직접 구축하게 되었습니다. 사양(spec)이 진실의 원천(source of truth)이며, 에이전트는 변경 사항이 완료되었다고 주장하기 전에 반드시 라이브 엔드포인트(live endpoint)를 대상으로 재실행해야 합니다. PR에는 여전히 사람이 필요하지만, '계약(contract)이 실제로 이동했는가?'라는 질문은 검토 시점의 놀라움(surprise)이 아니게 됩니다.

내일 변경할 것들

당신의 에이전트가 열었던 마지막 세 개의 PR을 살펴보세요. 코드를 본 적 없는 리뷰어 입장에서 설명을 읽어보세요. 만약 '왜 이 변경이 필요한지, 무엇이 거부되었는지, 무엇에 대해 확신하지 못하는지'를 답변할 수 없다면, 문제는 모델(model)이 아니라 프롬프트(prompt)입니다.

요약본을 요청하는 것을 멈추세요. 옆자리에 앉아 있는 팀원에게 소리 내어 말해줄 부분들을 요청하세요.