Claude Code가 Bun을 Rust로 재작성한 방법: 대규모 코드 마이그레이션 6단계 가이드

서론

과거에는 대규모 프로그래밍 언어 마이그레이션이 엔지니어링 팀이 몇 년씩 미루는 프로젝트 유형이었습니다. 이러한 마이그레이션은 비용이 많이 들고 파괴적이며 위험이 큽니다. 한 회사가 두 가지 구현 버전을 동시에 유지 관리하는 데 여러 분기를 소비하고, 결국 원본과 동작이 일치하지 않는 대체품을 얻게 되는 경우도 있었습니다.

Claude Code가 이러한 상황을 바꾸고 있습니다.

Anthropic은 최근 AI 에이전트를 활용한 대규모 코드 마이그레이션 프로세스를 공개했습니다. 가장 주목할 만한 사례는 Bun의 창시자 Jarred Sumner가 Bun의 핵심을 Zig에서 Rust로 마이그레이션한 것입니다. 2주도 채 되지 않아 Claude Code 워크플로우가 100만 줄 이상의 코드를 생성했고, Bun의 기존 테스트 스위트는 병합 전에 이미 CI(지속적 통합) 테스트를 통과했습니다.

이 프로젝트는 모델에게 "Bun을 Rust로 재작성하라"고 지시하고 완벽한 답변을 기다리는 방식으로 완료된 것이 아닙니다. 규칙 매뉴얼, 의존성 매핑, 기계적 큐, 적대적 리뷰어, 컴파일러, 스모크 테스트, 동작 일관성 검사 등 세심하게 설계된 시스템에 의존했습니다.

핵심 교훈은 간단합니다. 이러한 규모의 마이그레이션에서 개발자는 개별 파일을 수정하는 데 대부분의 시간을 소비해서는 안 됩니다. 이 파일들을 생성, 검토, 검증하는 프로세스를 개선해야 합니다.

Bun 창시자, AI를 활용해 100만 줄 이상의 코드 재작성

Jarred Sumner는 원래 Zig로 Bun을 구축했습니다. 이 언어는 독립 개발자가 대규모 시스템 언어 생태계의 모든 복잡성을 감수하지 않고도 낮은 수준의 제어권과 C 언어와 유사한 성능을 얻을 수 있게 해줍니다.

이러한 선택은 Bun이 초기에 빠르게 성장하는 데 도움이 되었습니다. Sumner는 오클랜드의 작은 아파트에서 약 1년 만에 첫 번째 버전을 작성했다고 밝혔으며, 당시에는 현대적인 코딩 모델이 없었습니다.

2026년까지 Bun은 널리 사용되는 JavaScript 및 TypeScript 런타임, 패키지 관리자, 테스트 러너, 번들러가 되었습니다. 이 명령줄 도구는 월 수천만 건의 다운로드를 기록하고 있으며, Claude Code를 포함한 여러 제품이 Bun에 크게 의존하고 있습니다.

성장은 또한 오래된 엔지니어링 트레이드오프를 무시하기 어렵게 만들었습니다.

Bun은 가비지 컬렉션 JavaScript 엔진과 수동으로 관리되는 네이티브 메모리를 결합합니다. Zig에서 개발자는 할당, 정리, 오류 경로, 객체 수명 주기를 명시적으로 추론해야 합니다. Bun 팀은 sanitizer, 퍼징, 보안 검사 빌드, 메모리 누수 테스트에 많은 노력을 기울였지만, use-after-free 오류, 이중 해제, 누수, 수명 주기 오류는 여전히 발생했습니다.

Rust는 다른 기반을 제공합니다. 소유권 시스템, 대여 검사기, 자동 정리를 통해 많은 런타임 메모리 문제를 컴파일 타임 오류로 전환할 수 있습니다.

역사적으로 이러한 이점만으로 완전한 재작성을 정당화하기는 어려웠습니다. Bun은 수십만 줄의 Zig 코드와 방대한 네이티브 통합을 포함하고 있습니다. 전통적인 재작성은 소규모 엔지니어링 팀이 1년 이상 소비하면서 기능 개발과 보안 수정을 지연시킬 수 있습니다.

Claude Code는 완전한 기계적 마이그레이션을 실현 가능하게 만들었습니다.

Zig에서 Rust로 11일 만에 전환

Sumner는 Claude Fable 5의 사전 출시 버전과 Claude Code 동적 워크플로우를 사용하여 마이그레이션을 수행했습니다.

주요 작성 및 검토

이 프로세스는 11일 동안 지속적으로 실행되었습니다. 약 50개의 동적 워크플로우가 다양한 단계를 처리했으며, 여기에는 다음이 포함됩니다:

• Zig에서 Rust로의 포팅 가이드 생성
• 메모리 수명 주기 매핑
• .zig 파일을 .rs 파일로 변환
• 생성된 각 파일 검토
• 컴파일러 오류 수정
• 개별 Bun 명령 복원
• 전체 테스트 스위트 실행
• 생성된 코드 리팩토링 및 정리

