리뷰어가 아직 알지 못하는 PR을 여세요

최근 리뷰해야 할 PR(Pull Request)을 하나 받았습니다. 변경 사항(diff)이 방대하고, AI의 도움을 받았으며, 다른 세 가지 기능이 의존하고 있는 모듈을 건드리는 내용이었습니다. 설명(description)은 단 한 문장이었습니다. 이유가 아닌 파일 이름만 적혀 있었습니다.

리뷰를 시작하기도 전에 변경 사항을 파악하는 데만 15분을 썼습니다. 의도가 무엇인지, 리스크(risk)가 어디에 있는지, 어떤 파일이 중요하고 어떤 파일이 노이즈(noise)인지 파악하는 데 말입니다.

그 15분 중 어느 시점에 이런 생각이 들었습니다. '나도 누군가에게 이런 식으로 한 적이 있었지.'

작성자는 리뷰어가 모르는 것을 잊어버린다

코드를 작성할 때, 당신은 모든 것을 머릿속에 담고 있습니다.

왜 모듈을 분리했는지 알고 있습니다. 이곳에 도달하기 전까지 무엇을 시도했는지 알고 있습니다. 어떤 섹션을 약간의 의구심을 품은 채 배포했는지 알고 있습니다. 기술적으로는 처리되었지만 제대로 테스트되지 않은 엣지 케이스(edge case)도 알고 있습니다.

그러고 나서 PR을 엽니다.

그리고 그 상태에서 설명을 작성합니다. 모든 맥락을 이미 알고 있는 '과거의 자신'을 위해, 전체 맥락 안에서 작성합니다. 아무것도 모른 채 들어오려는 리뷰어를 위해서가 아닙니다.

"서비스 레이어 리팩토링 (Refactored service layer)."

"설정 처리 업데이트 (Updated config handling)."

"인증 모듈의 이슈 수정 (Fixed issue with auth module)."

이것들은 기억을 바탕으로 작성된 설명이지, 기억이 없는 누군가를 위한 설명이 아닙니다.

AI가 인지하기도 전에 격차를 벌렸다

PR을 올리고 며칠 뒤, 제가 올린 PR들을 다시 보며 느꼈던 특유의 불안함이 있습니다.

코드는 괜찮습니다. 테스트도 통과합니다. 하지만 왜 그런 선택을 했는지 스스로 재구성할 수가 없습니다. 작업은 AI의 도움을 받았고, 변경 사항(diff)은 컸으며, 저는 빠르게 움직였습니다. 빠르게 움직이는 것과 깊이 이해하는 것은 같은 것이 아닙니다.

최근에 그런 PR 중 하나를 열어보았습니다. 리팩토링 작업이었습니다. 리뷰어의 입장에서 읽어보려 노력했습니다. 설명만으로는 답할 수 없는 질문이 하나 생겼습니다. 답은 존재했습니다. 코드를 작성할 때 제 머릿속에 있었습니다. 하지만 PR에는 전혀 담기지 않았습니다.

그 순간 깨달았습니다. 설명은 요약이 아니었습니다. 그것은 테스트였습니다.

3일 뒤에 이 코드를 리뷰할 당신의 버전을 위해 작성하라

그 깨달음은 제가 설명을 작성하는 방식을 바꾸어 놓았습니다.

템플릿이 먼저가 아닙니다. 질문이 먼저입니다. 만약 내가 아무것도 모르는 상태로 3일 뒤에 이 PR (Pull Request)로 돌아온다면, diff (차이점)를 열어보기 전에 무엇을 읽어야 할까?

나는 이 질문을 충분히 고민한 끝에 구조가 필요하다는 것을 깨달았습니다. 빠르게 작업할 때 건너뛸 수 있는 무언가가 아니라, 사소하지 않은 PR을 열기 전에 반드시 따르는 구체적인 템플릿 말입니다. 나는 이를 구축하고, 리팩터링 (refactoring) 과정, AI 보조 기능 개발, 그리고 더 큰 아키텍처 (architecture) 변경 사항들을 거치며 테스트했으며, 이것이 제대로 작동할 때까지 다듬었습니다.

그것은 여섯 부분으로 구성됩니다.

