외주 코드 인계받을 때 봐야 할 5가지, 개발사가 안 알려주는 것

지난 주에 한 대표님이 외주받은 코드를 들고 오셨습니다. "다른 개발자한테 넘기려는데 아무도 못 만지겠다고 한다" 는 상황이었습니다. 흔한 케이스입니다. 외주 개발이 끝나고 코드는 받았는데 그 코드를 다음 사람이 이어받을 수 없는 상태입니다.

문제는 인계 시점에 무엇을 확인해야 하는지 대표님이 모른다는 점입니다. 개발사는 굳이 안 알려줍니다. 이 글은 코드를 인계받을 때 반드시 확인해야 할 5가지를 기술 디테일까지 정리한 노트입니다. 계약서 단계에서 이 5가지를 넣으면 6개월 뒤 재개발 함정의 대부분을 피할 수 있습니다.

1. README 만으로 셋업이 되는가

가장 먼저 볼 것입니다. 코드를 받아서 README 문서만 보고 로컬에서 실행할 수 있어야 합니다. 환경 변수 목록, 의존성 설치 명령, DB 마이그레이션, 실행 순서가 문서에 다 있어야 합니다.

기준은 단순합니다. 새 개발자가 README 보고 6시간 안에 로컬에서 앱을 띄울 수 있으면 통과입니다. 며칠씩 reverse engineering 해야 하면 인계가 안 된 겁니다. 인계 미팅에서 직접 새 개발자에게 셋업을 시켜보는 게 가장 확실한 검증입니다.

2. 환경 변수와 시크릿이 코드에 박혀 있지 않은가

코드 안에 API 키나 비밀번호가 하드코딩되어 있으면 위험 신호입니다. 시크릿은 환경 변수로 분리되어 있어야 하고 .env 파일은 git에 커밋되지 않아야 합니다.

확인 방법이 있습니다. git 히스토리에서 .env나 API 키 패턴을 검색해보면 됩니다. 과거 커밋에 시크릿이 한 번이라도 올라갔으면 그 키는 이미 노출된 것으로 보고 전부 교체해야 합니다. 이걸 안 보고 넘어가면 인수 후 보안 사고로 이어집니다.

3. 테스트 코드가 있는가

테스트 코드가 0줄이면 그 코드는 수정할 때마다 도박입니다. 한 곳을 고치면 다른 곳이 깨지는데 그걸 알아챌 방법이 없습니다. 다음 개발자가 기능 하나 추가하려다 전체를 망가뜨립니다.

최소한 핵심 비즈니스 로직과 결제·인증 같은 중요 경로에는 테스트가 있어야 합니다. 테스트 커버리지 숫자보다 중요한 게 "어디에 테스트가 있는가" 입니다. 돈이 오가는 경로에 테스트가 없으면 그게 가장 위험한 신호입니다.

4. DB 스키마와 마이그레이션이 관리되는가

DB 구조가 코드로 관리되는지 봐야 합니다. 마이그레이션 파일이 있어서 DB를 처음부터 재현할 수 있어야 합니다. 누군가 프로덕션 DB에서 직접 컬럼을 추가한 흔적이 있으면 그 DB는 코드와 어긋나 있습니다.

인덱스 전략도 확인합니다. 사용자가 늘었을 때 느려지는 80%가 DB 문제입니다. 인덱스가 없거나 N+1 쿼리가 폭발하는 구조면 출시 후 100명 동접에서 무너집니다. 이전 글에서 정리한 다운 패턴이 정확히 이 지점입니다.

5. AI로 뽑은 코드를 사람이 이해하는가

요즘 가장 흔한 새 함정입니다. AI로 급하게 뽑은 코드는 돌아가긴 하는데 만든 사람도 이해 못 하는 경우가 많습니다. 인계 미팅에서 핵심 로직 몇 군데를 짚어서 "이 부분이 왜 이렇게 짜였는지 설명해달라" 고 물어보세요.

개발자가 설명을 못 하면 그 코드는 AI가 뽑은 걸 검증 없이 머지한 겁니다. 그런 코드는 버그가 나면 고칠 수가 없습니다. 검증된 코드만 머지하는 원칙이 지켜졌는지가 핵심입니다. AI가 짰어도 사람이 이해하고 책임질 수 있어야 인계 가능한 코드입니다.

계약서에 넣을 한 줄

위 5가지를 계약 단계에서 명시하는 게 가장 확실합니다. "인계 시 README 기반 6시간 셋업, 핵심 경로 테스트 코드, DB 마이그레이션, 시크릿 분리, 핵심 로직 설명 가능" 을 납품 조건으로 넣으면 됩니다.

개발사가 이 조건을 거부하면 그 자체가 신호입니다. 제대로 만드는 곳은 이 조건이 당연합니다. 이미 그렇게 작업하고 있기 때문입니다.

베비투스랩의 결론

코드 인계는 외주의 마지막 단계가 아니라 처음부터 설계되어야 하는 것입니다. 인계 가능한 코드는 만드는 동안 인계를 염두에 두고 짠 코드입니다. 다 만들고 나서 인계 문서를 급조하면 이미 늦습니다.

베비투스랩이 4가지 약속 중 Foundation을 "재개발 없는 견고한 제품"으로 두는 이유가 여기 있습니다. 클린 아키텍처와 자동화 테스트가 기본이고 처음부터 다른 개발자가 이어받을 수 있게 짭니다. AI가 짠 코드도 사람이 검증하고 책임집니다.

솔직히 말씀드리면 인계 가능한 코드는 만드는 시점에 시간이 더 듭니다. README 쓰고 테스트 짜고 시크릿 분리하는 게 당장은 느려 보입니다. 그러나 그 시간이 6개월 뒤 재개발 비용을 막습니다. 비용은 100% 결과물로 가야 한다는 게 베비투스랩의 원칙이고 인계 가능한 코드가 그 결과물의 일부입니다.

---

받은 외주 코드가 인계 가능한 상태인지 함께 점검하고 싶으면 바이브 코딩 정비소 진단 에서 아키텍처·테스트·운영·인계 4축 점수를 확인할 수 있습니다.