최대 처리량에서 워크플로우는 분당 약 1300줄의 코드를 생성했습니다. 생성된 각 코드 단위는 두 명의 독립적인 적대적 리뷰어 검사를 거친 후, 수정자가 확인된 변경 사항을 적용했습니다.

최종 풀 리퀘스트는 2000개 이상의 변경 파일에 100만 줄 이상의 코드를 추가했습니다.

병합 전에 Bun의 기존 테스트 스위트가 CI에서 통과되었습니다. 병합 후 19개의 회귀 문제가 발생했으며, Anthropic은 이 문제들이 모두 수정되었다고 보고했습니다. Rust 포팅 버전은 2026년 6월 Claude Code와 함께 출시되었습니다.

이 결과는 처음 생성된 100만 줄의 코드가 올바르다는 것을 증명하지는 않습니다. Sumner는 초기 번역 출력이 실행 불가능하다는 점을 분명히 밝혔습니다. 성공의 핵심은 피드백 시스템에 있었으며, 이 시스템은 실행 불가능한 출력을 점진적으로 컴파일되고 테스트된 동작 호환 코드로 변환했습니다.

마이그레이션 비용 약 16만 5천 달러(API 가격 기준)

Bun의 마이그레이션은 약 다음과 같은 리소스를 소비했습니다:

• 59억 개의 캐시되지 않은 입력 토큰
• 6억 9천만 개의 출력 토큰
• API 가격 기준 약 16만 5천 달러

이는 적지 않은 금액이지만, 여러 명의 풀타임 엔지니어가 수년간 소요되는 전통적인 마이그레이션 비용보다는 여전히 훨씬 낮습니다.

Anthropic은 이전에 100만 줄 규모의 마이그레이션에는 4년이 걸리고 약 300만~400만 달러의 엔지니어링 리소스가 소요되었을 것으로 추정합니다. AI는 마이그레이션이 비용을 정당화하기 위해 생존 위기를 겪을 필요가 없도록 비즈니스 로직을 변화시켰습니다.

지속적인 메모리 오류, 노후화된 언어 생태계, 비용이 많이 드는 빌드 프로세스, 반복적인 유지 보수 병목 현상 등은 이제 마이그레이션 평가를 충분히 고려할 만한 요인이 되었습니다.

하지만 비교는 신중하게 이루어져야 합니다. 토큰 비용이 프로젝트 총비용은 아닙니다. 팀은 여전히 인력 계획, 인프라, 테스트, 코드 리뷰, 보안 작업, 병합 후 유지 보수가 필요합니다.

Bun이 Zig에서 Rust로 마이그레이션한 이유

이번 마이그레이션은 주로 원시 속도보다는 안정성에 중점을 두었습니다.

Bun은 이미 Zig에서 뛰어난 성능을 보여주고 있었습니다. 문제는 수동으로 관리되는 네이티브 메모리와 가비지 컬렉션 JavaScript 런타임을 안전하게 조정하는 방법이었습니다.

일반적인 오류 유형은 다음과 같습니다:

• use-after-free 오류
• 이중 해제 오류
• 예외 경로에서의 메모리 누수
• 재진입 콜백으로 인한 잘못된 포인터
• 건너뛰어진 정리 코드
• 일관되게 적용하기 어려운 수명 주기 가정

안전한 Rust에서는 이러한 많은 오류가 컴파일을 통과할 수 없습니다. 값은 명확한 소유권을 가지며, 리소스 정리는 객체 수명 주기와 바인딩되고, 컴파일러는 프로그램이 실행되기 전에 참조를 검사합니다.

이번 마이그레이션의 목표는 Bun의 기존 아키텍처, 데이터 구조, 동작, 성능을 유지하는 것이었습니다. 완전한 재설계보다는 기계적 포팅에 의도적으로 가깝게 접근했습니다.

이 결정은 매우 중요했습니다. 시스템을 동시에 재설계하고 언어를 변경하면 동작 비교가 매우 어려워집니다.

두 번째 사례: 16만 5천 줄의 Python 코드를 TypeScript로 전환

Jarred Sumner만이 Claude Code를 사용하여 대규모 마이그레이션을 수행한 Anthropic 엔지니어는 아닙니다.

Anthropic Labs 공동 책임자이자 Instagram 공동 창업자인 Mike Krieger는 주말 동안 내부 Python 코드베이스를 약 16만 5천 줄의 TypeScript 코드로 마이그레이션했습니다.

주요 마이그레이션 프로세스는 약 2700만 개의 토큰을 소비했으며, 다음을 포함했습니다:

• 수백 개의 지능형 에이전트
• 8단계 게이트
• 3라운드의 적대적 리뷰
• 최종 일관성 검사
• 명령별 Python 버전과의 출력 비교
• AI 생성 엔드 투 엔드 테스트

원래 도구는 단일 바이너리 파일로 제공되어야 했습니다. Python 툴체인을 사용할 때 각 플랫폼 컴파일에 약 8분이 소요되었고, 전체 빌드 매트릭스로 인해 각 릴리스가 약 30분 지연되었습니다.

TypeScript 마이그레이션 완료 후:

• 컴파일 시간이 약 2초로 단축
• 바이너리 시작 속도가 약 6배 향상
• 독립적인 배포 파이프라인 제거 가능

