빌드 설정 의존성 버전 고정으로 재현 가능한 환경 확보

빌드 설정은 한 번 손대고 잊기 쉬운 영역이다. 기능 개발처럼 티가 나지 않고, PR 리뷰에서도 "설정 파일 한 줄 바꿨네" 하고 넘어가기 일쑤다. 그런데 막상 문제가 터지면 원인이 여기서 나오는 경우가 생각보다 많다. 이번 작업도 그런 맥락에서 시작됐다.

.claude/CLAUDE.md에 모놀리식 규칙서를 추가하고, 빌드 스크립트에서 implicit하게 처리되던 의존성 버전을 전부 explicit으로 끌어올렸다. 수정 파일 1개, 기능 영향 없음. 숫자만 보면 별거 아닌데, 이 작업이 왜 필요한지 설명하려면 좀 돌아가야 한다.

버전 미지정이 조용히 만드는 문제들

의존성에 버전을 안 박으면 어떻게 될까. 빌드 툴이 "최신 버전"을 알아서 가져온다. 로컬에서 처음 세팅할 때는 괜찮다. 문제는 시간이 지나면서 생긴다.

한 달 뒤 새로운 팀원이 환경을 세팅한다. 그 사이 라이브러리가 마이너 버전이 올라갔다. 똑같은 코드, 똑같은 명령어인데 동작이 다르다. 더 나쁜 케이스는 CI 서버와 로컬이 달라지는 것이다. 로컬에서 빌드 성공, CI에서 실패. 아니면 반대로. 이 상황에서 원인 파악하는 데 드는 시간이 실제 개발 시간보다 길어진다.

# 이전 방식 — 버전 미지정
# dependency.group=com.example
# dependency.artifact=some-lib

# 이후 방식 — 버전 명시화
dependency.version=2.4.1
# 빌드 환경이 어디서든, 언제든 동일한 버전을 참조

이게 작은 차이처럼 보이지만, 실제로 "재현 가능한 빌드(reproducible build)"의 핵심이다. 같은 소스 코드 + 같은 의존성 버전 = 같은 결과물. 이 등식이 보장되어야 배포에 대한 신뢰가 생긴다.

이번에 불필요한 설정 항목도 같이 정리했다. 오래된 프로젝트에서 자주 보이는 패턴인데, 이미 기본값과 동일한 설정이 명시적으로 적혀 있거나, 더 이상 사용하지 않는 플러그인 설정이 주석도 없이 남아있는 경우다. 이런 게 쌓이면 새 사람이 들어왔을 때 "이 설정 왜 있어요?"라는 질문이 계속 나온다. 답을 아는 사람도 없고.

빌드 스크립트 최적화도 같이 했다. 불필요한 단계를 없앴는데, 단계 하나가 사라진다는 게 단순히 속도 문제가 아니다. 단계가 많을수록 실패 지점도 많아진다. 불필요한 단계는 유지비용을 먹고, 언젠가 깨진다.

의존성 관리를 미루면 어떻게 되나

의존성 업데이트를 오래 미뤄두면 나중에 한꺼번에 올려야 하는 상황이 온다. 그때는 breaking change가 복수로 겹쳐서 어디서 뭐가 터진 건지 파악하기가 진짜 힘들다. 라이브러리 A 업데이트가 문제인지, B 업데이트가 문제인지, 아니면 둘이 조합되면서 생긴 건지. 이분법적으로 좁혀가려 해도 가짓수가 너무 많아진다.

반면 꾸준히 소폭씩 올리면 어떤 업데이트에서 문제가 생겼는지 바로 보인다. 롤백도 쉽다. 결국 총 투입 시간은 전자보다 후자가 훨씬 적다. 다만 전자는 고통이 나중에 몰리고, 후자는 고통이 고르게 퍼질 뿐이다.

이번 작업을 계기로 정기 점검 루틴을 만들기로 했다. 수동으로 챙기는 건 한계가 있으니, 자동화할 수 있는 부분은 자동화한다.

• 의존성 새 버전 알림 - 패치/마이너 업데이트 나오면 PR 자동 생성
• 보안 취약점 스캔 - 주기적으로 돌려서 CVE 리포트 받기
• 빌드 상태 모니터링 - 설정 변경 즉시 CI 트리거

이게 갖춰지면 이번처럼 한 번에 몰아서 손대는 일이 줄어든다. 잡무성 작업이 쌓이지 않는 구조를 만드는 게 목표다. 이런 설정 레벨 작업은 기능 개발에 비해 우선순위에서 밀리기 쉬운데, 밀릴수록 나중에 더 큰 시간을 요구한다는 걸 경험으로 알고 있다.

직접적인 비즈니스 로직을 건드린 작업이 아니었지만, 개발 환경 안정성이라는 측면에서 의미 있는 시간이었다. 재현 가능한 빌드 환경을 유지하는 게 장기적으로 훨씬 중요하다는 건, 한 번쯤 "이 서버에서만 왜 안 되지?"를 겪어본 사람이면 다 공감할 거다.