← 홈Setup Tip

Setup Tip

Setup Tip — 보고된 파일 목록이 아니라 스테이징된 파일 목록이 진짜 변경이다

작업자가 "파일 세 개를 고쳤다"고 보고해도, 커밋에 실제로 들어간 파일은 다를 수 있다. 리뷰나 머지 전에 커밋의 파일 목록과 크기를 보고된 목록과 한 줄씩 맞춰 보고, 작업 트리에 남은 빌드 산출물은 커밋 전에 걸러라.

상황

모델 별칭 하나를 추가하는 작은 작업이다. 작업 레인은 "코드 한 곳, 테스트 한 곳, 문서 한 곳, 총 파일 세 개"라고 보고하고 변경 요청을 연다. 설명과 목적이 모두 맞고, 테스트도 초록이다. 리뷰어가 할 일은 세 파일의 diff를 읽는 것뿐인 것처럼 보인다.

흔한 착각

보고서의 파일 목록을 변경의 범위로 믿는다. 리뷰어는 보고된 세 파일만 열어 보고, 목록 밖에 무엇이 들어왔는지는 묻지 않는다. 특히 바이너리 파일은 diff 화면에서 한 줄짜리 "변경됨"으로만 보여서, 그냥 넘기기 쉽다.

실제로 일어난 일

커밋에는 파일이 네 개 있었다. 보고된 세 파일 말고 약 6MiB짜리 패키지 압축 파일이 저장소 최상위에 함께 커밋되어 있었다. 패키징을 확인할 때 작업 트리에 남는 종류의 파일이다. 처음 이걸 잡은 것은 사람이 아니라 자동 리뷰 봇이었다. 커밋을 고쳐 그 파일을 빼고 다시 푸시하자 파일 수가 보고와 같은 세 개가 되었고, 그 뒤에 머지되었다.

무엇을 확인해야 하는가

파일 목록은 보고서가 아니라 커밋에서 읽는다. 기준 브랜치와 비교한 파일별 변경 요약을 뽑아, 보고된 목록과 개수와 이름이 정확히 같은지 본다. 목록에 없는 파일이 하나라도 있으면 그 이유가 설명될 때까지 리뷰를 멈춘다. 크기도 함께 본다. 몇 줄 고친 작업에 수 MiB짜리 파일이 있다면 거의 항상 실수다.

고치는 방향

커밋할 때 작업 트리 전체를 한꺼번에 담지 말고 바꾼 파일을 경로로 지정해 스테이징한다. 커밋 직전에는 스테이징된 파일 목록을 한 번 읽는다. 패키지 압축 파일이나 빌드 결과물처럼 로컬 확인 과정에서 생기는 파일은 무시 목록에 넣어, 실수로 담으려 해도 담기지 않게 한다. 이미 들어갔다면 커밋을 고쳐 빼고, 그 파일이 이력에 남지 않았는지 확인한다.

확인 방법

변경 요청에 "보고된 파일 목록"과 "커밋의 실제 파일 목록" 두 줄을 나란히 남긴다. 두 줄이 같고, 목록에 바이너리나 큰 파일이 없을 때만 리뷰로 넘어간다. 둘이 다르면 그 차이 자체가 첫 번째 리뷰 코멘트다.

같이 읽으면 좋은 글

같이 읽으면 좋은 글

2026-09-29Setup Tip

Setup Tip — "원래 깨져 있던 것"은 진단이 아니라 주장이다

  • 배운 규칙PR의 CI가 빨갛고 작업자가 "우리 변경과 무관한, 원래부터 있던 환경 문제"라고 보고하면, 그 말을 받아들이기 전에 실패한 잡의 실제 로그를 열고 같은 잡이 기준 브랜치에서도 같은 이유로 실패하는지 확인하라. 두 조건 중 하나라도 확인되지 않으면 그 실패는 이 PR의 것이다.
  • 적용 상황Setup Tip — "원래 깨져 있던 것"은 진단이 아니라 주장이다

PR의 CI가 빨갛고 작업자가 "우리 변경과 무관한, 원래부터 있던 환경 문제"라고 보고하면, 그 말을 받아들이기 전에 실패한 잡의 실제 로그를 열고 같은 잡이 기준 브랜치에서도 같은 이유로 실패하는지 확인하라. 두 조건 중 하나라도 확인되지 않으면 그 실패는 이 PR의 것이다.

2026-09-28Setup Tip

Setup Tip — 호출하는 곳이 없는 새 함수는 아무것도 바꾸지 않는다

  • 배운 규칙기능 PR이 새 모듈과 그 모듈의 단위 테스트를 추가했고 CI도 초록이라면, 머지 전에 한 가지를 더 확인하라. 새로 export한 함수를 실제 실행 경로에서 부르는 곳이 있는가. 호출처가 0이면 테스트는 함수가 맞게 동작한다는 것만 증명할 뿐, 제품의 동작은 한 줄도 바뀌지 않았다.
  • 적용 상황Setup Tip — 호출하는 곳이 없는 새 함수는 아무것도 바꾸지 않는다

기능 PR이 새 모듈과 그 모듈의 단위 테스트를 추가했고 CI도 초록이라면, 머지 전에 한 가지를 더 확인하라. 새로 export한 함수를 실제 실행 경로에서 부르는 곳이 있는가. 호출처가 0이면 테스트는 함수가 맞게 동작한다는 것만 증명할 뿐, 제품의 동작은 한 줄도 바뀌지 않았다.

2026-09-27Setup Tip

Setup Tip — 충돌 없이 끝난 병합도 브랜치를 지울 수 있다

  • 배운 규칙기능 브랜치에 기준 브랜치를 병합하고 충돌을 해결했는데 CI가 갑자기 대량으로 실패한다면, 테스트보다 병합 결과를 먼저 의심하라. 충돌 파일을 통째로 기준 브랜치 쪽으로 해결하면 브랜치의 변경이 조용히 사라진다. 브랜치가 건드린 파일마다 "병합 결과가 기준 브랜치와 바이트 단위로 같은가"를 확인하면 몇 초 만에 드러난다.
  • 적용 상황Setup Tip — 충돌 없이 끝난 병합도 브랜치를 지울 수 있다

기능 브랜치에 기준 브랜치를 병합하고 충돌을 해결했는데 CI가 갑자기 대량으로 실패한다면, 테스트보다 병합 결과를 먼저 의심하라. 충돌 파일을 통째로 기준 브랜치 쪽으로 해결하면 브랜치의 변경이 조용히 사라진다. 브랜치가 건드린 파일마다 "병합 결과가 기준 브랜치와 바이트 단위로 같은가"를 확인하면 몇 초 만에 드러난다.