Krieger는 기존의 포괄적인 교차 언어 테스트 스위트에 의존하지 않았습니다. 대신 Claude를

일곱 가지 실제 시나리오를 대상으로 한 일관성 테스트 프레임워크를 구축한 뒤, 기존 구현과 새로운 구현의 출력 결과를 비교했습니다.

Claude는 또한 추가적인 엔드투엔드 테스트를 설계하고, 이를 나흘 연속 밤새 실행하며 실패 사례를 수정한 뒤 이 과정을 반복했습니다. 이를 통해 원래 시나리오에서는 예상하지 못한 미묘한 동작 차이를 발견할 수 있었습니다.

왜 대규모 코드 마이그레이션에 AI 에이전트가 적합한가

대규모 마이그레이션이 부담스러운 이유는 방대한 양의 반복적인 변경 사항이 포함되기 때문입니다. 바로 이러한 특성 때문에 에이전트 기반 워크플로우에 적합합니다.

작업의 병렬화 가능

대규모 코드베이스는 일반적으로 파일, 패키지, 크레이트, 모듈 또는 의존성 그룹으로 나눌 수 있습니다. 독립적인 에이전트는 서로 의존하지 않는 단위를 동시에 처리할 수 있습니다.

의존성 그래프는 어떤 단위를 병렬로 진행할 수 있고 어떤 단위가 기다려야 하는지를 결정합니다.

기존 코드가 곧 명세

원래 구현에는 필요한 동작, 경계 조건, 데이터 구조 및 통합 세부 사항이 이미 포함되어 있습니다.

모델이 새로운 제품 기능을 창조할 필요는 없습니다. 그 임무는 새 언어나 프레임워크에서 기존 시스템을 유지하는 것입니다.

테스트가 객관적 평가 기준 제공

에이전트가 자신의 출력을 기계적으로 평가할 수 있을 때 더 효과적으로 작동합니다.

컴파일러, 테스트 스위트, 출력 차이 비교, 벤치마크 또는 일관성 테스트 프레임워크는 시스템에 구체적인 신호를 제공합니다. 에이전트는 이를 바탕으로 지속적으로 개선할 수 있으며, 매 중간 시도마다 사람이 평가할 필요가 없습니다.

작업 큐가 자동 생성됨

컴파일 오류는 다음 작업이 되고, 실패한 테스트는 다음 작업이 되며, 프로그램 충돌 역시 다음 작업이 됩니다.

이를 통해 대규모 마이그레이션 작업이 지속적으로 줄어드는 큐로 변환됩니다.

반복 실패가 규칙 개선을 촉진

검토자가 여러 파일에서 동일한 문제를 발견했을 때, 최선의 해결책은 각 파일을 하나하나 수동으로 고치는 것이 아닙니다.

규칙 매뉴얼을 업데이트하고 영향을 받은 배치를 다시 생성해야 합니다. 이렇게 하면 이후 작업에서 동일한 오류가 다시 발생하는 것을 방지할 수 있습니다.

핵심 원칙: 개별 파일이 아닌 프로세스를 수정하라

Anthropic 프로세스에서 가장 중요한 개념은 생성된 코드를 시스템 출력의 결과물로 보는 것입니다.

200개의 번역된 파일에 동일한 소유권 오류가 있다고 가정해 보겠습니다. 이러한 파일을 수동으로 수정하면 눈에 보이는 오류는 해결할 수 있지만, 워크플로우는 여전히 같은 오류를 다시 생성할 수 있습니다.

더 효과적인 방법은 다음과 같습니다.

1. 반복적인 실패 패턴을 식별합니다.
2. 어떤 마이그레이션 규칙이 원인인지 파악합니다.
3. 규칙 매뉴얼을 업데이트합니다.
4. 영향을 받은 파일만 다시 생성합니다.
5. 검토 및 검증 사이클을 다시 실행합니다.

코드가 개선되는 이유는 생산 프로세스가 최적화되었기 때문입니다.

이는 일반적인 소프트웨어 공학과 유사합니다. 반복적으로 발생하는 생산 결함은 또 다른 고립된 패치를 적용하는 것이 아니라, 테스트, 타입 규칙, 정적 검사 또는 프로세스를 개선하도록 유도해야 합니다.

전제 조건: 신뢰할 수 있는 평가 메커니즘 구축

대규모 마이그레이션을 시작하기 전에 팀이 새 구현의 정확성을 어떻게 입증할지 정의해야 합니다.

평가 메커니즘이 없으면 신뢰할 수 있는 완료 조건을 정의할 수 없습니다.

평가 메커니즘은 원래 구현과 대상 구현을 동등한 조건에서 평가해야 합니다. 기존 테스트는 비공개 함수나 언어별 내부 메커니즘에 의존할 수 있으며, 이러한 요소는 이식 과정에서 사라집니다.

Anthropic은 세 가지 준비 작업을 권장합니다.

