큰 코드베이스에서 완벽한 이해보다 중요한 것

큰 코드베이스에서 완벽한 이해보다 중요한 것

AI 뉴스 썸네일

수천만 줄짜리 시스템을 한 사람이 모두 이해하기는 어려워요. 큰 코드베이스에서 필요한 능력은 모든 코드를 외우는 일이 아니라, 지금 바꿀 영역을 충분히 좁히고 안전하게 확인하는 일이에요.

728x90

핵심 요약

구분	핵심	왜 볼 만한가요
대규모 개발	부분적으로 정확한 이해만으로도 실무를 진행할 수 있어요	시스템 규모가 커질수록 완전한 이해를 기다리는 비용이 커져요
레거시 복구	하나의 실행 흐름을 끝까지 추적한 뒤 범위를 넓혀요	담당자가 떠난 코드도 단계적으로 다시 맡을 수 있어요
변경 전략	전체 재작성보다 작은 단위의 교체가 현실적이에요	사용자와 예외 동작을 보존하면서 위험을 줄일 수 있어요
AI 코딩	LLM은 탐색을 빠르게 하지만 검증을 대신하지 못해요	빠른 설명과 실제 동작 사이의 차이를 테스트로 확인해야 해요

1. 큰 코드베이스는 부분적으로 이해하며 다뤄요

Sean Goedecke는 작은 팀의 코드와 대규모 조직의 코드를 같은 기준으로 평가하면 안 된다고 봐요. 구성원이 적고 코드 규모가 작다면 전체 구조를 머릿속에 담을 수 있어요. 반면 검색 엔진이나 대형 협업 서비스처럼 수천만 줄이 쌓인 시스템에서는 팀 전체도 모든 동작을 알기 어려워요. 이때 부분적 이해는 준비가 덜 된 상태가 아니라 현실적인 작업 조건이에요. 1

글은 Peter Naur의 1985년 논문 「Programming as Theory Building」도 다시 살펴봐요. Naur는 프로그래머가 코드와 함께 프로그램에 관한 머릿속 이론을 만든다고 설명했어요. 원래 팀이 모두 떠나 그 이론이 사라지면 기존 코드를 버리고 새로 만드는 편이 낫다는 주장도 폈어요. 하지만 사용자가 오래 쓴 대규모 시스템에는 문서에 적히지 않은 예외와 특이 동작이 쌓여요. 처음부터 다시 만들면 이런 동작을 놓치기 쉬워요. 2

현실적인 재작성은 기존 시스템을 한 번에 폐기하는 방식과 거리가 있어요. 먼저 경계를 나누고, 격리할 수 있는 작은 부분부터 교체해요. 기존 코드에 안전하게 손댈 수 없다면 새 시스템으로 옮기는 과정도 통제하기 어려워요. 전체 재작성보다 점진적 교체가 자주 선택되는 이유예요.

담당자가 모두 떠난 코드베이스도 되살릴 수 있어요. 한 기능의 요청이 어디로 들어오고 어떤 데이터를 거쳐 어떤 결과를 내는지 끝까지 추적해요. 그다음 작은 변경을 넣고 테스트, 로그, 지표로 예상과 실제 결과를 비교해요. 확인된 영역이 늘어나면 변경 범위도 조금씩 넓힐 수 있어요. 코드 전체를 먼저 읽겠다는 목표보다 훨씬 구체적인 접근이에요.

LLM 기반 코딩 도구는 이 과정의 탐색 시간을 줄일 수 있어요. 낯선 함수의 호출 관계를 설명하거나 관련 파일 후보를 찾는 데 유용해요. 다만 생성된 설명이 실제 런타임 동작과 같다는 보장은 없어요. 테스트 결과, 운영 로그, 타입과 인터페이스 같은 확인 가능한 근거를 함께 봐야 해요. 빠른 요약은 출발점이고, 변경의 안전성은 검증 과정에서 확보해요.

왜 중요한가요

완전한 이해를 목표로 삼으면 조사 범위가 끝없이 커질 수 있어요. 변경하려는 흐름, 실패했을 때의 영향, 되돌리는 방법을 먼저 정하면 필요한 이해의 경계가 선명해져요. 신규 기능을 넣을 때는 입력과 출력, 데이터 변경, 외부 의존성부터 확인해요. 장애 수정이라면 재현 조건과 로그, 최근 변경 내역을 먼저 좁혀요.

팀 차원에서는 개인의 기억보다 확인 수단을 남기는 편이 오래가요. 실행 가능한 테스트, 관측 가능한 로그, 작은 배포 단위, 명확한 소유권이 있으면 새 담당자가 더 빨리 판단할 수 있어요. 문서는 설계를 모두 설명하는 백과사전보다 자주 발생하는 작업과 위험 구간을 알려주는 지도에 가까울 때 쓸모가 있어요.

부분적 이해가 무모한 변경을 뜻하지는 않아요. 모르는 범위를 표시하고, 가정을 테스트하며, 실패 비용이 작은 순서로 움직이는 방식이에요. 코드베이스가 클수록 좋은 엔지니어링은 모든 것을 안다는 자신감보다 어디까지 확인했고 무엇을 아직 모르는지 구분하는 능력에 가까워요. 2

참고 자료

1. 코드베이스를 완전히 이해하지 못해도 괜찮은 이유 — GeekNews
2. In defense of not understanding your codebase — Sean Goedecke