3년 된 Node.js 레거시 코드베이스를 바이브코딩(vibe coding)으로 3주 만에 핵심 모듈 70%를 리팩토링한 팀의 실전 기록. 클로드 코드(Claude Code)와 커서(Cursor)를 조합해 기술 부채를 해소하는 과정에서 CLAUDE.md 컨텍스트 주입, 타입스크립트 마이그레이션, 깃허브 액션스 CI/CD 검증 게이트 도입까지 단계별 접근법을 정리한다. AI 코딩 도구로 레거시 프로젝트를 정리할 때 반드시 알아야 할 5가지 함정과 1인 개발자 적용법도 포함.
기술 부채는 늦게 갚을수록 이자가 불어난다. 스타트업에서 흔히 벌어지는 일이다. 출시 압박에 떠밀려 쌓인 코드가 3년 뒤 팀의 발목을 잡는다. 새 기능 하나를 붙이는 데 예상의 3배 시간이 걸리고, 코드 리뷰어는 파일 한 장을 이해하는 데만 하루를 쓴다.
한 SaaS 개발팀은 2026년 상반기 이 문제를 바이브코딩으로 정면 돌파했다. 전통적인 방식으로는 6개월이 걸릴 것으로 추정됐던 기술 부채 청산 작업을 클로드 코드(Claude Code)와 커서(Cursor)를 조합해 3주 만에 핵심 모듈 70%를 정리했다. 이 글은 그 과정 — 도입 결정부터 실패, 재설계, CI 통합까지 — 을 문제·시도·결과 구조로 재구성한 사례 기록이다.
이 팀이 관리하던 코드베이스는 3년 된 Node.js 백엔드였다. 초창기 MVP를 만들던 두 명이 짠 코드가 팀 규모 여섯 명으로 커지는 동안 그대로 남아 있었다. 파일 하나에 함수 40개, 전역 상태를 공유하는 미들웨어, 외부 라이브러리 버전은 2년 이상 고정 상태였다.
임계점은 신규 결제 모듈 연동 요청에서 드러났다. 기획 추산으로는 2주면 될 작업이었다. 개발팀 실제 소요 시간은 8주였다. 결제 로직이 사용자 인증, 구독 관리, 이메일 발송 코드와 뒤엉켜 한 줄을 바꾸면 세 군데에서 사이드 이펙트가 터졌다.
팀 리드가 기술 부채 현황을 스프레드시트로 정리했다. 전체 코드베이스의 단위 테스트 커버리지 12%, 함수당 평균 라인 수 87줄, 업데이트가 필요한 외부 의존성 23개였다. 이 수치를 확인한 후 팀은 다음 스프린트를 기술 부채 해소에 전량 투입하기로 결정했다.
초기 논의에서 두 가지 선택지가 나왔다. 팀원이 시간을 쪼개 전통 방식으로 리팩토링하거나, AI 코딩 도구를 활용해 속도를 높이거나. 전통적인 방식의 예상 소요 시간은 6개월이었다. 팀이 동시에 신규 기능도 유지해야 하는 상황에서 사실상 불가능한 기간이었다.
바이브코딩을 선택한 이유는 두 가지였다. 첫째, AI는 기존 코드를 읽고 패턴을 추출하는 데 인간보다 훨씬 빠르다. 둘째, 반복적인 리팩토링 작업 — 함수 분리, 변수명 정리, 타입 추가, 테스트 작성 — 은 AI가 가장 잘 처리하는 영역이다.
팀원들은 이미 개인적으로 챗지피티(ChatGPT)나 깃허브 코파일럿(GitHub Copilot)을 써온 경험이 있었다. 코드 생성 자체는 괜찮았지만, 기존 코드베이스 전체를 파악하고 일관된 방향으로 수정하는 능력에서 한계를 느끼고 있었다. 클로드 코드가 선택지로 오른 것은 프로젝트 전체 컨텍스트를 유지하며 멀티파일 작업을 처리하는 능력 때문이었다.
팀은 사흘 동안 세 가지 도구를 병행 테스트했다. 깃허브 코파일럿, 커서, 클로드 코드. 테스트 기준은 단순했다 — 기존 코드의 의존성 구조를 얼마나 정확하게 파악하고, 리팩토링 방향을 일관되게 제안하는가였다.
깃허브 코파일럿은 개별 함수 자동완성에 강했지만, 파일 간 관계를 추적하는 데 한계가 있었다. 커서는 에디터 통합이 뛰어나고 여러 파일을 동시에 수정하는 에이전트 모드가 유용했다. 클로드 코드는 터미널 기반이라 학습 비용이 있었지만, 전체 코드베이스를 스캔하고 의존성 관계를 설명하는 능력이 두드러졌다.
최종 선택은 클로드 코드를 주 엔진으로, 커서를 보조 편집기로 쓰는 조합이었다. 큰 단위 분석과 리팩토링 계획은 클로드 코드가 맡고, 코드 편집과 빠른 수정은 커서에서 처리하는 역할 분담이었다. 클로드 코드가 수립한 리팩토링 계획을 커서의 에이전트 모드로 실행하는 흐름이 가장 효율적이었다.
첫 주는 예상보다 느렸다. 클로드 코드에 레거시 코드를 보여주고 리팩토링을 요청했을 때, AI는 코드는 읽었지만 맥락을 이해하지 못했다. 왜 이 함수가 이런 구조인지, 어떤 비즈니스 이유로 이 우회로가 생겼는지를 몰랐다.
가장 큰 문제는 팀만 알고 있는 암묵적 규칙이었다. 특정 사용자 권한 체크가 미들웨어 세 군데에 중복된 이유는 초기 레거시 API와의 하위 호환성 때문이었다. AI는 중복으로 판단하고 하나로 합쳤다. 결과는 구형 API 클라이언트를 쓰는 일부 사용자의 서비스가 끊기는 사고였다. 롤백으로 대응했지만 반나절을 날렸다.
또 다른 문제는 파일 크기였다. 3년 된 코드베이스에는 1,000줄이 넘는 파일이 여러 개 있었다. AI가 한 번에 처리할 수 있는 컨텍스트 한계를 초과하자, 파일 끝부분 함수가 앞부분 맥락 없이 수정되는 일이 생겼다. 첫 주는 반복되는 롤백으로 마무리됐다.
문제 진단은 명확했다 — AI가 코드는 읽지만 배경을 모른다. 해법은 CLAUDE.md 파일을 통해 AI에게 팀의 규칙과 비즈니스 맥락을 명시적으로 알려주는 것이었다.
팀 리드는 CLAUDE.md 작성에 이틀을 투자했다. 포함된 내용은 크게 세 가지였다. 첫째, 절대 건드리면 안 되는 레거시 엔드포인트 목록과 그 이유. 둘째, 팀의 코딩 컨벤션 — 에러 핸들링 패턴, 로깅 규칙, 테스트 커버리지 기준. 셋째, 외부 API 연동 모듈의 구조와 변경 금지 인터페이스 목록.
효과는 즉시 나타났다. AI가 리팩토링을 제안할 때 레거시 엔드포인트를 보호하는 방향으로 접근했고, 팀 컨벤션에 맞는 코드를 생성했다. CLAUDE.md 없이 AI와 일하는 것은 신입 개발자에게 코드베이스를 아무 설명 없이 던져주는 것과 같다는 평가가 팀 내에서 공유됐다.
추가로 팀은 큰 파일을 먼저 분리하는 전략을 채택했다. 1,000줄짜리 파일은 AI에 주기 전에 수동으로 논리 단위로 나눴다. AI는 300~500줄 단위의 파일에서 훨씬 정확하게 동작했다.
2주차에 들어서자 흐름이 달라졌다. CLAUDE.md가 자리를 잡고, 팀원들이 AI와 일하는 리듬을 익히기 시작한 것이다. 하루에 처리하는 모듈 수가 1주차의 3배로 늘었다.
가장 효율이 높았던 작업 패턴은 다음과 같았다. 먼저 클로드 코드에 분석 대상 파일을 주고 의존성 맵을 만들도록 했다. AI가 이 파일의 의존성 관계와 리팩토링 시 영향 범위를 정리하면, 팀원이 방향을 결정하고 AI가 코드를 수정했다. 수정 후에는 자동 테스트가 돌아가고, 통과하면 다음 모듈로 넘어갔다.
타입스크립트(TypeScript) 마이그레이션 작업에서 AI 효율이 특히 두드러졌다. 타입 추론과 인터페이스 추출은 AI가 일관되고 정확하게 처리했다. 팀원은 전략을 결정하고, AI는 반복 작업을 실행하는 역할 분담이 안착된 것이다. 이 시점부터 팀의 체감 속도가 전통적 방식 대비 4~5배 빨랐다는 평가가 나왔다.
팀은 1주차 경험에서 AI가 생성한 코드를 검증 없이 신뢰할 수 없다는 교훈을 얻어 CI/CD 파이프라인에 추가 검증 단계를 넣었다.
핵심은 세 가지 게이트였다. 첫째, 단위 테스트 커버리지 게이트 — 리팩토링 전후 커버리지를 비교해 기존보다 낮아지면 풀 리퀘스트(PR)를 블록했다. 둘째, 타입 에러 게이트 — 타입스크립트 컴파일 에러 수를 이전 베이스라인과 비교했다. 셋째, 레거시 API 호환성 게이트 — 보호해야 할 엔드포인트 목록에 대한 통합 테스트를 CI에 포함시켰다.
깃허브 액션스(GitHub Actions) 워크플로우에 이 세 게이트를 추가하는 데 하루가 걸렸다. 이후 AI가 실수를 해도 자동으로 감지됐다. AI를 신뢰하는 것이 아니라, AI의 실수를 빠르게 잡는 시스템을 만드는 것이 핵심이었다는 것이 팀의 결론이었다.
부수적인 효과도 있었다. CI 게이트를 추가하면서 기존에 없던 통합 테스트가 생겼다. 바이브코딩 도입이 테스트 문화를 강화하는 계기가 된 것이다.
3주 후 팀이 정리한 결과다. 먼저 달라진 것들.
핵심 모듈 리팩토링 완료율은 약 70%였다. 결제 로직, 사용자 인증, 구독 관리 세 모듈이 독립적으로 분리됐다. 함수당 평균 라인 수는 87줄에서 32줄로 줄었다. 타입스크립트 전환율은 코드베이스의 65%에 달했다. 단위 테스트 커버리지는 12%에서 41%로 올랐다.
남아 있는 것도 있었다. 이메일 발송 모듈과 리포팅 모듈은 외부 서비스 의존성이 복잡해 AI가 자동으로 리팩토링하기 어려웠다. 수동 작업이 필요한 부분이었다. 또한 AI가 생성한 코드 중 일부는 팀 컨벤션에 완전히 맞지 않아 별도 리뷰 후 수정이 필요했다.
팀이 가장 크게 느낀 변화는 속도 이상의 것이었다. 바이브코딩을 통해 기술 부채 전체 현황을 처음으로 명확하게 시각화할 수 있었다. AI가 코드를 분석하면서 팀도 몰랐던 의존성 관계가 드러났다. 단순히 빠른 것이 아니라, 더 잘 보이게 됐다는 것이 핵심 성과였다.
이 팀의 경험에서 추출한 5가지 실패 패턴과 대응 방법이다.
함정 1: AI를 믿고 리뷰를 건너뛰는 것. AI가 빠르게 코드를 생성하면 리뷰 없이 병합하고 싶어진다. 하지만 AI는 비즈니스 맥락을 모른다. 모든 AI 생성 코드는 반드시 팀원 리뷰를 거쳐야 한다.
함정 2: 컨텍스트 없이 시작하는 것. CLAUDE.md 없이 AI에게 레거시 코드를 주면 AI는 코드를 읽지만 이해하지 못한다. 팀의 규칙, 금지 사항, 비즈니스 맥락을 먼저 문서화하는 것이 선결 조건이다.
함정 3: 큰 파일을 그대로 주는 것. 1,000줄이 넘는 파일은 AI 컨텍스트 한계를 초과한다. 먼저 논리 단위로 수동 분리한 뒤 AI에게 맡겨야 한다. 300~500줄 단위가 가장 효율적이었다.
함정 4: CI 게이트 없이 진행하는 것. AI 실수를 사람이 잡으려면 리뷰 부담이 너무 크다. 자동화된 테스트 게이트가 반드시 먼저 갖춰져야 한다. 커버리지 게이트 하나만 있어도 실수를 빠르게 잡을 수 있다.
함정 5: 결과에 기대치를 과장하는 것. 이 팀의 경우 3주 동안 기술 부채의 약 70%를 처리했다. 나머지 30%는 여전히 수동 작업이 필요했다. 바이브코딩은 속도를 높이지만, 사람의 판단을 대체하지 않는다.
CLAUDE.md 파일 작성이 가장 먼저다. 코드베이스의 규칙, 절대 수정하면 안 되는 인터페이스, 팀 컨벤션, 외부 서비스 의존성 맥락을 담는다. 이 파일 없이 AI에게 레거시 코드를 주면 맥락 없이 수정해 사이드 이펙트를 만든다. AI는 빠르지만 배경을 모른다. CLAUDE.md는 AI에게 팀의 배경을 알려주는 문서이자, 프로젝트 진입 장벽을 낮추는 유일한 수단이다.
역할이 다르다. 클로드 코드는 전체 코드베이스 분석과 의존성 파악, 리팩토링 계획 수립에 강하다. 커서는 실제 코드 편집과 빠른 수정에 강하다. 대규모 기술 부채 청산에는 클로드 코드로 분석·계획하고, 커서로 실행하는 조합이 효과적이다. 예산이 제한적이라면 클로드 코드 하나로 시작해도 된다. 클로드 코드 맥스(Max) 플랜은 대용량 컨텍스트 작업에 유리하다.
세 가지 자동 게이트를 CI에 추가하는 것을 권장한다. 첫째, 단위 테스트 커버리지 — 리팩토링 전후 비교해 감소하면 블록. 둘째, 타입 에러 수 — 타입스크립트 에러가 늘어나면 블록. 셋째, 레거시 API 호환성 테스트 — 기존 엔드포인트가 정상 동작하는지 통합 테스트로 확인. 자동 게이트가 없으면 AI 실수를 사람이 전부 잡아야 해 오히려 느려진다. 깃허브 액션스로 하루 안에 구성할 수 있다.
비즈니스 규칙 이해와 복잡한 외부 서비스 의존성 처리다. AI는 코드 패턴은 잘 인식하지만, 이 함수가 왜 이 구조인지의 이유를 모른다. 레거시 API 하위 호환성, 특정 고객에게만 적용된 예외 로직, 외부 서비스 SDK의 비공개 동작 방식 등은 인간이 직접 판단해야 한다. 이런 부분을 CLAUDE.md에 명시해두면 AI가 최소한 건드리지 않도록 유도할 수 있다.
가능하다. 팀 내 승인 프로세스가 없어 빠르게 실험할 수 있는 장점이 있다. 단, 혼자 작업할 때 리뷰 단계를 생략하기 쉽다는 것이 위험하다. 최소한 AI 생성 코드를 병합하기 전에 직접 전체를 읽는 습관이 필요하다. 또한 커버리지 게이트를 CI에 추가해 실수를 자동으로 잡는 안전망을 먼저 만들 것을 권장한다. CLAUDE.md 작성과 CI 게이트 추가 — 이 두 가지를 먼저 갖추면 1인 개발자도 충분히 시도할 수 있다.
이 팀의 경험에서는 리팩토링 자체보다 부수적인 효과가 컸다. AI와 함께 코드를 분석하면서 기존에 몰랐던 의존성 구조가 드러났고, CI 게이트를 추가하면서 테스트 커버리지가 올랐다. 코드 품질은 AI가 직접 높이는 것이 아니라, AI를 도입하는 과정에서 갖추게 된 구조와 도구가 품질을 높인다. 바이브코딩은 좋은 엔지니어링 관행을 강제하는 트리거가 된다는 점에서 가치가 있다.