1. 기존 테스트를 분류합니다. 공개 동작을 테스트하는 것과 내부 구현에 의존하는 테스트를 분리합니다.
2. 이식 가능성을 위해 테스트를 다시 작성합니다. 외부에서 관찰 가능한 동작을 두 시스템에서 모두 실행할 수 있는 어설션으로 변환합니다.
3. 평가 메커니즘을 검증합니다. 원래 구현이 테스트를 통과하는지 확인한 후, 의도적으로 프로그램을 손상시켜 평가 메커니즘이 실패하는지 확인합니다.

알려진 결함을 감지하지 못하는 테스트 스위트는 마이그레이션 평가 메커니즘으로 사용할 수 없습니다.

Bun은 중요한 이점이 있습니다: 대부분의 테스트 스위트가 Zig가 아닌 TypeScript로 작성되어 있어, 동일한 테스트로 Rust 구현을 테스트할 수 있습니다.

이러한 이점이 없는 프로젝트의 경우, 피어 테스트 도구를 사용하여 두 버전 간의 실제 입력과 출력을 비교할 수 있습니다.

Anthropic의 6단계 코드 마이그레이션 프레임워크

Anthropic은 이러한 프로젝트에서 얻은 경험을 아래 6단계 프로세스로 정리했습니다.

이미지는 Anthropic이 제안한 6단계 코드 마이그레이션 프레임워크를 보여줍니다. 첫 번째 단계는 지도와 규칙 생성으로, 규칙서 작성자, 의존성 매퍼, 갭 인벤토리 등이 포함됩니다. 두 번째 단계는 규칙 스트레스 테스트로, 이중 번역자, 차이 검사기 등이 있습니다. 세 번째 단계는 모든 내용 번역으로, 구현자, 검토자 등이 포함됩니다. 네 번째 단계는 컴파일로, 빌드 조사, 병렬 수정자 등이 있습니다. 다섯 번째 단계는 실행으로, 스모크 테스트, 수정자 등이 포함됩니다. 여섯 번째 단계는 동작 일치로, 빌드 데몬, 수정자 등이 있습니다. 하단에는 공유 문서, 실행 인프라 등이 나열되어 있습니다. 이 그림은 위에서 설명한 Anthropic의 6단계 코드 마이그레이션 프레임워크를 시각화한 것입니다.

1단계: 규칙 매뉴얼, 의존성 그래프 및 갭 인벤토리 생성

첫 번째 단계에서는 이후 모든 에이전트가 따를 공유 문서를 만듭니다.

규칙 매뉴얼 구축

규칙 매뉴얼은 소스 언어의 개념이 대상 언어에 어떻게 매핑되는지 정의합니다.

구조를 유지하는 마이그레이션의 경우 규칙 매뉴얼에는 다음이 포함될 수 있습니다.

• 타입 매핑
• 오류 처리

규칙 관례

• 명명 규칙
• 메모리 및 소유권 규칙
• 표준 라이브러리 대체 사양
• 동시성 패턴
• 파일 및 모듈 레이아웃
• 외부 함수 인터페이스 규칙
• 수동 검토가 필요한 패턴

리팩토링 설계에서 규칙 매뉴얼은 아키텍처 문서에 더 가깝습니다.

Jarred Sumner는 Claude와의 대화 및 수동 검토를 통해 Bun의 이식 가이드라인을 수립했습니다. 최종 결과물은 수백 줄에 달했습니다.

의존성 매핑 생성

저장소는 의존성 순서에 따라 분할되어야 합니다.

결정적 스크립트는 임포트, 매니페스트, 빌드 파일 및 심볼 관계를 검사하여 의존성 매핑을 생성할 수 있습니다. 이 결과는 오케스트레이터가 어떤 파일을 독립적으로 변환할 수 있고 어떤 파일을 함께 처리해야 하는지 결정하는 데 도움이 됩니다.

갭 인벤토리 작성

소스 언어와 대상 언어는 서로 다른 규칙을 따릅니다.

Zig에서 Rust로의 마이그레이션에서 메모리 소유권이 주요 차이점입니다. Python에서 TypeScript로의 마이그레이션에서 암시적 객체 형태와 인터페이스를 명시적 계약으로 변환해야 합니다.

갭 인벤토리는 단순한 번역만으로 해결할 수 없는 부분을 기록하며, 구체적으로 다음을 포함합니다.

• 숨겨진 소스 언어 가정
• 누락된 대상 언어 추상화
• 명시화해야 하는 런타임 동작
• 지원되지 않는 라이브러리
• 플랫폼별 코드
• 안전하지 않은 경계
• 재설계 또는 수동 결정이 필요한 영역

규칙 매뉴얼은 갭 인벤토리보다 먼저 작성해야 합니다. 갭 인벤토리는 일반 규칙으로 처리할 수 없는 내용에 부분적으로 의존하기 때문입니다.

2단계: 규칙 스트레스 테스트

수천 개의 파일을 바로 번역하지 마십시오.

먼저 소수의 복잡하고 대표적인 파일을 선택하여 작은 규모의 일회성 시험 실행을 진행합니다. 목표는 규칙 결함이 전체 저장소로 확산되기 전에 문제를 발견하는 것입니다.

Bun의 시험 실행에서:

