코딩 에이전트가 검증된 수정 사항으로 만들 수 있는 리뷰 피드백 작성 방법

제목: 버그 리포팅 및 기능 제안을 위한 구조화된 접근법

요약 답변: 문제가 되는 동작(problematic behavior)을 설명하고, 해당 동작이 발생하는 조건(conditions where it appears), 그리고 유지되어야 할 원하는 결과(outcome you want preserved)를 명시하세요. 집중적인 수정 사항과 기존 동작에 실패하는 테스트 케이스를 요청해야 합니다. 병합을 막는 문제(merge-blocking problem)와 기다릴 수 있는 개선 제안(improvement suggestion)은 분리하여 제시하십시오.

선호도가 아닌 시나리오로 시작하기

"이건 정리할 필요가 있다(this needs cleaning up)" 같은 코멘트는 실제 작업을 받는 사람에게 남겨진 막연한 지시입니다. 코멘트를 작업으로 전환하려면, 시스템에서 무엇을 할 수 있는지 그리고 그 결과로 어떤 일이 발생하는지 구체적으로 작성해야 합니다.

real-browser-mcp의 PR #60에 대한 공개 토론은 구체적인 문제점들을 보여줍니다: 동일한 탭에서 두 개의 동시 동작(concurrent actions)이 발생하면 두 그룹을 만들 수 있으며, 디버거 연결(debugger connections) 두 개가 있을 경우 단 하나의 탭만 추적되었더라도 하나 이상의 탭에 연결될 수 있습니다. PR의 답변은 또한 테스트해야 할 내용들을 설명합니다. 이들은 모든 가능한 브라우저 환경을 다루었다는 증거라기보다는 시나리오를 위한 자료입니다.

수정 사항에 대한 짧은 계약서 작성하기

다음 구문이 제안된 템플릿입니다:

첫 번째 요청이 완료되기 전에 두 개의 요청이 동일한 리소스에 도달할 경우, 시스템은 합의된 결과(agreed outcome)를 보존해야 합니다. 이전 버전에서 충돌을 재현하는 테스트를 보여주고, 동작을 수정하며, 새 버전에서 해당 테스트가 통과함을 보여주십시오. 어떤 부분이 테스트되지 않았는지 명시하십시오.

"합의된 결과"는 실제 요구사항으로 대체되어야 합니다: 하나의 그룹, 하나의 연결, 또는 명확한 오류(clear error)여야 합니다. 이 각각은 서로 다른 결정입니다. 합의된 바가 없다면, 에이전트에게 선택을 요청하기 전에 토론을 여십시오.

블로커와 제안 사항 분리하기

검토는 버그 수정, 설계 질문, 또는 코드 정리 등 여러 가지를 다룰 수 있습니다. 자신이 작성한 코멘트가 어떤 종류인지 표시하십시오. 변수 이름에 대한 제안은 비록 같은 스레드 내에서 나타나더라도 권한(permissions) 수정과는 동등하지 않습니다.

GitHub의 문서는 세 가지 리뷰 상태를 설명합니다: 댓글(comment), 승인(approve), 그리고 변경 요청(request changes)입니다. '변경 요청'이 병합을 차단하는지 여부는 브랜치 보호 규칙에 따라 다릅니다. 댓글에 '차단 요소(blocker)'라는 단어를 쓰는 것은 저장소 규칙의 기술적 정의가 아닙니다.

검증하기에 충분히 작은 단위로 유지하기

변경 사항이 두 개의 분리된 메커니즘을 포함할 경우, 분리를 요청할 수 있습니다. 공개 예시에서는 탭 그룹 관리와 디버거 처리가 두 개의 PR(Pull Request)로 분리되었습니다. 이렇게 나누면 각 부분을 하나의 묶음에 묶지 않고도 의도와 증거를 검증할 수 있습니다.

분리는 그 자체로 목표가 아니라 작업 도구입니다. 만약 동작을 올바르게 유지하기 위해 두 부분이 함께 배포되어야 한다면, 종속성과 병합 순서를 문서화해야 합니다. 에이전트가 브랜치를 준비할 수는 있지만, 공유 계약에 대한 결정은 변경 소유자에게 남아 있습니다.

댓글 후 무엇이 바뀌었는지 확인하기

승인하기 전에 새로운 diff와 추가된 테스트를 읽어보세요. 테스트가 현재 코드가 작성된 방식뿐만 아니라 논의에서 제기된 동작을 건드리고 있는지 확인해야 합니다. 실행 결과, 버전, 그리고 명령어를 요청하세요. PR 본문에 있는 계획된 테스트 목록은 실행 결과가 아닙니다.

에이전트가 '모든 댓글이 처리됨'이라고 요약하면, 원래 목록으로 다시 보내야 합니다. 모든 댓글에는 수정 사항, 왜 필요하지 않은지에 대한 설명, 또는 연기하기로 한 결정이 필요합니다. 화면에서 스크롤되어 사라진 대화 흐름은 문제가 해결되었다는 증거가 아닙니다.

재현 가능한 결론으로 마무리하기

좋은 수정 사항은 댓글, 요구사항, 그리고 증거를 연결합니다. 이렇게 하면 나중에 PR을 읽는 사람이 왜 변경이 이루어졌고 무엇을 보존해야 하는지 이해할 수 있습니다. 리뷰의 목표는 피드백을 받는 사람을 추측가로 만들지 않으면서 동작을 개선하고 이를 검증하는 방법을 제공하는 것입니다.

제 경험에서 우러나온 이야기

실제 브라우저 환경(real-browser-mcp)에 기여하는 것에 대한 게시물에서, 저는 검토 후 두 개의 별도 PR과 테스트 과정에서 발견된 사례에 대한 수정 사항을 가지고 돌아온 한 기여자(contributor)를 설명했습니다. 이 가이드는 모든 변경 사항이 이미 테스트되었다고 가정하지 않고도 적용할 수 있는 작동 방식(working approach)을 제안합니다.

요약

문제가 되는 동작, 해당 동작이 나타나는 조건, 그리고 유지하고 싶은 결과(outcome)를 설명하세요. 집중적인 수정과 기존 동작에 대해 실패하는 테스트를 요청하세요. 병합을 막는 문제(merge-blocking problem)와 연기할 수 있는 개선 제안을 분리하세요.

FAQ

댓글(comment)과 변경 요청(request for changes)의 차이점은 무엇인가요?

github은 리뷰 상태로 댓글, 승인(approve), 그리고 변경 요청을 지원합니다. 실제 블록 여부는 단순히 댓글의 문구에 의해서가 아니라 브랜치 규칙(branch rules)에 따라 달라집니다.

에이전트가 모든 리뷰 댓글을 처리할 수 있나요?

합의된 경계 내에서 수정 사항과 증거를 준비할 수는 있습니다. 설계 질문이나 계약 변경에는 명시적인 결정이 필요합니다.

PR을 분리해야 하는 경우는 언제인가요?

독립적으로 검증될 수 있는 별도의 메커니즘들이 있을 때입니다. 의존성(dependency)이 있다면, 그와 함께 변경 사항이 적용되어야 할 순서도 문서화하세요.

저자 소개

Ofer Shapira - AI 빌더이자 개발팀 리드로서, 에이전트, 결정, 그리고 검증할 수 있는 워크플로우에 대해 글을 쓰고 있습니다.