Anthropic제품 블로그Enterprise AI
AI 기반 코드 현대화 프로젝트, 어떻게 준비해야 할까
에이전트를 활용하면 코드 현대화를 몇 달 안에 마칠 수 있다. 하지만 실제 속도를 좌우하는 건 결국 변화 관리다. 목표 설정부터 인증, 승격 정책 수립까지 — 반드시 짚어야 할 6단계를 정리했다.
현장 노트 시리즈에서는 Anthropic의 현장 배포 엔지니어들이 실제 고객 배포 사례를 바탕으로 정리한 모범 사례를 공유합니다. 이번 글에서는 대규모 코드 현대화 프로젝트를 관리하며 얻은 경험을 나눕니다.
코드 현대화는 한때 수년이 걸리는 전사적 과제로 여겨졌지만, 이제는 몇 달, 심지어 몇 주 안에 마칠 수 있게 됐다. 다만 그 앞뒤로 필요한 조직적 작업은 여전히 크게 달라지지 않았다.
예를 들어, 핵심 뱅킹 시스템에 대한 모든 변경 사항은 변경 관리, 검토, 승인 프로세스를 거쳐야 한다. 규제 기관, 감사 기관, 비즈니스 모두가 요구하는 사항인 만큼 이 프로세스는 매우 엄격하게 운영된다.
이러한 프로세스야말로 핵심 시스템을 신뢰할 수 있게 만드는 근간이다. 이 프로세스는 사람이 각 변경 사항을 작성하고 다른 사람이 각 diff를 검토한다는 전제 위에 설계됐다. 에이전트가 변경 사항 작성을 가속화하면, 병목은 변경 사항을 만들어내는 것에서 조직이 그에 대응하도록 움직이는 것으로 이동한다.
이 글은 현대화 작업이 시작되기 전에 기업이 반드시 준비해야 할 사항을 다룬다. '완료'가 무엇을 의미하는지 정의하고, 변경 사항이 갖춰야 할 근거는 무엇인지, 인증된 변경 사항이 어떻게 프로덕션에 도달하는지, 그리고 작업을 시작하기 위해 무엇을 미리 갖춰야 하는지를 살펴본다.
이 과정을 여섯 단계로 나눠 설명한다.
- 목표 정의: 현대화된 코드가 갖춰야 할 기술 스택과 동작 방식을 규정한다.
- 인증서 작성: 변경 사항이 목표 상태에서 올바른 것으로 인정받기 위해 충족해야 할 조건을 정한다.
- 승격 정책 수립: 인증된 변경 사항이 생산 속도에 맞춰 프로덕션에 반영되는 경로를 정의한다.
- 사전 요건 준비: 환경, CI/CD, 검토 역량, 승인 체계를 갖춘다.
- 에이전트 워크플로우 구축 및 고도화: 목표, 인증서, 승격 정책을 중심으로 설계된 맞춤형 Claude Code 동적 워크플로우(dynamic workflow)를 구축한다. 이 워크플로우는 현대화 작업을 다수의 소규모 병렬 서브에이전트 작업 흐름으로 분산해 변경 사항을 생성한다.
- 현대화 실행: 코드베이스의 일부 구획을 대상으로 워크플로우 전체를 검증한 뒤, 전체 규모로 확장한다.
1단계: 목표 정의
목표란 현대화의 최종 도달 상태를 말한다. 원하는 최종 상태에 따라 아래 표에서 설명하는 세 가지 현대화 유형 중 어느 것을 수행할지 결정된다.
현대화 유형 결정
어떤 유형의 현대화를 선택할지는 조직 내에서 논쟁이 되기 쉽다. 우리의 경험상, 프로덕션 현장에 가장 가까운 사람들은 위험을 최소화하기 위해 동작 방식은 그대로 두고 스택만 교체하는 트랜스폼 방식을 선호한다. 반면, 코드베이스와 오랫동안 씨름해온 엔지니어들은 현대화를 통해 기술 부채도 함께 해소하길 원하고, 비즈니스 이해관계자들은 이 기회에 새로운 요구사항을 반영하려는 경향이 있다. 이는 리이매진 방식에 가깝다.
두 입장 모두 합리적이지만, 이 문제를 해결하지 않고 넘어가면 나중에 특정 변경 사항이 '올바른지' 여부를 놓고 다시 충돌이 생긴다. 어떤 방향으로 갈 것인지 합의를 이끌어내는 데는 초반에 마찰이 따르지만, 프로젝트 전체의 흐름은 훨씬 매끄러워진다.
코드베이스 파악과 동작 명세서 작성
목표를 정의하는 첫걸음으로 현재 시스템을 제대로 파악하는 것이 유효하다. 기존 코드가 실제로 무엇을 하는지 추출하고 현재 동작 목록을 만들어두면, 어떤 부분을 변경하고 어떤 부분을 제거할지 판단하기 쉬워지고, 트랜스폼과 리이매진 중 어느 방식이 맞는지도 명확해진다. 이 과정에서 알려지지 않았던 비즈니스 로직이나 엣지 케이스가 드러나는 경우도 많다.
이러한 탐색 작업의 상당 부분을 Claude가 처리할 수 있다. 아무도 기억하지 못하는 의존성을 매핑하고 워크플로우를 문서화하는 식으로 말이다. 코드 현대화 플러그인의 assess, map, extract-rules 명령은 소스 인용과 함께 비즈니스 규칙을 추출해주며, 엔지니어는 이를 검토하면 된다.
다만 Claude의 탐색만으로는 레거시 시스템의 동작 전반을 파악하기 어려울 수 있다. 비즈니스 사용자와 개발자 인터뷰, 내부 문서 등을 통해 빠진 부분을 보완해야 한다. 컨텍스트 수집에 초반 시간이 걸리더라도, 그 품질이 이후 워크플로우의 모든 판단에 영향을 미친다.
리이매진의 경우 목표 정의에 추가 작업이 필요하다. 새 시스템에 대한 상세한 동작 명세서를 문서화하고 사용자 그룹과 합의해야 한다.
프로젝트의 타당성과 목표 정립
목표를 정의하는 동시에, 조직은 이 현대화가 왜 추진할 가치가 있는지를 검토해야 한다. 레거시 시스템을 현대화하면 지속적인 유지보수 및 운영 비용을 줄일 수 있지만, 우리 경험상 비용 절감이 현대화 프로젝트의 핵심 목표인 경우는 많지 않았다.
리스크 감소가 현대화의 가장 중요한 가치인 경우가 많다. 프로젝트 추진 여부를 논의할 때는 현대화를 하지 않을 경우의 리스크도 반드시 고려해야 한다.
예를 들어, 미패치 취약점을 안고 있는 시스템은 사이버 침해나 심각한 장애로 이어질 수 있고, 사업 자체를 위협할 수도 있다. 지원이 종료된 런타임이나 해당 시스템을 이해하는 엔지니어 풀이 점점 줄어드는 상황은 이 리스크를 더욱 키운다.
Claude Code와 같은 에이전트 코딩 도구가 현대화 일정을 단축시켰지만, 예산 추정은 여전히 쉽지 않아 추진 결정이 늦어지는 원인이 되곤 한다. 우리는 대규모 현대화 사례의 비용 일부를 공개했고, 다른 사례들도 공개된 바 있다. 이를 대략적인 기준점으로 활용할 수 있으며, 예산 추정에 대한 추가 가이드는 이 글 하단에서 확인할 수 있다.
이러한 프로젝트를 시작할 때 가장 큰 과제는 대개 해당 시스템을 소유한 팀과 이에 의존하는 팀 모두로부터 내부 합의와 실질적 참여를 이끌어내는 일이다. 주로 리더십 레벨에서 비즈니스 케이스를 구축하고 프로젝트 목표를 설정하면 이 과정이 수월해진다. 또한 이후 단계의 인증서와 승격 정책에서 발생하는 트레이드오프를 결정할 때 기준점이 된다. 변경 사항이 감수할 수 있는 리스크 수준을 두고 이해관계자들 사이에 이견이 생길 때, 현대화를 하지 않을 경우의 리스크가 균형추 역할을 한다.
2단계: 인증서 정의
인증서란 모든 현대화 변경 사항이 충족해야 하는 조건 또는 테스트의 집합이다. 변경 사항이 목표에 부합한다는 가장 강력한 누적 근거를 제공하는 조건들을 선별한다.
각 조건은 사람이 개입하지 않아도 검증 가능해야 한다. 그래야 에이전트 워크플로우가 인증서를 충족할 때까지 변경 사항을 반복 수정하거나, 충족이 불가능한 경우 사람의 검토를 요청할 수 있다.
인증서에 포함될 항목은 목표에 따라 달라지지만, 일반적으로 다음 목록에서 선별한다.
- 기존 테스트 스위트 통과
- 현대화 과정에서 Claude가 작성한 테스트 전체 통과
- 테스트 커버리지가 합의된 기준치 충족
- 성능 벤치마크가 합의된 범위 내 유지
- 각각 새 컨텍스트 창에서 독립적으로 수행한 Claude의 적대적 검토에서 블로킹 이슈 없음
- 사용자 인터페이스의 경우, Claude 기반 컴퓨터 사용으로 회귀 없음 확인
- 동일 입력에 대해 현재 버전과 목표 버전이 동일한 출력 생성 — 라이브, 녹화, 또는 Claude 생성 데이터 활용 가능
- 저장 상태와 와이어 포맷이 현재 버전과 목표 버전 사이에서 왕복 변환 가능
- 변경 사항이 합의된 기간 동안 스테이징에서 실행되며 오류율, 지연 시간, 알림에서 회귀 없음
- 정적 분석 및 보안 스캔에서 새로운 발견 사항 없음
- 컴파일 대상의 경우, 빌드가 깨끗하고 타입 검사 통과
인증서는 변경 사항을 검토하고 프로덕션에 승격시킬 사람들과 함께 작성한다. 인증서와 에이전트 워크플로우가 설계되는 단계에서부터 현재 코드베이스에 의존하는 개발자, 사용자 그룹, 비즈니스 리드를 참여시킨다.
이들의 전문성이 인증서가 무엇을 측정할지를 결정하고, 초기 참여가 변경 사항이 검토 단계에 도달했을 때의 수용을 이끌어낸다. 완성된 인증서에 대한 좋은 점검 기준은, 그들이 인증서 근거만으로 머지할 의향이 있는지 여부다. 자신들의 기준이 인증서에 반영돼 있다고 느끼면, 3단계의 승격 정책을 더 간소하게 설계할 수 있다.
인증서가 무엇을, 어떻게 검증하는지는 현대화 유형에 따라 달라진다.
- 업리프트 현대화의 경우, 기준은 원본 코드베이스와의 동등성이며, 원본 테스트 스위트가 인증서의 핵심이 될 수 있다.
- 트랜스폼 현대화의 경우, 기준 역시 원본 코드베이스와의 동등성이지만, 원본 테스트 스위트가 새 스택에서 실행되지 않는 경우가 많다. 대신 프로덕션 트래픽 재현, 구버전과 신버전 간 차등 테스트, 프로덕션 병렬 배포가 핵심 역할을 한다.
- 리이매진 현대화의 경우, 인증서는 동작 명세서를 기준으로 한다. 이것이 가장 어려운 케이스다. 명세서는 기존 시스템과의 diff처럼 객관적이지 않기 때문에 모델의 판단이 더 많이 개입되고, 결과의 편차도 커질 수 있다. 이 경우 인증서는 명세서를 기반으로 작성된 테스트, 각 변경 사항을 명세서와 대조하는 Claude의 독립적인 적대적 검토, 신규 시스템이 기존 시스템의 동작을 유지하는지 확인하는 차등 검사에 의존한다. 명세서가 구체화되면서 인증서도 함께 수정될 것을 예상해야 한다. 명세서의 공백은 이 단계에서 가장 먼저 드러난다.
오래된 시스템은 테스트 커버리지가 빈약하고, 불안정한 테스트가 많으며, 텔레메트리도 부족한 경우가 흔하다. 인증서를 정의하는 작업의 일부는 이러한 공백을 파악하는 것이다. 탄탄한 인증서를 갖추기 어렵다면, 이 단계에서 가장 유용한 일은 Claude를 활용해 누락된 근거를 직접 구축하는 것이다. 프로덕션 병렬 환경을 구성하거나, 재현 하네스를 만들거나, 테스트를 추가로 작성하는 방식으로 말이다.
3단계: 승격 정책 수립
에이전트는 어떤 인간 팀도 diff 단위로 검토할 수 없을 만큼 빠르게 변경 사항을 생성한다. 승격 정책은 사전에 문서화하고 합의한 단계별 검토 경로로, 변경 사항에 대한 사람의 검토 깊이를 설정해 현대화가 수용 가능한 일정 내에 완료될 수 있도록 한다.
인증서와 마찬가지로, 이 단계도 검토자들과 함께 작업하고, 가능한 한 조직의 기존 변경 관리 프로세스에 맞춰 설계한다. 세부 내용은 조직마다, 직면한 리스크 트레이드오프마다 다르겠지만, 어디에나 통용되는 몇 가지 원칙이 있다.
- 영향 범위와 에이전트 신뢰도에 따라 변경 사항을 등급화한다. 조직 자체의 변경 또는 리스크 분류 체계가 있다면 활용한다. 핵심 경로에 대해서는 완전한 사람 검토를 유지한다.
- 반복되는 플래그는 근본 원인에서 해결한다. 시간이 지남에 따라 플래그가 달린 변경 사항을 그룹화하고 분석한다. 동일한 종류의 플래그가 반복해서 나타나면, 건별로 검토하는 대신 에이전트 워크플로우나 인증서에서 원인을 수정한다.
- 출력 형식은 검토자와 함께 설계한다. 검토를 가장 빠르게 할 수 있는 정보와 형식이 무엇인지, 어떤 신호가 더 높은 신뢰를 주는지 합의한다. 5단계에서 초기 샘플 출력물에 대해 검토를 진행하도록 한다.
- SME(도메인 전문가) 시간을 효율적으로 배분한다. SME가 모든 최종 diff를 읽지는 않더라도, 그들의 판단은 여전히 가장 희소한 투입 자원이다. SME가 방대한 diff를 헤집지 않고도 가장 높은 리스크 등급의 변경 사항과 그 안의 주요 에이전트 결정 지점으로 곧장 이동할 수 있게 만든다. 소수의 전문가 시간으로 가장 위험도가 높은 변경 사항을 커버할 수 있다.
이러한 원칙들 중 상당수는 프로젝트 초반에 SME를 참여시켜 그들의 시간을 선투자하는 방식이다. 그들의 피드백은 본격적인 현대화 작업이 시작되기 전에 인증서와 에이전트 워크플로우를 다듬는 데 쓰인다.
샘플에 대한 SME의 승인은 신뢰도가 높은 영역에서 더 간소한 검토 경로를 정당화하는 추가 근거가 된다. 이는 검토가 마지막에 이루어지는 전통적인 비에이전트 방식과 정반대 구조다.
승격 정책은 속도와 검토 깊이 사이의 스펙트럼에서 해당 현대화가 어느 지점에 위치하는지도 반영해야 한다. 런타임 지원 종료처럼 명확한 데드라인이 있는 현대화라면 더 빠른 정책, 즉 더 가벼운 사람 검토와 변경 사항당 더 많은 리스크를 감수한다는 명시적 합의가 필요하다.
여유 있는 일정으로 진행하는 현대화는 더 깊은 사람 검토와 느린 전환을 감당할 수 있다. 이해관계자들은 리스크 감수 수준과 제약에 따라 이 스펙트럼의 서로 다른 지점에 자리잡게 되므로, 작업 시작 전에 합의를 확정해두는 것이 중요하다.
규제 환경에서는 어떤 변경이든 사람 검토를 가볍게 처리한다는 것 자체가 큰 부담이 될 수 있다. 개별 승인자는 잘못된 변경 사항의 책임이 자신에게 돌아올까 봐 주저하는 반면, 리더십은 노후화된 시스템이 가져오는 더 큰 리스크를 감당해야 한다.
우리 경험상, 승격 정책에 대한 방향은 조직 최상위에서 내려오는 것이 가장 효과적이다. 또한 프로덕션에 도달한 버그의 책임이 승인자 한 명에게 집중되지 않도록, 사전에 합의해두는 것이 낫다.
이 모든 것은 결국 실질적인 근거로 기능할 만큼 충분히 상세한 인증서와, Claude가 변경 사항에 이른 과정을 충분히 이해해 신뢰할 수 있는 검토자를 전제로 한다.
4단계: 사전 요건 준비
이 단계의 많은 부분이 현대화 팀 외부의 조직과의 협업을 요구한다. 호스트 환경을 위한 플랫폼 또는 인프라 팀, 테스트 역량을 위한 QA 또는 릴리즈 엔지니어링 팀, 승인을 위한 보안 및 컴플라이언스 팀이 여기에 해당한다. 각 팀에는 고유한 백로그나 승인 프로세스가 있는 경우가 많으므로, 요건을 파악하는 즉시, 주로 1~3단계가 진행되는 시점부터 일찌감치 대화를 시작해야 한다.
환경
- 코드베이스와 Claude가 접근해야 할 기타 소스에 연결된 워크플로우 실행용 전용 원격 호스트
- 인증서 요건에 맞는 테스트 역량
- 인증서 강화를 위한 모든 요소: 프로덕션 텔레메트리, 프로덕션 병렬 환경, 또는 재현용 프로덕션 데이터
코드베이스 및 CI/CD
- 빌드 및 컴파일 로그, 임포트 분석, 또는 런타임 트레이스에 기반한 코드베이스 의존성 맵. 참고: 플러그인의 map 명령이 좋은 출발점이지만, 코드베이스의 규모와 노후도에 따라 더 광범위한 사전 작업이 필요할 수 있다
- 목표 정의의 일환으로, 의존성 및 패키지 처리 방안 사전 계획
- 필요한 경우 CI/CD에 추가할 호환성 검사 준비
- 현행 코드베이스에서 현대화하는 경우, 합의된 코드 프리즈 정책
- 코드 프리즈 및 새로운 호환성 요건을 활성 개발자에게 안내하는 커뮤니케이션 계획
팀 구성 및 검토
- 코드베이스에 의존하는 다른 팀들로부터, 인증서 승인이나 승격 정책 하의 검토 등 참여 방식에 대한 합의 및 검토자 시간 확보
보안 및 컴플라이언스
- 소스 코드 접근이 승인된 Claude Code 모델 접근 경로
- 에이전트 워크플로우에 대한 최소 권한 접근: 현대화 브랜치에만 쓰기 허용, 프로덕션 자격증명 없음
- 현대화 브랜치에서 시크릿 및 개인정보 제거 또는 마스킹
- 모든 변경 사항이 추적 가능하며 PR이 에이전트 트랜스크립트 및 인증서 근거와 연결됨
- 신규 의존성에 대한 라이선스 및 취약점 검사
5단계: 에이전트 워크플로우 구축 및 고도화
Claude Code를 활용해 코드베이스 현대화에 특화된 동적 워크플로우를 개발한다.
코드 현대화 플러그인을 시작점으로 삼고, 워크플로우에 필요한 모든 것을 Claude가 접근할 수 있도록 파일 시스템이나 MCP를 통해 준비해둘 것을 권장한다. 목표, 인증서, 승격 정책, 코드베이스, 문서, 인증서에 필요한 데이터 소스나 툴링이 여기에 해당한다. 이 글 자체를 Claude에게 컨텍스트로 제공할 수도 있다. 이것이 프로젝트의 핵심 지식 베이스를 구성한다.
이러한 준비가 갖춰지면, 현대화 워크플로우를 구축하는 것은 그다음으로 쉬운 부분이다. 다운스트림 작업이 의존하기 전에, 코드베이스 특화 기술이나 추출된 규칙을 포함해 Claude의 작업물을 SME가 필요에 따라 검토하도록 한다.
구축한 워크플로우를 코드베이스의 작은 부분에 적용하면서 고도화한다. 이때 SME가 워크플로우가 생성하는 변경 사항, 에이전트의 처리 과정, 인증서 충족 근거를 검토한다.
문제가 발견되면 개별 변경 사항이 아니라 워크플로우 자체를 수정해야 한다. 전체 규모로 확장했을 때 변경 사항이 거의 모든 경우에 인증서를 충족하고, 검토자들이 승격 정책 하에서 편안하게 머지할 수 있다는 확신을 갖는 것이 목표다.
6단계: 현대화 실행
먼저 코드베이스의 일부 구획을 대상으로 승격 정책을 통한 변경 사항 검토 및 반영까지 현대화 전 과정을 완주한다. 아직 규모가 작을 때 작동하지 않는 부분을 수정하고, 자신감이 생길 때까지 반복한 뒤, 전체 코드베이스로 확장한다.
트랜스폼과 리이매진 현대화는 기존 시스템과 함께 목표 시스템을 구축한 뒤 완성되면 전환하는 방식인 반면, 업리프트는 두 번째 선택지가 있다. 개발이 계속 진행되는 라이브 코드베이스에서 현행 코드를 직접 현대화하는 방식이다.
이 방식은 시스템을 중단할 수 없거나, 코드베이스 변경이 너무 빨라 현대화된 별도 사본을 최신 상태로 유지하기 어려울 때 주로 선택한다. 이 경우 우리가 효과를 확인한 방법은 다음과 같다. 코드베이스를 말단(leaves)부터 안쪽으로 논리적 구획으로 분리하고, 한 번에 하나의 구획을 프리즈하고 현대화한 뒤, 구획이 현대화된 이후 새 커밋이 이를 되돌리지 못하도록 CI/CD를 게이팅하는 방식이다.
비용에 관한 참고 사항
현대화에 드는 토큰 비용이 얼마나 되는지 자주 질문을 받는다. 현대화 작업은 경우마다 다르지만, 주요 비용 요인은 다음과 같다.
- 코드베이스에서 읽기만 하는 부분과 실제로 변경하는 부분의 비율
- 인증서의 복잡도 (규제 환경에서는 변경 사항 작성이 아니라 검증이 대개 더 큰 비중을 차지한다)
- 인증서가 요구하는 새로운 테스트 작성 및 테스트 수정의 양
- 작업이 진행되는 동안 다른 팀이 코드를 머지하면서 발생하는 조정 작업의 양
코드베이스 일부를 대상으로 현대화를 완료할 때 토큰 사용량을 측정하고, 이를 바탕으로 전체 작업의 비용을 추산한다. 파일럿에서 확인하지 못한 요소, 예를 들어 라이브 코드베이스에서의 조정 작업은 미지수로 처리한다. 이 방식으로 전체 현대화의 최소 비용 기준선을 도출할 수 있다.
파일럿 측정값은 또한 에이전트 워크플로우의 비용 최적화 지점을 보여준다. 토큰을 가장 많이 소비한 워크플로우 부분을 찾아 효율화 방법을 검토한다. 계산 비용이 높은 검증 신호는 더 저렴한 게이트 뒤에 배치해 쉬운 검사를 통과한 경우에만 실행되도록 한다.
인증서가 완전히 검증하는 기계적이고 대용량의 작업에는 Sonnet처럼 비용과 성능의 균형이 잡힌 모델을 활용하는 것을 고려한다. 어려운 변환 작업과 정확성을 검증하는 적대적 검토에는 더 강력한 모델을 유지한다.
저렴한 모델이 인증서를 충족하지 못할 때 더 비싼 모델로 에스컬레이션하는 방법도 있지만, 파일럿 단계에서 재시도율을 면밀히 분석해야 한다. 저렴한 모델로 여러 번 시도하는 것이 비싼 모델 한 번보다 더 많은 비용이 드는 경우가 있기 때문이다. Claude에게 워크플로우와 파일럿 데이터 모두에 접근 권한을 주면, 이 분석의 상당 부분을 함께 수행할 수 있다.
현대화 이후
현대화된 코드베이스가 하나의 산출물이라면, 그것을 만들어낸 워크플로우, 올바름의 기준을 담은 문서화된 인증서, 변경 관리 프로세스가 이미 수용한 승격 정책, 그리고 반영된 모든 변경 사항에 대한 근거 추적 기록도 똑같이 중요한 산출물이다. 다음 업그레이드나 재작성에도 이 패턴이 바로 적용될 수 있도록, 이 플레이북을 재사용 가능한 자산으로 정리해두자.
Anthropic의 현장 배포 엔지니어들은 고객의 가장 중요한 시스템을 대상으로 이 단계들을 함께 진행한다. 현대화를 준비 중이라면 저희 팀에 문의하세요.