1. 첫 번째 에이전트가 규칙 매뉴얼에 따라 세 개의 파일을 번역합니다.
2. 다른 에이전트가 시니어 Rust 엔지니어의 관점에서 동일한 파일을 번역합니다.
3. 비교 에이전트가 차이점을 확인합니다.
4. 검토자가 누락되거나 잘못된 마이그레이션 규칙을 표시합니다.
5. 번역된 파일은 폐기됩니다.

이 단계의 산출물은 최적화된 규칙 매뉴얼이며, 프로덕션 코드가 아닙니다.

리팩토링 마이그레이션의 경우, 이에 상응하는 테스트는 적대적 검토자가 설계 문서를 공격한 후 일회성 엔드투엔드 실행을 수행하는 것입니다.

3단계: 전체 번역

규칙이 시험 실행을 통해 검증되면 저장소는 병렬 큐를 통해 처리됩니다.

일반적인 단위 구성은 다음과 같습니다.

• 한 명의 구현자
• 두 명의 독립적인 적대적 검토자
• 한 명의 수정자
• 기계적 큐
• 공유 규칙 매뉴얼
• 공유 갭 인벤토리

큐는 중단된 지점에서 재개할 수 있어야 합니다. 단일 에이전트의 메모리에 의존하지 않고 파일 검사 또는 아티팩트 기록을 통해 작업 완료 상태를 판단할 수 있어야 합니다.

에이전트는 항상 일관되게 완료되지 않은 작업을 표시해야 합니다. 예:

TODO(이식): 이 부분을 안전하게 번역할 수 없는 이유 설명

모든 단위에 가장 비싼 모델을 사용할 필요는 없습니다. 낮은 사양의 모델은 대량 번역을 처리하고, 더 강력한 모델은 검토자, 아키텍처 결정 및 규칙 수정에 할당할 수 있습니다.

4단계: 컴파일

첫 번째 전체 빌드는 컴파일러 오류를 구조화된 작업 큐로 변환합니다.

빌드 비용에 따라 컴파일러는 각 에이전트 루프 내부에서 실행되거나 별도의 오케스트레이터를 통해 실행될 수 있습니다.

Bun 프로젝트의 경우 전체 워크스페이스를 컴파일하는 비용이 높기 때문에, 파일 번역 과정에서 Claude 에이전트는 임의로 cargo 명령을 실행하지 않습니다. 대신 다음과 같은 프로세스를 따릅니다.

1. 오케스트레이터가 컴파일러를 실행합니다.
2. 오류 메시지가 공유 목록에 기록됩니다.
3. 모듈 또는 근본 원인별로 목록을 분류합니다.
4. 수정 에이전트가 각 오류 그룹을 병렬로 처리합니다.
5. 검토자가 수정 결과를 확인합니다.
6. 오케스트레이터가 프로젝트를 다시 빌드합니다.

이렇게 하면 수십 개의 에이전트가 동시에 동일한 고비용 빌드를 시작하는 것을 방지할 수 있습니다.

시스템 차원의 컴파일러 오류는 규칙을 업데이트해야 합니다. 예를 들어, 대상 언어는 소스 컴파일러가 지연 로딩 방식으로 허용하는 순환 종속성을 거부할 수 있습니다. 이는 단순히 고립된 파일 오류의 집합이 아닌 프로세스 수준의 문제입니다.

5단계: 프로그램 실행

컴파일 성공은 대상 언어가 코드를 수용할 수 있음을 증명할 뿐입니다.

다음 단계에서는 기본 실행과 스모크 테스트를 통해 충돌, 초기화 실패, 리소스 누락, 잘못된 가정, 통합 실패를 발견합니다.

실패 사례는 여전히 원인별로 분류해야 합니다.

40개의 스모크 테스트가 동일한 잘못된 초기화 패턴으로 인해 실패한다면, 40개의 개별 수정 작업을 할당하는 대신 마이그레이션 규칙을 수정하고 영향을 받는 코드를 다시 생성해야 합니다.

6단계: 원래 동작과 일치

최종 단계는 동작 일관성입니다.

두 코드베이스에서 휴대용 테스트 스위트, 일관성 검증 도구, 출력 비교 및 관련 벤치마크를 동시에 실행합니다.

각 실패 사례에 대해:

1. 수정 에이전트에 실패 증거와 두 가지 구현 방안을 제공합니다.
2. 수정 에이전트가 동작 차이를 식별하도록 요청합니다.
3. 적대적 검토자가 제안된 수정 사항을 검사합니다.
4. 단일 빌드 프로세스를 통해 고비용 빌드를 일괄 처리합니다.
5. 영향을 받는 테스트를 다시 실행합니다.
6. 반복되는 실패를 규칙 변경으로 승격합니다.

프로젝트가 의도적으로 동작 변경을 목표로 하지 않는 한, 원래 코드베이스는 항상 사실상의 기준입니다.

테스트 스위트가 없다고 해서 이 단계를 건너뛸 수는 없습니다. 팀은 Claude를 활용하여 실제 시나리오를 기반으로 외부 일관성 검증 도구를 만들고, 의도적으로 손상시킨 동작을 통해 검증 도구의 유효성을 확인할 수 있습니다.

Anthropic 마이그레이션 툴킷 빠른 시작

