거대한 미지의 코드베이스에 갑자기 투입됐나요? 생존 가이드입니다

AI 요약

새 직장에 입사한 첫 주이거나, 담당자가 떠난 프로젝트를 넘겨받았거나, 오픈소스 저장소에 기여하려는 상황에서는 수천 개의 파일과 중첩된 디렉터리를 마주하게 됩니다. 이때 흔히 하는 실수는 무작위로 파일을 열고 처음부터 끝까지 읽으면서 이해가 쌓이기를 기대하는 것입니다. 글쓴이는 이런 방식으로는 정보가 연결되지 않은 채 쌓일 뿐이며, 대규모 코드베이스는 책처럼 읽을 수 없다고 말합니다. 목표는 모든 파일을 암기하는 것이 아니라 주요 구성요소가 어디에 있고 중요한 실행 경로가 어떻게 흐르는지 보여주는 지도를 만드는 것입니다. 글에서는 이 과정을 의도적으로 수행하면 일주일도 충분하다고 설명합니다.

■ 먼저 실행하고, 애플리케이션의 ‘앞문’을 찾습니다

가장 먼저 저장소를 clone하고 로컬에서 애플리케이션을 실행한 뒤 실제로 사용해야 합니다. 버튼을 눌러 보고, 로그인하고, 기능을 직접 동작시켜야 합니다. 실행 과정에서는 의존성, 환경 설정, 개발 환경의 특이점, 초기 설정에서 발생하는 마찰을 함께 확인할 수 있습니다. 글은 이런 실행 경험이 팀 안에서 구두로만 전해지는 실무 지식의 상당 부분을 빠르게 파악하게 해준다고 설명합니다.

그 다음에는 실행이 시작되는 지점을 찾아야 합니다. 애플리케이션의 main function, 서버 bootstrap, router, app entry file 등이 출발점이 될 수 있습니다. 진입점을 찾으면 임의의 파일을 헤매는 대신 그 지점에서 바깥쪽으로 실행 흐름을 따라갈 수 있습니다. 위치가 불분명하다면 package.json의 scripts, Dockerfile, README가 단서가 됩니다. 진입점은 이후의 탐색을 위한 기준점이 됩니다.

■ 파일을 넓게 읽기보다 기능 하나를 끝까지 추적합니다

글에서 가장 효과적인 방법으로 제시하는 것은 하나의 기능에 대한 vertical slice를 완성하는 것입니다. 로그인, 버튼 클릭 하나, API 호출 하나처럼 애플리케이션이 수행하는 기능을 고른 뒤 UI에서 시작해 요청을 처리하는 route와 handler, 실제 작업을 수행하는 로직, 데이터베이스 조회, 응답 반환까지 한 흐름으로 따라갑니다.

예를 들어 로그인 기능을 조사한다면 UI에서 로그인 요청이 어디서 시작되는지 찾고, 요청이 어떤 handler로 전달되는지 확인합니다. 이어서 handler가 인증 로직의 어느 부분을 호출하는지, 인증 로직이 어떤 데이터베이스 정보를 확인하는지, 결과가 어떤 경로로 다시 반환되는지를 차례로 기록합니다. 글은 이 각각의 이동 지점을 적어 두는 것만으로도 하루 동안 무작정 파일을 읽는 것보다 더 많은 정보를 얻을 수 있다고 설명합니다.

서로 무관한 파일 50개를 읽으면 50개의 단편적인 정보만 남을 수 있지만, 기능 하나를 끝까지 추적하면 해당 프로젝트의 계층 구조와 연결 방식이 드러납니다. 라우팅이 어디에 놓이는지, 비즈니스 로직을 어디에 두는지, 데이터와 어떤 방식으로 통신하는지, 각 계층에서 어떤 이름을 사용하는지 파악할 수 있습니다. 두세 개의 기능에 같은 과정을 반복하면 애플리케이션이 반복적으로 사용하는 구조적 패턴이 보이기 시작한다고 말합니다.

■ 세부 구현보다 먼저 아키텍처와 데이터를 봅니다

구현 코드를 깊이 읽기 전에 디렉터리 트리와 최상위 모듈을 살펴봐야 합니다. 사용자가 보는 UI, 애플리케이션이 수행하는 로직, 데이터가 저장되는 영역이 어디에서 나뉘는지 확인하는 과정입니다. 이는 단순히 폴더 이름을 외우는 작업이 아니라 팀이 애플리케이션을 어떻게 나눠 생각하는지 파악하는 작업입니다. 글은 약 20분 동안 폴더 구조를 살펴보면서 각 영역의 역할을 소리 내어 추측해 보라고 권합니다. 틀린 추측이 생기는 지점은 팀원에게 질문할 가치가 있는 부분이 됩니다.

