[태그:] Git diff

  • AI가 만든 대규모 PR 리뷰, 파일명 대신 의존성부터 읽어야 한다

    AI가 만든 대규모 PR 리뷰, 파일명 대신 의존성부터 읽어야 한다

    여러 파일을 한 번에 생성하는 AI 코딩 에이전트가 등장하면서, 리뷰어의 작업 방식도 바뀌어야 합니다. 화면에 dozens of files가 올라온 대규모 PR 리뷰를 앞에서부터 읽다 보면, 구현은 보이지만 그 구현을 지탱하는 계약과 스키마는 뒤늦게 보입니다. 결국 시간을 많이 쓴 뒤야 변경의 중심이 무엇인지 파악하게 됩니다.

    특히 git diff가 파일 경로와 이름 순서로 파일을 보여줄 때, 그 순서는 시스템의 책임 분배나 실행 흐름을 설명하지 않습니다. 에이전트가 만든 20-file 변경에서는 유틸리티 헬퍼나 UI 컴포넌트를 먼저 읽고, 실제 동작을 결정하는 데이터베이스 스키마나 핵심 인터페이스를 나중에 만나게 될 수 있습니다. 리뷰어가 해야 할 일은 더 많은 줄을 읽는 것이 아니라, 그 줄들이 어떤 계약과 호출 경로에 연결되는지 먼저 파악하는 것입니다.

    왜 알파벳순 diff는 구조를 보여주지 않는가

    파일 목록은 저장소 디렉터리의 결과이지 아키텍처의 결과가 아닙니다. UI가 서비스 함수를 호출하고, 서비스가 인터페이스를 의존하며, 인터페이스가 데이터 모델을 요구한다면, 파일 이름 정렬만으로는 그 방향을 알 수 없습니다. 호출 그래프를 머릿속에서 다시 그리기 시작하는 순간, 이미 코드 검토보다 구조 복원이 더 큰 비중을 차지합니다.

    이 문제는 자동화 도구를 하나 더 붙여 해결할 수 없습니다. AI 에이전트가 만든 변경 설명을 그대로 검토 전제로 삼거나, 통과한 테스트를 근거로 최종 diff만 승인하면 의존성 누락을 그대로 통과시킬 수 있습니다. 대규모 변경의 검토 대상은 구현량이 아니라 계약이 어떻게 바뀌고, 그 계약의 수신자와 호출자가 어디까지 영향을 받는지입니다.

    이 문제를 다루기 위해 에이전트가 만든 대규모 변경을 리뷰하는 방식에 대한 토론이 시작됐습니다. 핵심 질문은 단순합니다. 팀은 20-file diff를 어떤 순서로 읽어야 하는가입니다.

    파일 목록을 계약과 호출 흐름으로 다시 배치하기

    첫 단계는 변경 파일을 임의로 줄 세우는 대신 책임별로 분류하는 것입니다. 계약·인터페이스·스키마를 먼저 놓고, 도메인 서비스와 오케스트레이션을 그다음에 검토합니다. 이후 변경된 인터페이스를 호출하는 호출자, 테스트, 마지막으로 표현 계층을 확인합니다. 이 순서는 파일 수가 많을 때 모든 줄을 같은 깊이로 읽지 않고 위험도가 높은 의존 경로에 집중하게 합니다.

    확인 도구는 Git의 diff 명령을 단계적으로 사용하는 것으로 충분합니다. 규모와 파일 목록을 분리해서 보는 것이 핵심입니다.

    git diff --stat
    git diff --name-only
    git diff --find-renames
    git diff --word-diff

    --stat은 변경 규모를, --name-only는 검토 대상 목록을, --find-renames는 파일 이동과 변경을 구분하는 데 씁니다. 계약이나 설정처럼 한 줄의 의미가 중요한 변경에는 --word-diff가 구현 디테일을 덜 놓칩니다. 이 명령들의 결과는 다시 계약·스키마·호출자·테스트·표현 계층의 목록으로 재배치해야 합니다.

    스키마와 인터페이스의 영향 범위 찾기

    핵심 계약을 읽을 때 구현 세부만 판단해서는 안 됩니다. 해당 인터페이스를 직접 호출하는 코드, 메시지나 API 응답을 만드는 코드, 저장된 데이터를 읽는 마이그레이션 경로를 함께 찾습니다. 인터페이스 변경이 있으면 하위 호환성이 깨질 수 있는지, 응답 구조가 바뀌면 수신자가 영향을 받는지, 스키마 변경이 있으면 마이그레이션과 롤백 순서가 유효한지가 각각의 검증 항목이 됩니다.

    검토 문서에는 변경의 진입점, 변경된 계약, 예상되지 않은 호출 경로, 되돌릴 때의 상태를 먼저 적습니다. 호출자와 수신자, 스키마 변경은 하나의 논리적 단위로 묶되, 가능하면 계약 변경·호출자 반영·데이터 마이그레이션·동작 변경을 작은 단위로 분리합니다. feature flag를 쓸 수 있는 환경이라면 실제 도달 범위를 제한하고, 단계적으로 배포해 회귀가 발생했을 때 원인을 좁힐 수 있습니다.

    테스트는 통과 여부가 아니라 검증 게이트다

    대규모 PR 리뷰에서 테스트는 마지막에 한 번 실행하는 의례가 아닙니다. 변경 범위가 계약에 닿으면 계약 테스트를, 여러 계층이 연결되면 통합 테스트를, 스키마가 바뀌면 마이그레이션 검증과 롤백 검증을 함께 배치합니다. 실패 경로를 포함하지 않은 테스트는 성공 경로의 표현만 확인할 뿐, 실제 리스크가 있는 분기를 검증하지 못합니다.

    병합 전 리뷰 요청서에는 변경 요약, 영향 범위, 실행한 검증, 남은 위험, 롤백 방법을 함께 남깁니다. 테스트가 통과해도 계약의 의도가 맞는지, 호출자가 모두 반영됐는지, 되돌리면 데이터 상태가 안전한지는 별도로 판단해야 합니다. 이렇게 해야 AI 산출물의 설계를 그대로 믿는 대신, 독립적인 검증 대상으로 취급할 수 있습니다.

    실무에서 흔히 생기는 한계와 함정

    의존성 중심 리뷰를 도입하면 비용이 추가됩니다. 호출 그래프를 정리하는 시간과 파일 간 관계를 설명하는 시간이 들고, 아키텍처 경계가 불분명한 저장소에서는 분류 자체가 어려워집니다. 자동 분류 결과와 실제 호출 흐름이 다를 수 있으므로, 도구가 만든 목록을 검토 전제로 삼지 말고 사람이 연결 관계를 확인해야 합니다.

    가장 흔한 안티패턴은 이름순으로 읽자마자 구현을 판단하는 것, 에이전트의 변경 목적을 그대로 받아들이는 것, 테스트 통과만으로 최종 diff를 병합하는 것입니다. 대량 변경을 작은 논리적 단위로 나누면 병합 가능한 범위는 줄지만, 계약과 호출자가 서로 다른 묶음에 흩어질 수 있습니다. 분리 기준은 파일 수가 아니라 호환성 책임과 롤백 가능성입니다.

    지금 바로 해볼 것

    • 현재 브랜치에서 git diff --stat와 git diff --name-only를 실행하고 변경 규모와 파일 목록을 각각 기록합니다.
    • 파일 목록을 계약·스키마·서비스·호출자·테스트·표현 계층으로 분류합니다.
    • 변경된 인터페이스와 스키마를 검색해 호출자, 수신자, 마이그레이션 경로를 함께 표시합니다.
    • git diff --find-renames로 실제 이동과 변경을 구분하고 git diff --word-diff로 계약 변화를 다시 읽습니다.
    • 병합 전에 계약·통합·스키마·실패 경로 테스트와 롤백 방법을 리뷰 요청서에 남깁니다.

    참고 원문

    이 기사는 다음 원문을 확인해 작성했습니다: r/devops — Why are we still reviewing massive PRs in alphabetical file order?