Anthropic은 마이그레이션 프로세스를 기반으로 한 일반 프롬프트, 템플릿 및 스크립트가 포함된 공개 시작 툴킷을 출시했습니다.

이 저장소는 완전히 관리되는 마이그레이션 제품이 아닌 참고 자료입니다. 프롬프트는 리팩터링 템플릿으로, Bun 프로젝트의 정확한 프로세스를 기록한 것은 아닙니다.

1. Claude Code 설치

macOS 또는 Linux 시스템:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell 시스템:

irm https://claude.ai/install.ps1 | iex

원격 설치 스크립트를 실행하기 전에 스크립트 내용과 조직의 보안 정책을 먼저 검토하세요.

2. 마이그레이션 툴킷 클론

마이그레이션할 저장소에서 실행:

git clone https://github.com/anthropics/code-migration-kit-with-claude-code.git ./migration-kit

3. 마이그레이션 스킬 추가

이 선택적 단계는 마이그레이션 스킬을 로컬 Claude Code 스킬 디렉토리에 복사합니다:

cp -r migration-kit/skill ~/.claude/skills/code-migration

설명에 따라 설치된 SKILL.md의 툴킷 경로를 업데이트하세요.

저장소.

4. 실행 가능성 평가 실행

먼저 툴킷의 읽기 전용 실행 가능성 프롬프트를 사용합니다:

prompts/00-feasibility.md

결과는 세 가지 질문에 답해야 합니다:

• 이 프로젝트를 마이그레이션해야 합니까?
• 마이그레이션은 구조를 유지합니까, 아니면 재설계합니까?
• 원래 구현과 대상 구현이 공정하게 평가될 수 있습니까?

"마이그레이션하지 않음"은 유효한 결과입니다.

5. 평가 도구 및 보안 규칙 준비

번역을 시작하기 전에:

• 언어 간 평가 도구를 구축하거나 검증합니다.
• 권장 Claude 설정을 대상 저장소에 복사합니다.
• 적절한 경우 파괴적이거나 고비용 명령을 금지합니다.
• 소스 저장소에 복구 가능한 백업이 있는지 확인합니다.
• 격리된 브랜치, 제어된 작업 트리 및 최소 권한 자격 증명을 사용합니다.

그런 다음 대규모 번역으로 바로 건너뛰지 말고 마이그레이션 프롬프트를 순서대로 실행합니다.

Bun 초기 시도에서 발생한 문제

Bun의 마이그레이션은 처음부터 순조롭지 않았습니다.

많은 에이전트가 하나의 저장소에서 작업을 시작하면 Git 작업이 서로 간섭했습니다. 한 에이전트가 git stash를 실행하고, 다른 에이전트가 git stash pop을 사용했으며, 또 다른 에이전트가 작업 트리를 재설정했습니다.

Sumner는 에이전트가 파괴적인 Git 명령을 자유롭게 실행할 수 없도록 워크플로를 변경했습니다. 이후 작업을 4개의 워크플로 분할로 나누고, 각 분할이 독립적인 작업 트리를 사용하여 여러 에이전트를 조정했습니다.

이 예시는 핵심 사항을 강조합니다: 에이전트 권한은 워크플로 설계와 일치해야 합니다.

광범위한 셸 액세스 권한을 가진 코딩 에이전트는 다음과 같은 행위를 할 수 있습니다:

• 작업을 삭제하거나 덮어씀
• 커밋되지 않은 변경 사항을 재설정
• 고비용 빌드를 반복적으로 트리거
• 관련 없는 파일을 수정
• 명령어나 로그를 통해 기밀을 유출
• 다른 에이전트를 방해

오케스트레이션 계층은 명령을 제한하고, 파일 소유권을 정의하며, 고비용 작업을 직렬화하고, 복구를 쉽게 만들어야 합니다.

AI 지원 코드 마이그레이션의 모범 사례

Anthropic이 발표한 교훈은 몇 가지 실용적인 규칙으로 요약할 수 있습니다.

일반 가이드를 맹목적으로 따르지 마십시오

모든 코드베이스는 빌드 시스템, 테스트 커버리지, 런타임 동작, 배포 제약 조건 및 위험 감수 능력이 다릅니다.

6단계 프레임워크를 출발점으로 삼은 다음, Claude가 실제 저장소에 맞게 조정하도록 하세요.

개별 실패가 아닌 패턴에 주목하세요

수정 에이전트는 개별 실패를 처리할 수 있습니다. 인간의 주의는 반복되는 패턴, 누락된 규칙, 안전하지 않은 가정 및 아키텍처 문제를 식별할 때 더 가치가 있습니다.

검토를 적대적으로 만드세요

구현 에이전트가 유일한 검토자가 되어서는 안 됩니다.

검토자에게 독립적인 컨텍스트를 제공하고 생성된 코드가 잘못되었다고 가정하도록 지시하세요. 그들의 임무는 코드가 실패하거나, 벗어나거나, 규칙을 위반하는 이유를 찾는 것입니다.

검증을 기계화하세요

컴파일러, 테스트, 린터, 출력 차이, 벤치마크 및 결정적 스크립트를 평가 도구로 사용하세요.

