처음 보는 코드베이스, 왜 이렇게 막막할까요
새 회사에 입사했거나 레거시 프로젝트를 물려받았을 때, 클론 받고 폴더를 열었는데 파일이 수천 개예요. 어디서부터 봐야 할지 몰라서 아무 파일이나 열었다가, 거기서 import된 파일로 넘어가고, 또 거기서 다른 파일로 넘어가다 보면 한 시간 뒤엔 내가 뭘 찾고 있었는지도 잊어버려요. 이 경험, 다들 한 번쯤 있으시죠?
Simon Smart라는 개발자가 쓴 글이 이 문제를 딱 한 문장으로 짚어요. '코드가 미로라면, 똑똑한 개발자는 지도를 만든다.' 미로에서 빠져나오는 방법은 더 빨리 뛰는 게 아니라 지도를 그리는 거라는 얘기예요. 코드도 마찬가지거든요. 더 열심히 파일을 여는 게 아니라, 구조를 한 장으로 정리하는 게 먼저예요.
왜 '지도'가 필요한가: 우리 머리는 생각보다 작아요
이게 뭐냐면, 사람의 작업 기억은 한 번에 대여섯 개 정도밖에 못 들고 있어요. 함수 A가 B를 부르고, B가 C를 부르고, C가 다시 A의 상태를 바꾸는 구조를 머릿속으로만 추적하면 금방 한계에 부딪혀요. 이걸 인지 부하라고 하는데요. 지도는 이 부하를 머리 밖으로 꺼내는 도구예요. 한 번 그려두면 다시 계산할 필요 없이 '아, 이 요청은 여기로 들어가서 저기로 나가지' 하고 바로 떠올릴 수 있거든요.
또 하나 중요한 점은, 지도는 '무엇을 무시해도 되는지'를 알려줘요. 코드베이스의 80%는 내가 지금 하려는 작업과 관련이 없어요. 지도가 있으면 그 80%를 마음 편히 건너뛸 수 있고, 관련 있는 20%에만 집중할 수 있어요.
지도는 어떻게 그리나요
거창한 도구가 필요한 게 아니에요. 글에서 강조하는 것도 '완벽한 문서'가 아니라 '나를 위한 스케치'거든요. 실무에서 통하는 순서를 정리해볼게요.
1. 진입점부터 찾으세요. 웹 서버라면 라우터 파일, CLI라면 main 함수, 프론트엔드라면 루트 컴포넌트예요. 요청이 처음 들어오는 문을 찾으면 그 다음은 물 흐르듯 따라갈 수 있어요.
2. 핵심 타입 다섯 개를 고르세요. 어떤 코드베이스든 중심이 되는 데이터 모델이 몇 개 있어요. 쇼핑몰이면 User, Order, Product 정도겠죠. 이 타입들이 어디서 만들어지고 어디서 바뀌는지만 알아도 절반은 이해한 거예요.
3. 데이터 흐름을 한 줄로 써보세요. 'HTTP 요청이 컨트롤러를 거쳐 서비스, 리포지토리, DB 순서로 흘러간다' 처럼요. 이 한 줄이 나중에 어떤 파일을 열어야 할지 결정하는 기준이 돼요.
4. 도구의 도움을 받으세요. JavaScript라면 madge나 dependency-cruiser로 의존성 그래프를 뽑을 수 있고, Python이면 pydeps가 있어요. 규모가 크면 Sourcegraph 같은 코드 검색 도구가 '이 함수를 누가 부르나'를 즉시 알려줘요. 아키텍처를 정식으로 그리고 싶다면 C4 모델이라는 방식이 있는데, 시스템 전체에서 시작해 컨테이너, 컴포넌트, 코드 순으로 확대해가며 그리는 방법이에요.
5. 지도를 코드 옆에 두세요. 위키에 올려두면 금방 잊혀요. 저장소 안의 docs 폴더에 Mermaid 다이어그램으로 넣어두면 코드 리뷰할 때 같이 갱신되고, 검색도 돼요.
지도는 결국 '결정'의 기록이에요
글에서 또 하나 짚는 게, 지도에는 구조뿐 아니라 '왜 이렇게 만들었는지'가 들어가야 한다는 점이에요. 이걸 ADR(Architecture Decision Record, 아키텍처 결정 기록)이라고 부르는데요. '왜 여기서 Redis를 쓰지 않고 DB 폴링을 했나' 같은 질문에 답이 남아 있으면, 후임자가 그 코드를 함부로 걷어내다 사고 치는 일이 줄어요.
요즘은 사람보다 AI가 먼저 지도를 찾아요
이 글이 2025년에 나왔지만 지금 다시 읽히는 이유가 있어요. Claude Code나 Cursor 같은 코딩 에이전트에게 프로젝트를 맡겨보신 분은 아실 거예요. 에이전트도 처음 보는 코드베이스에서 똑같이 헤매거든요. 그래서 CLAUDE.md나 AGENTS.md 같은 파일에 '이 프로젝트는 이런 구조고, 진입점은 여기고, 테스트는 이렇게 돌려' 하고 적어두면 결과 품질이 확 달라져요. 결국 사람을 위한 지도가 곧 AI를 위한 지도이기도 한 거예요. 지도를 잘 그리는 습관이 온보딩 문서이자 에이전트 설정 파일이 되는 시대인 셈이죠.
한국 개발자에게
SI 프로젝트나 오래된 서비스를 물려받는 일이 유독 많은 환경이잖아요. 문서가 없다고 한탄하기보다, 내가 헤맨 만큼 지도를 남기면 다음 사람의 일주일을 하루로 줄여줄 수 있어요. 그리고 그 지도는 다음 사람이 AI일 수도 있고요.
여러분은 새 코드베이스를 맡으면 제일 먼저 뭘 하세요? 지도를 남겨서 도움이 됐던 경험, 혹은 지도가 없어서 고생했던 경험이 있다면 들려주세요.
🔗 출처: Hacker News