저는 계속 유지하고 싶은 개인 프로젝트로 Codenames AI를 구축해 왔습니다. Renovate는 의존성 업그레이드 (dependency upgrades) 과정에서 유지보수 작업이 결국 추진력을 꺾어버리지 않도록 도와줍니다.

제 설정을 그대로 따를 필요는 없습니다.

모든 프로젝트에는 유지보수 작업이 쌓이기 마련입니다. 프레임워크 업그레이드 (Framework upgrades)는 작업이 정체되는 지점 중 하나인데, 이는 엔지니어가 마이그레이션 (migrate) 방법을 몰라서가 아니라, 실제로 무엇을 변경해야 하는지 증명하는 데 시간이 걸리기 때문입니다. 이러한 트레이드오프 (tradeoff)는 취미용 저장소 (hobby repo)에서는 "방해받지 않는 저녁 시간이 생기면 그때 봐야지"라는 식으로 나타납니다. 프로덕션 (production) 환경에서는 조사 작업이 기능 개발 (feature work)과 경쟁하는 동안 메이저 버전들이 계속 쌓이는 모습으로 나타납니다.

그것이 제가 해결하려 했던 문제입니다.

AI 이전에는 현실적인 선택지가 좁았습니다. 자동화를 믿고 희망을 품거나, 릴리스 노트 (release notes)를 코드베이스 (codebase)와 매핑하는 데 몇 시간을 소비하거나, 아니면 업그레이드를 그대로 방치하는 것이었습니다.

저는 더 나은 리뷰 프로세스 (review process)를 발명하려 했던 것이 아닙니다.

저는 유지보수 비용 (maintenance cost)을 가용 시간보다 낮게 유지하려 했던 것입니다.

AI는 조사 (investigation) 비용을 충분히 변화시켰고, 덕분에 저는 조사를 미뤄야 할 대상으로 취급하는 것을 그만두었습니다.

Renovate가 해당 프레임워크 메이저 버전 중 하나에 대해 풀 리퀘스트 (pull request)를 열었을 때, 즉 Vite를 ^6.0.11에서 ^8.0.0으로, @vitejs/plugin-react를 ^4.3.4에서 ^6.0.0으로 업그레이드할 때, 저의 첫 본능은 여전히 이를 마이그레이션 (migration) 작업처럼 취급하는 것이었습니다. 가이드를 읽고, 중단되는 변경 사항 (breaking changes)을 찾고, 코드 변경을 계획하고, 앱을 검증한 다음 머지 (merge)하는 방식 말입니다.

그것은 잘못된 시작 가정이었습니다.

유용한 작업은 마이그레이션을 구현하는 것이 아니었습니다. 유용한 작업은 이 저장소에 마이그레이션이 실제로 필요한지를 증명하는 것이었습니다.

리뷰 게이트 (review gate)는 옳았습니다

Renovate는 이 업데이트를 프론트엔드 React/Vite 메이저 업데이트로 그룹화했습니다. 저의 리뷰 정책은 패키지들을 저위험 (low-risk)과 고접촉 (high-touch) 버킷으로 분류합니다. 타입 정의 (type definition)나 린트 플러그인 (lint plugin)에 대한 패치 레벨 (patch-level) 업데이트는 자동 머지 (auto-merge)할 수 있지만, 앱을 빌드하거나 서빙하는 모든 것 (번들러 (bundler), React 플러그인)은 고접촉 (high-touch) 항목입니다.

Vite와 @vitejs/plugin-react 모두 그 고접촉 (high-touch) 범주에 속하므로, 버전 변경이 발생하면 자동 병합 (auto-merge) 대신 사람의 손을 거치게 됩니다.

풀 리퀘스트 (pull request)는 서류상으로는 심각해 보였습니다:

• Vite 8 릴리스 노트에는 명시적인 파괴적 변경 사항 (breaking changes)이 포함되어 있었습니다.
• Vite가 Rollup 중심의 의존성 구조에서 Rolldown 패키지 방향으로 이동함에 따라 락파일 (lockfile)의 변동 폭이 컸습니다.