주관적인 "맞아 보이는" 검토는 수백만 줄의 변경을 안전하게 검증할 수 없습니다.

다른 역할에 다른 모델을 사용하세요

대용량 번역 작업은 더 작거나 저렴한 모델에 맡길 수 있습니다. 가장 강력한 모델은 규칙 생성, 아키텍처, 모호한 실패 및 검토에 사용해야 합니다.

인력을 조기에 투입하세요

가장 가치 있는 인력 작업은 대규모 생성 전에 완료되어야 합니다:

비즈니스 사례 정의

• 검토 메커니즘 구축
• 규칙 매뉴얼 작성
• 종속성 매핑
• 파일럿 프로젝트 감사
• 권한 및 경계 설정

이러한 기본 사항이 견고하게 자리잡으면 나머지 작업의 대부분은 기계적인 큐 작업이 됩니다.

큐의 복구 가능성을 유지하세요

며칠 동안 실행되어야 하는 마이그레이션 작업은 충돌, 재시작, 모델 오류 및 인프라 중단과 같은 돌발 상황을 견딜 수 있어야 합니다.

완료 상태는 단일 긴 대화가 아닌 디스크의 지속형 아티팩트, 커밋 기록, 테스트 결과 및 큐 상태를 기반으로 판단해야 합니다.

Bun 마이그레이션 후 성과

Anthropic은 Rust로 작성된 Bun 코드가 프로덕션 환경에서 사용 중이라고 보고했습니다.

이 마이그레이션이 모든 트레이드오프를 제거하지는 않았습니다. 약 4%의 Rust 코드가 여전히 unsafe 블록에 존재하며, 주로 C 및 C++ 경계의 작은 포인터 연산에 집중되어 있습니다.

그러나 새로운 구현은 상당한 개선을 가져왔습니다:

• 감지 가능한 메모리 누수 수정
• 특정 반복 빌드 벤치마크에서 메모리 사용량이 6,745MB에서 609MB로 감소
• Linux 및 Windows 플랫폼에서 바이너리 크기 19% 축소
• 언어 간 최적화로 특정 워크로드 성능 약 2~5% 향상

이러한 결과는 마이그레이션의 의미를 잘 보여줍니다. 목표는 대량의 AI 작성 코드를 생성하는 것이 아니라, 원래 동작을 유지하면서 더 안전하고, 더 작고, 유지 관리하기 쉬운 시스템을 구축하는 것입니다.

AI 마이그레이션이 적합한 시나리오

다음 조건이 충족될 때 대규모 마이그레이션은 에이전트 워크플로에 적합합니다:

• 원래 코드베이스를 완전한 사양으로 사용할 수 있음
• 동작을 외부 수단으로 확인할 수 있음
• 테스트 또는 피어 시나리오를 생성할 수 있음
• 작업을 반복 가능한 단위로 분해할 수 있음
• 대상 언어가 명확한 이점을 제공함
• 조직이 대규모 실험용 브랜치를 수용할 수 있음
• 인간 전문가가 아키텍처 및 경계 사례를 검토할 수 있음
• 도구 환경을 제한하고 감사할 수 있음

다음과 같은 경우에는 적합하지 않을 수 있습니다:

• 원래 동작에 대한 이해가 불충분함
• 정확성을 검증할 수 없음
• 프로젝트가 마이그레이션과 완전한 제품 재설계를 혼동함
• 규제 승인을 위해 모든 변경 사항에 대한 수동 검증이 필요함
• 코드에 안전하게 노출할 수 없는 기밀 또는 시스템이 포함됨
• AI 생성 코드 병합 후 팀이 소유권을 가지지 않음

수백만 줄의 코드를 빠르게 생성할 수 있다고 해서 마이그레이션 방안이 당연히 타당한 것은 아닙니다.

자주 묻는 질문

Claude Code가 실제로 Bun을 Zig에서

러스트로 다시 작성했나요?

네. Jarred Sumner는 Claude Code 동적 워크플로우와 프리릴리스 Claude 모델을 활용하여 Bun의 핵심을 Zig에서 Rust로 마이그레이션했습니다. 이 과정은 2주도 안 되어 백만 줄 이상의 코드를 생성했으며, 이후 컴파일, 테스트, 검토, 병합 후 수정이 이루어졌습니다.

Bun 마이그레이션 비용은 얼마나 들었나요?

Anthropic 보고서에 따르면 약 59억 개의 캐시되지 않은 입력 토큰과 6억 9천만 개의 출력 토큰이 소비되었습니다. API 가격 기준으로 모델 비용은 약 16만 5천 달러로 추정되며, 이는 인력 및 인프라 비용을 포함하지 않은 금액입니다.

마이그레이션 병합 전에 모든 테스트를 통과했나요?

Anthropic은 병합 전에 Bun의 기존 테스트 스위트가 CI에서 통과되었다고 밝혔습니다. 병합 후 19개의 회귀 문제가 발견되었으며, 이후 모두 수정되었습니다.

Bun이 왜 Zig에서 Rust로 마이그레이션했나요?

