AI로 1,400개 파일을 마이그레이션하는 6단계 전략 (claude.com)

한줄 요약

Claude Code로 대규모 코드 마이그레이션을 자동화하는 6단계 전략 — 룰북·판정기·병렬 에이전트로 수천 개 파일을 체계적으로 전환한다.

어떤 상황에서 필요한가?

대규모 코드 마이그레이션은 개발 프로젝트 중에서도 손에 꼽히게 까다로운 작업이다. 파일 수가 수백 개를 넘어가면 수작업은 현실적으로 불가능하고, 단순 스크립트로는 언어 간 의미 차이를 처리하지 못한다.

Anthropic은 실제 프로젝트에서 이 문제를 Claude Code로 풀었다. 한 사례는 Zig에서 Rust로, 다른 사례는 Python에서 TypeScript로의 전환이었는데, 두 프로젝트 모두 단순 번역이 아닌 언어 패러다임 자체의 차이를 극복해야 했다. 가령 Zig의 수동 메모리 관리를 Rust의 소유권 시스템으로, Python의 암묵적 덕 타이핑을 TypeScript의 명시적 인터페이스 계약으로 바꾸는 작업이다.

이 과정에서 정리된 방법론은 특정 언어 쌍에 국한되지 않는다. 레거시 코드베이스를 현대화하거나, 외주로 넘어온 구형 시스템을 전환해야 할 때도 동일한 구조로 적용할 수 있다.

핵심 구현 방법

전제 조건: 판정기(Judge)를 먼저 만들어라

마이그레이션을 시작하기 전에 반드시 해야 할 일이 있다. 원본 코드와 전환된 코드를 동일한 기준으로 평가할 수 있는 판정기를 구축하는 것이다. 판정기 없이는 "언제 끝났는지"를 알 수 없다.

핵심은 테스트가 특정 언어의 내부 구현에 의존하지 않도록 만드는 것이다. 기존 테스트 스위트를 Claude로 분류해서 외부 호출로 표현 가능한 테스트와 내부 의존성이 있는 테스트를 분리하고, 전자를 양쪽 코드베이스에 모두 실행 가능한 형태로 재작성한다. 판정기가 제대로 작동하는지 검증하는 방법도 명확하다. 정상 코드에서 통과하고, 의도적으로 망가뜨린 코드에서 실패해야 한다. 실패를 잡지 못하는 판정기는 판정기가 아니다.

1단계 — 룰북, 의존성 맵, 갭 인벤토리 작성

세 가지 산출물을 이 순서대로 만든다.

룰북은 마이그레이션의 헌법이다. 구조를 그대로 유지하는 전환이라면 타입·관용구 변환 대조표 형태가 되고, 설계 자체를 바꾸는 전환이라면 설계 문서 형태가 된다. 룰북이 먼저여야 하는 이유는 다음에 만들 갭 인벤토리가 "룰북의 기본 규칙이 커버하지 못하는 영역"으로 정의되기 때문이다.

의존성 맵은 파일 간 참조 관계를 그래프로 정리한 것이다. 병렬로 마이그레이션을 진행할 때 어떤 파일을 먼저 전환해야 하고, 어떤 파일들을 한 묶음으로 처리해야 하는지를 결정한다. 레거시 코드베이스나 C/C++, Python처럼 명시적 매니페스트가 없는 언어는 에이전트를 배포해서 이 의존성을 탐색하고 스크립트로 뽑아낸다.

갭 인벤토리는 언어 간 암묵적 지식의 차이를 목록화한 것이다. Python은 함수가 받는 객체의 형태를 선언하지 않아도 되지만 TypeScript는 반드시 인터페이스를 명시해야 한다. 이런 차이들을 미리 정리해두지 않으면 전환 과정에서 같은 문제가 반복해서 터진다.

2단계 — 규칙을 스트레스 테스트하라

전체 파일에 적용하기 전에 소규모 시험 운항을 한다. 에이전트 하나는 룰북대로 세 파일을 전환하고, 다른 에이전트 하나는 "시니어 Rust 엔지니어처럼" 동일한 세 파일을 전환한다. 두 결과의 diff를 세 번째 에이전트가 분석해서 새로운 전환 규칙을 도출한다.

실제 사례에서 이 단계에서 치명적인 문제 두 개를 잡아냈다. 만약 이를 건너뛰고 전체 파일에 적용했다면 1,448개 파일 전체에 같은 오류가 퍼졌을 것이다.

주의할 점이 있다. 이 방식은 구조를 그대로 유지하는 마이그레이션에서만 유효하다. 설계 자체를 바꾸는 경우라면 설계 문서를 적대적 리뷰어로 공격하고, 전체 흐름을 한 번 disposable run으로 실행해서 검증하는 방식을 써야 한다. 어떤 경우든 이 단계에서 나온 전환 파일은 버린다. 목적은 규칙을 다듬는 것이지 진행 상황을 쌓는 것이 아니다.

3단계 이후 — 구현·리뷰·수정 루프

나머지 단계는 동일한 멀티 에이전트 루프 구조로 실행된다. 구현하고, 리뷰하고, 수정하는 사이클이다. 각 단계마다 검토 관문(gate)을 두어 다음 단계로 넘어가기 전에 품질을 확인한다.

한 프로젝트에서는 전체 마이그레이션을 처음부터 끝까지 실행하고, 결과를 버리고, 룰북과 워크플로우를 수정한 뒤 다시 처음부터 실행하는 방식을 세 번 반복했다. 점진적으로 쌓는 방식이 아니라 전체를 반복 실행하면서 규칙을 정제하는 방식이다.

실전에서 주의할 점

이 방법론을 실제로 적용할 때 가장 흔히 놓치는 지점이 있다.

첫째, 판정기 검증을 생략하는 경우다. 테스트가 통과한다고 해서 판정기가 올바른 게 아니다. 반드시 의도적으로 깨진 코드를 넣어서 판정기가 실패를 잡는지 확인해야 한다.

둘째, 2단계의 테스트 파일을 본 마이그레이션에 재사용하려는 유혹이다. 스트레스 테스트에서 나온 파일은 버리는 게 원칙이다. 규칙이 바뀌었기 때문에 그 파일들은 이미 구버전 규칙의 산물이다.

셋째, 갭 인벤토리를 사후에만 만드는 경우다. 전환 전에 미리 만들고, 전환 후에 감사로 보완하는 두 가지를 모두 하는 게 안전하다. 언어 간 패러다임 차이는 예상보다 훨씬 많은 곳에서 튀어나온다.

개발 외주나 레거시 시스템 전환 프로젝트를 맡고 있다면, 이 구조를 도입하기 전에 판정기 설계에 충분한 시간을 투자하는 게 전체 공수를 줄이는 가장 확실한 방법이다.