기존의 워크플로우라면 마이그레이션 계획부터 시작했을 것입니다. 하지만 증거 우선 (evidence-first) 워크플로우는 다른 목표로 시작되었습니다:

문서화된 파괴적 변경 사항 중 이 저장소 (repository)에 실제로 적용되는 것은 무엇인가?

CI는 브랜치가 빌드된다는 것을 보여주었지만, 파괴적 변경 사항이 이 저장소와 무관하다는 것을 보여주지는 않았습니다. 저는 AI 지원 리뷰를 통해 PR을 검토했고, 아래의 4단계 체크리스트를 사용하여 결과를 감사 (audit)했습니다. 저의 업무는 모든 사실을 수동으로 다시 도출하는 것이 아니라, 증거가 병합하기에 충분한지 결정하는 것이었습니다.

구현 전 조사

체크리스트는 점점 더 구체화되는 네 가지 질문을 다룹니다. Vite 버전 업그레이드의 경우, 결과로 도출된 증거 패킷은 다음과 같았습니다:

1. 업스트림 변경 사항을 조사하십시오 (Inspect the upstream change).

두 패키지 모두 문서화된 파괴적 변경 사항 (breaking changes)을 포함하고 있었습니다. 검토 과정에서는 해당 노트를 사용하여 발생 가능한 실패 모드 (failure modes)를 명명했을 뿐, 어떤 모드가 이 저장소에 영향을 미칠지 가정하지 않았습니다. 예를 들어, Vite 8의 릴리스 노트에서는 SSR 파이프라인의 변화와 더 엄격해진 import.meta.hot 처리 방식 등을 언급했습니다.

2. 해당 변경 사항을 실제 사용 사례와 매핑하십시오 (Map those changes to actual usage).

증거 패킷은 질문의 틀을 "Vite 8에 파괴적 변경 사항이 있는가?"에서 "이 앱이 해당 변경 사항으로 인해 깨지는 인터페이스 (surfaces)를 사용하는가?"로 재구성했습니다. 이 저장소는 커스텀 SSR이 없는 일반적인 Vite React 설정을 사용하고 있었습니다.

3. 커스텀 리스크를 식별하십시오 (Identify custom risk).

패킷은 프로젝트 특유의 의미 있는 영역 하나를 지목했습니다: 스타일시트와 모듈 스크립트 태그의 순서를 재정렬하기 위해 transformIndexHtml에 후킹하는 작은 커스텀 Vite 플러그인인 cssBeforeModuleScript였습니다. 번들러가 Rollup에서 Rolldown으로 교체된다면 해당 동작이 변경될 가능성이 있었기에, 이 부분은 앱을 실제로 실행해 보기 전까지 미결 상태로 남겨두었습니다.

4. 앱을 검증하십시오 (Validate the app).

CI의 test 작업은 이미 통과(green) 상태였지만, 패킷은 커스텀 리스크 경로와 프로덕션 빌드 (production build)가 유지되는지에 대한 증거를 여전히 요구했습니다. 준비된 Vercel 프리뷰 (preview)가 그 간극을 메워주었습니다: cssBeforeModuleScript가 포함된 상태로 새로운 Vite를 통해 프로덕션 빌드를 실행했으며, 렌더링된 페이지는 스타일시트나 모듈 스크립트의 순서가 깨졌을 때 나타날 문제들을 확인할 수 있는 지점이었습니다.

그 시점에서 권장 사항이 바뀌었습니다.

패킷은 마이그레이션 작업을 찾아낸 것이 아니었습니다. 마이그레이션이 필요하지 않다는 충분한 증거를 찾아낸 것이었습니다.

마이그레이션 계획보다 증거 (Evidence over migration plans)

병합된 PR은 두 개의 파일, frontend/package.json과 package-lock.json을 변경했습니다.