주요 목표는 메모리 안전성을 높이고 반복적인 수명 문제,

정리, 해제 후 사용, 이중 해제 및 메모리 누수 문제를 줄이는 것이었습니다. Rust의 소유권과 타입 시스템은 컴파일 타임에 이러한 많은 문제를 잡아낼 수 있습니다.

Claude Code가 임의의 코드베이스를 자동으로 마이그레이션할 수 있나요?

아니요. 성공적인 마이그레이션을 위해서는 엄격한 평가자, 명확한 규칙, 의존성 분석, 통제된 권한, 재현 가능한 큐, 적대적 검토 및 인간 감독이 필요합니다. 일부 프로젝트는 마이그레이션해서는 안 됩니다.

적대적 코드 검토란 무엇인가요?

적대적 검토자는 독립된 환경에서 생성된 변경 사항을 받아 승인이 아닌 결함 찾기를 담당합니다. 구현자와 검토자의 역할이 달라 작성자가 자신의 출력물을 유지할 위험을 줄입니다.

기존 테스트 스위트가 필요한가요?

이상적으로는 기존 테스트 스위트가 잘 갖춰져 있어야 하며, 특히 구현 언어와 독립적으로 공용 동작을 테스트할 수 있어야 합니다. 그렇지 않은 경우 팀은 새 시스템과 기존 시스템 간의 실제 시나리오와 출력 차이를 비교하는 검증 프레임워크를 구축할 수 있습니다.

Anthropic의 마이그레이션 툴킷이 Bun이 사용한 전체 워크플로우인가요?

아니요. Anthropic은 해당 저장소를 일반화되고 리팩터링된 스타터 툴킷으로 설명합니다. 실제 Bun 마이그레이션은 긴 프로젝트 규칙 매뉴얼과 맞춤형 동적 워크플로우를 포함한 더 구체적인 구성 요소를 사용했습니다.

관련 도구

• Claude Code: Anthropic의 지능형 코딩 도구로, 저장소, 터미널, 테스트 및 개발 워크플로우 관리에 사용됩니다.
• Bun: JavaScript 및 TypeScript 런타임, 패키지 관리자, 번들러 및 테스트 러너.
• Rust: 성능, 타입 안전성 및 메모리 안전성에 중점을 둔 시스템 프로그래밍 언어.
• Zig: 명시적 제어와 간결한 언어 의미론을 강조하는 저수준 프로그래밍 언어.
• GitHub: Bun 마이그레이션 풀 리퀘스트 및 Anthropic 마이그레이션 툴킷 관리를 위한 소스 제어 및 협업 플랫폼.
• Claude Code 현대화 플러그인: 레거시 시스템 평가 및 현대화를 위한 Anthropic 공식 플러그인.

관련 링크

• Anthropic 대규모 코드 마이그레이션 가이드: 공식 6단계 프로세스 및 두 가지 마이그레이션 사례 연구.
• Bun을 Rust로 다시 작성: Jarred Sumner의 아키텍처, 워크플로우, 검토, 실패 및 결과에 대한 상세 기록.
• Bun Rust 재작성 풀 리퀘스트: 대규모 Zig에서 Rust 마이그레이션을 포함한 병합된 풀 리퀘스트.
• Claude Code 마이그레이션 툴킷: 언어 마이그레이션을 위한 공식 프롬프트, 템플릿, 스크립트 및 참조 워크플로우.
• Claude Code 문서: 공식 설치, 구성, 보안 및 워크플로우 문서.
• 코드 현대화 플러그인: 레거시 시스템 평가 및 변환을 위한 공식 Claude Code 플러그인.

동등성 테스트.

• Rust 공식 가이드: Rust의 소유권, 빌림, 타입, 동시성 및 애플리케이션 개발에 관한 공식 문서.

요약

Claude Code가 Bun의 마이그레이션을 성공시킨 것은 완벽한 백만 줄 재작성을 한 번에 생성했기 때문이 아닙니다. 프로젝트 성공의 핵심은 팀이 모델을 중심으로 엄격한 생산 시스템을 구축한 데 있습니다: 규칙 매뉴얼, 의존성 매핑, 격차 목록, 파일럿 프로젝트, 병렬 번역 큐, 적대적 검토, 컴파일러 루프, 스모크 테스트 및 동작 일관성 검사.

동일한 방법으로 Anthropic은 주말 안에 대규모 Python 코드베이스를 TypeScript로 마이그레이션했습니다. 두 사례 모두에서 원시 생성 속도보다 객관적 검증이 훨씬 중요했습니다.

AI는 대규모 마이그레이션의 비용과 기간을 크게 줄일 수 있지만, 프로세스가 중단 후 복구 가능하고, 권한이 통제되며, 반복되는 결함이 생성 코드의 규칙을 지속적으로 개선할 수 있어야 합니다.

진정한 돌파구는 AI가 백만 줄의 코드를 작성할 수 있다는 것이 아니라, 정교하게 설계된 루프가 이 코드를 반복적으로 생성하고, 의문을 제기하고, 테스트하고, 수정하여 새 시스템의 동작이 기존 시스템과 완전히 일치할 때까지 개선한다는 점입니다.