또 다른 빠른 단서는 데이터 모델, 데이터베이스 스키마, 핵심 타입입니다. 대부분의 애플리케이션은 User, Order, Project와 같은 핵심 엔티티를 여러 계층으로 전달하고 변경합니다. 핵심 엔티티가 무엇인지, 서로 어떤 관계인지 이해하면 각 코드가 무엇을 대상으로 어떤 작업을 수행하는지 해석하기 쉬워집니다. 글은 데이터 구조를 코드베이스의 뼈대에 비유하며, 뼈대를 파악하면 그 위에 놓인 나머지 구현을 이해하기 쉬워진다고 설명합니다.

■ 읽는 데서 멈추지 말고 작은 변경을 합니다

코드를 읽는 것은 수동적인 활동이지만, 실제로 변경하고 결과를 관찰하는 과정에서는 시스템의 동작과 숨은 연결을 더 분명하게 배울 수 있습니다. 작은 버그를 수정하거나 로그 한 줄을 추가해 언제 실행되고 무엇을 출력하는지 확인할 수 있습니다. 안전한 범위의 변경을 적용한 뒤 무엇이 깨지는지, 그리고 예상하지 못한 다른 부분도 함께 깨지는지 살펴보면 파일만 읽어서는 알기 어려운 결합 관계를 확인할 수 있습니다.

가능하다면 실제로 작은 starter ticket을 맡아 완료하는 것도 방법입니다. 시스템을 수정하고 결과를 확인하는 동안 코드가 문서에 적힌 방식이 아니라 실제 환경에서 어떻게 동작하는지 알게 됩니다. 글은 하나를 깨뜨렸다가 고치는 경험이 긴 시간 동안 조심스럽게 읽는 것보다 더 많은 정보를 줄 수 있다고 설명합니다.

■ 사람과 저장소의 기록을 함께 활용합니다

새 코드베이스를 빠르게 파악하는 과정은 혼자 할 필요가 없습니다. 팀원에게 하나의 흐름을 설명해 달라고 요청하면, 요청이 시스템을 통과하는 실제 경로와 코드만으로는 알기 어려운 설계 배경을 짧은 시간에 들을 수 있습니다. 글에서는 20분 동안 팀원이 한 흐름을 설명해 주는 것이 혼자 코드를 조사하는 여러 시간보다 빠를 수 있다고 말합니다.

저장소의 최근 git log와 pull request도 확인해야 합니다. 최근에 어떤 영역이 활발히 바뀌는지, 팀이 변경을 검토하고 작업하는 방식이 어떤지 파악할 수 있습니다. 테스트는 코드가 해야 하는 일을 보여주는 문서 역할을 합니다. 이해하기 어려운 파일이 있다면 git blame을 사용해 해당 파일이나 줄을 추가한 커밋을 찾을 수 있습니다. 그 커밋의 변경 맥락이 코드만 읽어서는 알 수 없는 이유를 설명해 줄 수 있습니다.

■ 학습 내용을 문서로 외부화합니다

파악한 내용을 계속 기록하는 것도 핵심 단계입니다. 진입점, 인증 흐름, 결제 로직의 위치, 특정 모듈의 예외적인 동작처럼 다시 찾아야 할 내용을 하나의 문서에 정리합니다. 이렇게 하면 길을 잃을 때마다 같은 구조를 머릿속에서 다시 만들어 내지 않아도 됩니다. 동시에 이 문서는 다음 사람이 코드베이스에 적응할 때 사용할 수 있는 온보딩 문서가 됩니다.

글은 둘째 주에 이 문서를 팀과 공유하는 것도 제안합니다. 본인이 새로 익힌 내용을 정리하는 동시에 팀에서 필요성을 알고도 만들지 못했던 지도를 제공할 수 있기 때문입니다. 결론적으로 새로운 코드베이스를 빠르게 익히는 능력은 모든 파일을 읽는 속도의 문제가 아니라, 실행 가능한 작업 모델을 의도적으로 만드는 방법의 문제라고 설명합니다. 애플리케이션을 실행하고, 진입점을 찾고, 실제 기능을 끝까지 추적하고, 구조와 데이터를 먼저 파악하고, 작은 변경을 적용하고, 사람에게 질문하고, 알아낸 내용을 지도처럼 기록하는 순서가 이 글의 핵심 절차입니다.

원문: dev.to / 번역·요약: Trawling