코드베이스 (Codebase)

코드베이스(Codebase)는 하나의 소프트웨어나 함께 관리하는 시스템을 이루는 소스 코드의 집합입니다. 기능 구현뿐 아니라 테스트와 빌드 설정 등 개발에 필요한 파일을 함께 가리키기도 합니다. 프로젝트 전체를 이해하거나 수정한다고 할 때의 작업 대상이며, 개별 파일이나 실행 중인 서비스 한 대보다 넓은 범위를 뜻합니다.

소프트웨어를 이루는 파일의 범위

로그인 화면에서 오류가 나더라도 원인은 화면 파일 밖에 있을 수 있습니다. 요청을 보내는 함수, 서버의 인증 처리, 데이터 형식, 관련 테스트가 함께 동작하기 때문입니다. 코드베이스를 살핀다는 말은 이 연결 관계를 따라 실제 수정 지점을 찾는다는 뜻으로 쓰입니다. 파일 이름만 열거하는 작업과 달리, 어떤 코드가 다른 코드를 호출하고 어떤 설정에 의존하는지까지 확인합니다.

GitHub의 저장소 설명은 저장소를 코드와 파일, 변경 이력을 담고 협업하는 공간으로 설명합니다. 코드베이스는 그 안에서 개발하는 코드 집합을 가리키고, 저장소는 이력과 접근 권한을 관리하는 단위입니다. 두 단어를 같은 뜻으로 쓰는 경우가 많지만, 논의하는 대상이 코드의 구조인지 저장 위치와 이력인지는 구분할 수 있습니다.

소스 코드와 함께 테스트, 패키지 의존성 목록, 실행 설정을 보관하면 다른 환경에서 동작을 재현하기 쉬워집니다. 반면 설치된 의존성 사본이나 재생성 가능한 빌드 결과가 작업 폴더에 있다고 해서 모두 직접 관리할 소스가 되는 것은 아닙니다. 코드베이스의 범위는 프로젝트가 무엇을 원본으로 관리하는지에 따라 정해집니다. 데이터나 비밀 설정처럼 별도로 공급되는 요소도 실행에는 필요할 수 있습니다.

저장소와 배포본의 구분

Twelve-Factor의 코드베이스 원칙은 버전 관리되는 하나의 코드베이스에서 여러 배포본을 만드는 구성을 설명합니다. 개발자의 로컬 실행, 테스트 환경, 운영 서비스가 서로 다른 버전의 코드를 실행하더라도 같은 이력을 공유할 수 있습니다. 이 원칙은 애플리케이션 구성에 관한 권고이므로, 모든 조직이 반드시 코드베이스 하나와 저장소 하나를 일대일로 대응시킨다는 뜻으로 확대하지 않습니다.

여러 애플리케이션을 한 저장소에서 관리하는 구조도 있고, 한 제품을 구성하는 서비스들이 각자 저장소를 쓰는 구조도 있습니다. 전자는 저장소 안의 폴더나 패키지 경계가, 후자는 서비스 사이의 인터페이스와 버전 조합이 중요해집니다. ‘코드베이스 전체를 수정한다’는 작업 요청만으로는 어느 서비스와 공통 라이브러리까지 포함되는지 정해지지 않으므로 대상 범위를 먼저 특정합니다.

배포된 웹사이트의 주소만으로 그 코드를 재현할 수도 없습니다. 어느 저장소의 어느 커밋을 빌드했는지, 어떤 의존성과 설정으로 실행했는지가 추가로 필요합니다. 같은 소스라도 빌드 시점에 적용한 설정이나 외부 서비스 상태에 따라 관찰되는 동작이 달라집니다. 오류를 조사하는 기록에는 서비스 주소와 함께 코드 버전을 남기면 원인 추적의 기준이 생깁니다.

수정 전에 확인할 작업 상태

Git 공식 용어집은 저장소와 작업 트리를 구별합니다. 작업 트리는 실제 파일을 읽고 고치는 공간이고, 저장소에는 커밋과 이력에 관한 정보가 있습니다. 파일을 고친 직후의 작업 트리는 마지막 커밋과 다를 수 있습니다. ‘같은 코드베이스를 받았다’고 해도 체크아웃한 브랜치와 아직 커밋하지 않은 변경이 다르면 실제 작업 대상은 일치하지 않습니다.

AI 코딩 도구에 프로젝트를 맡길 때도 이 차이가 작용합니다. 도구가 접근할 수 있는 폴더, 읽은 지침, 컨텍스트에 담긴 파일은 전체 코드 중 일부일 수 있습니다. 저장소를 열었다는 사실만으로 모든 코드와 실행 조건을 파악했다고 판단하기는 어렵습니다. 수정 요청에 증상과 재현 경로를 함께 주고, 제시된 변경이 관련 테스트와 호출 지점에 맞는지 확인합니다.

작업 결과는 바뀐 파일과 동작의 관계로 평가합니다. 화면의 오류를 고치면서 공통 함수의 입력 형식을 바꿨다면 다른 호출 지점도 검토 대상이 됩니다. 수정한 부분이 정상이어도 같은 함수를 쓰는 기능에서 실패할 수 있기 때문입니다. 저장소의 기존 변경을 보존하고 관련 검증 결과를 같은 커밋과 연결하면, 나중에 어떤 코드 상태를 확인했는지 다시 찾을 수 있습니다.