Sandboxed Agents로 코드베이스 마이그레이션하기

레거시 코드베이스의 대규모 마이그레이션은 한 번에 묶어 처리하면 리뷰가 어렵고 병합 리스크도 커진다. 그래서 작업을 repo shard 단위로 쪼개고, 각 shard마다 독립된 sandbox에서 에이전트가 파일을 읽고, 수정하고, 테스트한 뒤 패치를 반환하는 방식이 필요하다.

핵심 구조는 host-side harness와 실행 환경의 분리다. 하니스는 Agents SDK를 비롯해 정책, 자격증명, MCP 서버, 감사 로그를 관리하고, sandbox에는 현재 작업에 필요한 파일과 명령만 넘긴다. 이렇게 하면 오케스트레이션은 신뢰된 호스트에 남기고, 코드 실행과 파일 편집은 격리된 환경에서 처리할 수 있다.

예제는 두 개의 서비스 리포지토리를 각각 다른 sandbox에 올려, OpenAI 클라이언트 래퍼를 Chat Completions에서 Responses API로 옮기는 작업을 보여준다. 에이전트는 각 sandbox에서 테스트를 먼저 돌려 기준선을 확인한 뒤, 코드를 수정하고, 다시 테스트와 compileall 검사를 실행하고, 최종적으로 타입이 정해진 마이그레이션 리포트와 패치를 돌려준다.

구성 요소는 다음과 같다.

• Manifest로 /workspace 아래에 필요한 파일만 스테이징한다.
• sandbox capability는 **Shell()**과 **ApplyPatch()**만 노출해 작업 범위를 제한한다.
• provider별 차이는 sandbox 생성 코드에만 두어, 같은 하니스와 에이전트를 Docker, E2B, Cloudflare 같은 다른 provider로 쉽게 바꿀 수 있다.

실행 전에는 같은 테스트를 호스트에서 먼저 돌려 baseline을 확인한다. 이후 각 task는 MIGRATION.md를 따르며, 호스트는 작업 결과를 받아 감사 로그를 남기고 sandbox를 삭제한 뒤 다음 shard로 넘어간다. 이 패턴은 대규모 코드 현대화를 더 작은 단위로, 더 안전하게 반복 실행하는 방법을 제시한다.