Hunk로 읽는 에이전트 변경과 코드 리뷰 기준

에이전트의 완료 보고를 검토할 때는 실제 변경과 설명을 대조해야 합니다. 커밋된 변경, 작업 트리 수정과 새 파일은 비교 명령에 따라 포함 범위가 달라집니다. 먼저 읽을 범위를 정한 뒤 호출자와 입력, 테스트 조건을 확인합니다.

lucas가 소개한 Hunk는 터미널에서 diff를 읽는 뷰어입니다. diff는 수정 전후의 차이를 표시한 자료입니다. 에이전트의 설명과 바뀐 파일을 대조하는 데 사용할 수 있습니다. 이 글에서는 비교 범위를 정하고 변경의 근거를 확인하는 절차를 설명합니다.

읽을 변경의 범위

Hunk의 설치 안내에서 운영체제에 맞는 방법을 고릅니다. npm 설치는 Node.js 22 이상을 필요로 하며 패키지 이름은 hunkdiff입니다. 설치 후 hunk --version으로 실행 가능 여부를 확인하고, 검토할 Git 저장소에서 시작합니다.

git status --short
hunk diff
hunk show HEAD

git status --short로 현재 수정과 새 파일의 목록을 확인할 수 있습니다. 공식 작업 트리 안내에 따르면 hunk diff는 작업 트리의 변경을 리뷰 화면으로 열며 추적하지 않는 파일도 기본으로 포함합니다. 설치한 버전의 옵션과 비교 범위는 도움말에서 확인합니다. hunk show HEAD는 최신 커밋의 변경을 엽니다. 에이전트가 커밋까지 만들었는지, 아직 작업 트리에 수정이 남았는지에 따라 검토 범위가 달라집니다.

Git이 만든 패치만 그대로 보고 싶다면 git diff --no-color | hunk patch -를 사용할 수 있습니다. 이 경우 범위는 Git이 출력한 내용이며 새 파일은 자동으로 포함되지 않습니다. staged 변경만 볼 때는 앞의 명령에 --cached를 붙입니다. 서로 다른 범위를 같은 리뷰 결과로 취급하지 않도록 먼저 파일 목록을 대조합니다.

Hunk 공식 저장소의 다중 파일 리뷰 화면입니다. 파일 목록과 코드 diff, 인라인 설명을 함께 표시합니다. 공식 예시의 설명

새 파일을 포함하는 비교

에이전트가 기존 파일을 수정하고 새 설정 파일도 만들었다고 가정해보겠습니다. hunk diff와 Git 패치를 여는 방식은 새 파일을 포함하는 범위가 다르므로 화면의 파일 목록을 git status --short와 대조합니다.

확인 대상	명령	읽을 범위
작업 트리 수정과 새 파일	hunk diff	추적하지 않는 파일도 포함
Git이 출력한 작업 트리 패치	git diff --no-color → hunk patch -	Git 패치에 포함된 변경
최신 커밋	hunk show HEAD	해당 커밋의 변경

이 표는 명령의 비교 범위를 정리한 것입니다. 모든 명령이 같은 변경을 보여준다고 가정하면 새 파일이나 커밋된 변경을 놓칠 수 있습니다.

추가된 파일과 삭제된 파일도 구분합니다. 새 설정 파일이 실행 경로를 바꾸는지, 제거한 파일이 다른 곳에서 참조되는지 살펴봅니다. 생성된 파일이 많다면 원본 변경과 생성 결과를 나누어 읽되 최종 산출물에 누락이 없는지도 확인합니다.

여러 작업자의 수정이 섞였다면 작업 시작 시점의 상태와 현재 파일 목록을 비교합니다. 이번 에이전트가 만든 변경을 구분한 뒤 해당 파일을 읽습니다.

변경한 줄의 호출자와 입력

파일 목록을 확인했다면 리뷰어는 바뀐 코드가 어디에서 호출되고 어떤 입력을 받는지 살펴봅니다. diff에 추가된 줄뿐 아니라 주변 함수와 데이터 흐름도 필요한 만큼 읽습니다. 조건 하나를 바꿨더라도 다른 사용자나 다른 입력에 영향을 줄 수 있기 때문입니다.

예를 들어 검색 결과를 날짜순으로 정렬하는 변경이라면 비교 함수만 확인하는 것으로 끝내지 않습니다. 날짜 형식, 값이 없는 결과, 동일한 날짜의 순서, 페이지를 나누는 기준도 확인해야 합니다. 화면에서 한 번 정상으로 보였다는 사실은 모든 조건의 근거가 아닙니다.

리뷰어는 변경의 목적을 짧게 설명해 볼 수 있습니다. “이 줄은 결과가 없을 때 빈 목록을 반환한다”처럼 동작을 말하면 코드와 설명의 차이를 찾기 쉽습니다. 설명하기 어려운 변경은 작성자에게 결정 이유를 확인할 수 있습니다.

테스트가 지키는 조건

테스트가 함께 바뀌었다면 통과 여부뿐 아니라 무엇을 검증하는지 읽습니다. 원래 실패하던 조건을 삭제하거나 기대값을 구현에 맞게 바꿨다면 결함을 숨길 수 있습니다. 요구사항이 바뀐 경우에는 새 기대값의 근거가 있어야 합니다.

새 테스트에서는 실제 입력과 기대 결과를 읽습니다. 정렬 함수를 바꿨다면 동일 날짜와 날짜가 없는 입력에 대한 기존 검사가 유지되는지 확인할 수 있습니다.

리뷰어는 검토 기록에 사용한 비교 명령과 읽은 파일 범위를 남깁니다. Git 패치만 읽었다면 새 파일을 별도로 확인했는지 적고, 최신 커밋만 읽었다면 작업 트리에 남은 수정은 아직 미검토인지 표시합니다.

검토 결과에는 비교 범위, 확인한 동작과 남은 질문을 기록합니다. 설명과 코드가 다른 부분이나 근거를 확인하지 못한 결정은 작성자에게 확인한 뒤 승인 여부를 판단합니다.