소스 파일은 없었습니다. Vite 설정 재작성도 없었습니다. 컴포넌트 변경도 없었습니다. 테스트 재작성도 없었습니다. 커스텀 심 (shim)도 없었습니다.

이를 "업그레이드가 사소했다"라고 오해하기 쉽습니다. 하지만 사소하지 않았습니다. 해당 풀 리퀘스트 (pull request)는 실제 리스크 신호를 담고 있었습니다. 소스 변경 사항이 없었다는 점은, 조사를 통해 코드 변경이 필요하지 않음을 증명한 후에야 비로소 의미를 갖게 되었습니다.

구현 (Implementation)은 오직 증거가 그것을 요구할 때만 이루어져야 합니다. 인간의 역할은 "이 의존성을 마이그레이션해 주세요"에서, 패킷 (packet)이 위의 네 가지 단계를 충족하는지 감사 (auditing)하는 것으로 전환됩니다.

이것이 수동 검토 (manual review)를 어떻게 변화시켰는가

이전에는 "수동으로 검토하라"는 말이 마치 주차장처럼 느껴졌습니다. 대규모 업그레이드가 도착했지만 자동화 도구가 머지 (merge)를 거부했고, 나중에 사람이 이를 맡게 되는 식이었죠. 증거 패킷을 수동으로 조립하는 과정이 종종 검토를 지연시키는 원인이 되었습니다.

이제 저는 "수동 검토"를 증거 수집을 위한 차선 (lane)으로 취급합니다. AI는 이 차선을 실용적으로 만들어 줍니다. 패킷 조립의 상당 부분을 더 이상 키보드 앞에 앉아 한 번에 처리할 필요가 없기 때문입니다. 이것이 경제성을 변화시킨 지점입니다. 조사가 유지보수를 미루기 쉽게 만드는 비용이 많이 드는 단계가 아니게 된 것입니다. Vite 업데이트 당시, AI는 증거를 조립하는 데 도움을 주었고, 저는 그것이 마이그레이션 작업 없이 머지하기에 충분한지 감사했습니다.

저위험 패치 (low-risk patches)의 경우 질문은 단순합니다. CI가 통과했는가, 그리고 차이점 (diff)이 패키지 파일 내에 머물러 있는가? 직접적인 영향이 큰 프레임워크 업그레이드의 경우 질문은 더 풍부해집니다. 패킷이 업스트림 (upstream) 변경 사항, 리포지토리 (repo) 사용량, 커스텀 리스크 (custom risk), 그리고 실제 앱 검증 (real app validation)을 충분히 다루어, 사람이 추측에 기반한 마이그레이션 작업을 먼저 수행하지 않고도 결정할 수 있는 수준인가?

이것이 판단이나 머지 결정을 없애는 것은 아닙니다. 판단과 결정 모두를 더 앞 단계로 옮기는 것입니다. 먼저 패킷을 수집한 다음, 구현이 실제로 필요한지 감사하십시오.

다음 대규모 업그레이드 시 내가 할 일

1. 패키지를 정직하게 분류하십시오. 런타임 (Runtime) 및 프레임워크 패키지는 패치 수준의 개발 도구 업데이트보다 더 많은 증거를 요구합니다.
2. 릴리스 노트 (release notes), 리포지토리 사용량, 커스텀 리스크, 실제 앱 검증에 대해 위의 4단계 루프를 실행하십시오.
3. 소스 변경 사항이 없다는 것을 가정이 아닌 결론으로 취급하십시오. 만약 구현이 필요하지 않다면, 어떤 증거가 그것을 증명했는지 명시하십시오.

핵심 요약 (Takeaway): 조사가 실행하기에 충분히 저렴해지면, 미루는 것이 기본값이 되지 않습니다. 마이그레이션 계획을 작성하기 전에 감사를 먼저 수행하십시오.

이러한 워크플로 실험의 기반이 된 프로젝트를 확인하고 싶다면, Codenames AI를 살펴보세요.