외주 개발의 진짜 시험대는 납품일이 아니라 그로부터 몇 달 뒤입니다. 수정 요청이 왔을 때 원작자 없이도 코드를 고칠 수 있는가. 담당자가 바뀌어도 프로그램이 계속 쓰이는가. 이 질문에 "예"라고 답할 수 있는 상태가 인수인계 가능한 코드입니다. 재고 변환 프로그램을 납품하며 우리가 지킨 네 가지 기둥을 정리합니다.
기둥 1: 동작을 증명하는 테스트
인수인계에서 테스트는 "품질 관리"가 아니라 안전망 문서입니다. 새 담당자가 코드를 고칠 때 가장 두려운 것은 "내가 뭘 깨뜨렸는지 모른다"는 상태인데, 테스트가 있으면 이 두려움이 "테스트를 돌려 보면 안다"로 바뀝니다.
특히 가치가 큰 것은 운영 버그를 고정한 테스트입니다. 우리는 실제로 겪은 진열 판정 버그(특정 상품이 첫 품목만 보고 미진열되던 문제)를 실데이터 기반 테스트 케이스로 남겼습니다. 이런 테스트는 "과거에 이런 사고가 있었고, 다시 나면 여기서 걸린다"는 사고 이력서 역할을 합니다. 몇 달 뒤의 수정자가 원작자에게 물어볼 수 없는 맥락이 코드 안에 남습니다.
테스트는 CI와 묶여야 힘이 붙습니다. 우리는 빌드 워크플로의 첫 단계에 테스트 실행을 두어 테스트가 깨진 코드로는 배포용 실행 파일이 아예 만들어지지 않게 했습니다. 인수인계 후의 수정자가 테스트를 깜빡해도 CI가 대신 기억합니다.
기둥 2: 사용자용과 개발자용, 두 벌의 문서
문서는 대상 독자가 다른 두 벌이 필요합니다. 사용자용 매뉴얼은 화면 기준으로 "무엇을 누르면 무엇이 되는지"를 다룹니다. 개발자용 문서(README)는 구조 기준으로 "어디에 무엇이 있고 어떻게 빌드하는지"를 다룹니다. 하나로 합치면 둘 다에게 불친절한 문서가 됩니다.
개발자 문서에서 가장 중요한 항목은 의외로 실행 방법과 빌드 방법입니다. 코드 설명은 코드를 읽으면 되지만 "이걸 어떻게 돌리지"는 문서 없이는 알아낼 수 없습니다. 개발 환경 세팅, 테스트 실행, 배포 빌드까지의 명령이 복사해서 실행 가능한 형태로 적혀 있어야 합니다.
기둥 3: 빌드를 사람에게서 분리
"빌드는 원작자 PC에서만 된다"는 상태는 인수인계의 최대 적입니다. 빌드 환경이 곧 암묵지이기 때문입니다. 우리는 CI(GitHub Actions)에 빌드를 맡겨 코드를 밀면 테스트가 돌고 배포용 실행 파일이 자동으로 만들어지게 했습니다.
이렇게 하면 인수인계 항목에서 "빌드 방법 전수"가 통째로 사라집니다. 새 담당자는 저장소 접근 권한만 받으면 되고 어떤 커밋에서 어떤 산출물이 나왔는지도 릴리스 이력으로 추적됩니다. 배포형 도구의 빌드 구성은 파이썬 EXE 배포 설계에서 자세히 다뤘습니다.
기둥 4: 바뀔 것을 설정으로 분리
코드에서 가장 자주 바뀌는 부분은 업무 규칙의 값입니다. 우리 사례에서는 도매상별 재고표 규칙이 그것이었습니다. 이런 값이 로직 사이에 흩어져 있으면 수정할 때마다 전체 코드를 읽어야 하지만 타입과 설정으로 분리되어 있으면 수정 범위가 명확합니다. "새 도매상 추가"가 코드 전체 이해 없이 규칙 하나 추가로 끝나는 구조가 인수인계 후 유지보수 비용을 결정합니다.
| 기둥 | 없을 때 생기는 일 | 확인 질문 |
|---|---|---|
| 테스트 | 수정이 두려워 코드가 동결됨 | 고치고 나서 깨졌는지 알 수 있는가 |
| 두 벌 문서 | 사용법·구조 문의가 원작자에게 옴 | 문서만 보고 실행·빌드가 되는가 |
| CI 빌드 | 원작자 PC가 단일 장애점이 됨 | 저장소만 있으면 산출물이 나오는가 |
| 설정 분리 | 값 하나 바꾸는 데 전체 이해 필요 | 자주 바뀌는 값이 한곳에 모여 있는가 |
인수인계 검수 체크포인트
이 글은 개발자 관점으로 썼지만 발주자에게도 쓸모가 있습니다. 납품 검수 때 소스코드와 함께 다음을 요구하세요. 테스트 실행 방법, 개발 문서, 빌드 절차(가능하면 CI), 그리고 업무 규칙이 어디에 정의되어 있는지. 이 네 가지가 갖춰진 납품물은 원작 업체와의 관계가 끊겨도 다른 개발자가 이어받을 수 있습니다. 실제로 이 기준으로 만든 납품 사례는 카페24 재고 업로드 자동화에서 볼 수 있습니다.
자주 묻는 질문
인수인계 가능한 코드의 최소 조건은 무엇인가요?
문서만 보고 실행과 빌드가 재현됩니다. 여기에 동작을 증명하는 테스트, 자주 바뀌는 업무 규칙의 설정 분리가 더해지면 원작자 없이도 수정이 가능한 상태가 됩니다. 코드 스타일보다 이 세 가지가 인수인계 비용을 좌우합니다.
문서는 어느 수준까지 쓰는 게 적당한가요?
"따라 하면 되는" 수준이 기준입니다. 사용자 매뉴얼은 화면 단위로 클릭 순서를, 개발 문서는 환경 준비부터 실행·테스트·빌드까지의 명령을 복사 실행 가능한 형태로 담으면 충분합니다. 설계 철학 같은 장문보다 절차가 재현되는지가 인수인계 문서의 품질을 결정합니다.
작은 납품 프로젝트에도 테스트와 CI가 필요한가요?
규모보다 수명이 기준입니다. 한 번 쓰고 버릴 스크립트라면 과하지만 몇 년 쓰일 업무 도구라면 수정 요청이 반드시 오고 그때 테스트와 CI가 없으면 작은 수정도 큰 위험이 됩니다. 납품 시점의 몇 시간 투자가 이후 모든 수정의 비용을 낮춥니다.
발주자가 납품 검수에서 확인할 것은 무엇인가요?
소스코드 자체보다 재현성을 확인하세요. 문서대로 따라 하면 실행이 되는지, 빌드 절차가 문서화(가능하면 자동화)되어 있는지, 테스트가 있고 돌아가는지입니다. 이 항목들이 갖춰지면 업체가 바뀌어도 시스템을 이어받을 수 있습니다.