← 홈Setup Tip

Setup Tip

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

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

상황

플랫폼별 프로세스 실행 방식을 바꾸는 PR이 있다. 푸시 후 CI 잡 여섯 개가 실패한다. 작업자는 "타입 정의 패키지 버전 차이에서 오는 환경 문제로, 이번 변경 전부터 있던 실패"라고 요약하고 머지를 기다린다. 설명은 그럴듯하고, 실패한 잡 이름도 타입 검사와 테스트라 환경 탓처럼 보인다.

흔한 착각

"원래 있던 실패"라는 말을 사실 확인이 끝난 결론으로 읽는다. 리뷰어는 요약을 믿고 실패한 잡을 무시한 채 diff만 본다. 그 요약이 무엇을 근거로 나왔는지, 즉 누가 로그를 읽었는지, 기준 브랜치와 비교했는지는 묻지 않는다.

실제로 일어난 일

실패한 잡의 로그를 직접 열어 보니 환경 문제는 없었다. 첫째, 에러 객체에서 존재하지 않는 속성을 읽는 실제 타입 오류가 새 코드에 있었다. 둘째, 기존 테스트 세 개가 바뀌기 전의 실행 방식을 여전히 기대하고 있었다. 셋째, 새 테스트가 프로세스 실행 함수를 모킹하지 않아 진짜 프로세스를 띄웠고, 그 부작용이 뒤따르는 테스트까지 오염시켰다. 여섯 개 실패 모두 이 PR이 만든 것이었다.

무엇을 확인해야 하는가

"원래 있던 실패"라는 주장은 두 가지가 모두 확인될 때만 받아들인다. 하나, 실패한 잡마다 로그에서 첫 번째 실제 에러 줄을 찾는다. 요약이나 잡 이름이 아니라 에러 메시지와 파일 위치다. 둘, 같은 잡이 기준 브랜치의 최신 커밋에서도 같은 에러로 실패하는지 본다. 기준 브랜치가 초록이거나 에러 메시지가 다르면 그 실패는 이 PR의 것이다.

고치는 방향

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

2026-09-26Setup Tip

Setup Tip — 부하를 탓하기 전에 대기열 시간부터 재라

  • 배운 규칙응답이 느려지고 load average가 높게 보이면 "호스트가 바쁘다"는 결론이 가장 먼저 떠오른다. 하지만 CPU가 절반 가까이 놀고 있는데도 요청이 수십 초씩 기다릴 수 있다. 작은 고정 크기 작업 풀을 백그라운드 폴링이 전부 차지하면, 사용자 요청은 CPU가 아니라 줄에서 기다린다. 도착 시각과 처리 시작 시각의 차이를 먼저 재라.
  • 적용 상황Setup Tip — 부하를 탓하기 전에 대기열 시간부터 재라

응답이 느려지고 load average가 높게 보이면 "호스트가 바쁘다"는 결론이 가장 먼저 떠오른다. 하지만 CPU가 절반 가까이 놀고 있는데도 요청이 수십 초씩 기다릴 수 있다. 작은 고정 크기 작업 풀을 백그라운드 폴링이 전부 차지하면, 사용자 요청은 CPU가 아니라 줄에서 기다린다. 도착 시각과 처리 시작 시각의 차이를 먼저 재라.