의도 (Intent) - 무엇이 바뀌었는가가 아니라, 왜 이 PR이 존재하는지 그리고 어떤 문제를 해결하고 있는지에 대한 것입니다. 한 단락으로 작성합니다. 만약 이를 명확하게 쓸 수 없다면, 멈추십시오. 그 PR은 열 준비가 되지 않은 것입니다.

주요 변경 사항 (Major changes) - 아키텍처 (architecture), 기존 동작, 또는 다운스트림 시스템 (downstream system)이 의존하는 모든 것에 영향을 미치는 결정 사항들입니다. 리뷰어가 속도를 늦추고 주의 깊게 봐야 할 부분입니다.

사소한 변경 사항 (Minor changes) - 정리 작업, 이름 변경, 노이즈 (noise) 등입니다. 구조적 변경 사항과 나란히 놓여 동일한 비중을 갖지 않도록 별도로 명시합니다.

영향 (Impact) - 이 PR이 어떤 기능, 모듈, 또는 시스템에 영향을 미치는지입니다. 영향 범위 (blast radius)를 솔직하게 기술합니다. 문서화가 아니라 지도 (map)를 그리는 것입니다.

증거 (Evidence) - 무엇을 실행했는지, 무엇을 수동으로 검토했는지, 커버리지 (coverage)가 어떠했는지에 대한 것입니다. 프로세스를 만족시키기 위함이 아닙니다. 작성자가 다른 사람에게 요청하기 전에 스스로 작업을 완료했다는 증거입니다.

그리고 대부분의 설명이 도달하지 못하는 마지막 한 가지: 내가 무엇에 대해 확신하지 못하는가입니다.

불확실성을 명시하는 것은 약점이 아닙니다. 그것은 방향입니다.

무언가가 작동은 하지만 왜 그런지 완전히 설명할 수 없을 때, 나는 설명 (description)에 직접적으로 그렇게 적습니다.

리뷰어에게 이것은 타겟팅 신호 (targeting signal)가 됩니다. 그들은 어디를 면밀히 읽어야 할지, 어디를 빠르게 지나쳐도 될지를 알게 됩니다. 이것이 없다면, 리뷰어는 주의를 기울일 가치조차 없는 diff (차이점) 전체에 주의력을 균등하게 분산시키게 됩니다.

이를 작성하는 것은 체크포인트 (checkpoint) 역할을 합니다. 만약 내가 무엇에 대해 불확실한지 이름을 붙일 수 없다면, 나는 내 코드에 대해 충분히 깊게 생각하지 않은 것입니다. 이 원칙 덕분에 나는 준비되지 않은 PR을 여는 것을 멈출 수 있었습니다.

설명(Description)은 리뷰 전의 마지막 단계가 아닙니다. 그것은 이 PR을 열어야 할지 말지를 결정하기 전의 마지막 단계입니다.

이 PR을 여는 리뷰어는 아직 당신의 코드를 만나지 못했습니다

내가 자랑스럽게 배포했던 PR들과 질문이 쏟아져 돌아온 PR들을 비교해 보면, 그 차이는 코드인 경우가 거의 없습니다.

그것은 바로 설명(Description)입니다.

첫 읽기부터 당신의 의도(Intent)를 이해하는 리뷰어는 어려운 질문에 시간을 할애합니다. 당신의 의도를 재구성해야 하는 리뷰어는 쉬운 질문에 시간을 허비합니다. 그것이 맞는지 아닌지가 아니라, 그것이 무엇인지 묻는 데 시간을 씁니다.

이 시리즈의 Part 1은 동일한 문제에 대한 리뷰어의 관점을 다룹니다. 만약 이 글에 먼저 도착했다면, 잠시 돌아가 볼 가치가 있습니다. 그곳의 논지는 이렇습니다: 이제 리뷰어는 표면적인 정확성(Correctness) 너머를 보고 의도(Intent)를 찾아내야 합니다. 하지만 의도는 저절로 나타나지 않습니다. 리뷰가 시작되기 전에 누군가가 그것을 그곳에 적어두어야 합니다.

아직 당신의 코드를 만나지 못한 리뷰어를 위해 작성하세요.

질문에 답하기 위해 당신이 그 자리에 없을 것처럼 작성하세요.

이 글을 읽을 다음 사람이, 작성했다는 기억이 전혀 없는 3일 뒤의 당신이라고 가정하고 작성하세요.

이 원칙이 통한다면, 그 PR은 준비된 것입니다.