AI로 레거시 코드 숲을 그려보자: CodeBoarding 코드베이스 분석 활용기

레거시 코드 처음 열어보고 몇 분 동안 멍하니 파일 구조만 쳐다본 적 있나요?

저는 솔직히 자주 있습니다. 특히 수년간 이어진 프로젝트나, 내가 아닌 다른 팀이 만들던 서비스에 투입될 때면 코드 한 줄 치기도 전에 구조 파악만 하루 종일 하게 되죠.

최근에 그런 상황을 조금이라도 덜 고통스럽게 만들어 줄 도구를 하나 발견했는데, 바로 CodeBoarding이라는 오픈소스 도구였습니다.

이 친구는 단순히 코드에 대해 답을 해주는 AI 도우미라기보다, 코드베이스 전체의 지도를 그려주는 탐험 가이드에 가깝습니다.

정적 분석으로 코드의 제어 흐름을 뽑아내고, LLM으로 그걸 이해하기 좋은 다이어그램으로 바꿔주는 방식인데요. 실제로 써보니 코드 이해 방식 자체가 살짝 달라지는 경험이라, 개발자가 아니더라도 서비스 구조를 이해해야 하는 사람이라면 꽤 매력적으로 느낄 만한 도구라서 정리해 봅니다.

🧭 CodeBoarding이 해결하려는 진짜 문제

소프트웨어 개발에서 제일 지치는 순간 중 하나가 바로 남이 써놓고 사라진 레거시 코드와 싸울 때입니다.

문서도 없고, 설계 다이어그램도 없고, 심지어 코드 주석도 부실한데, 서비스는 이미 프로덕션에서 잘 돌아가고 있는 그런 상황이요.

보통 이런 상황에서 우리가 쓰는 도구는 몇 가지 패턴으로 정리됩니다.

함수 검색, call hierarchy, IDE의 navigate 기능, 그리고 요즘은 코드와 대화하는 AI 어시스턴트까지 추가됐죠.

하지만 이 도구들의 공통적인 한계가 있습니다. 대부분 질문을 잘해야 답이 나온다는 점입니다.

특정 함수가 뭘 하는지, 이 API가 어디서 쓰이는지, 이 파일이 어떤 책임을 갖는지 같은 질문에는 꽤 잘 답해 줍니다.

그런데 정작 중요한 것은 이런 질문 사이의 맥락, 다시 말해 프로젝트 전체의 구조와 흐름입니다.

CodeBoarding이 노리는 지점이 바로 여기입니다.

이 도구는 하나의 함수, 하나의 파일이 아니라 코드베이스 전체의 구조를 먼저 시각적으로 보여준 다음, 세부로 내려갈 수 있게 도와줍니다.

즉, 나무가 아니라 숲부터 보여주고, 필요할 때 나무로 확대해 들어가는 관점 전환을 제공하는 셈이죠.

공식 홈페이지도 한 번 보면 감이 더 잘 옵니다.
https://www.codeboarding.org

🧠 Static Analysis + LLM, 왜 이 조합이 중요한가

개인적으로 CodeBoarding에서 가장 마음에 들었던 부분은 정적 분석과 LLM을 묶어 쓰는 방식입니다.

요즘 나오는 AI 코드 도구들을 보다 보면, LLM에 거의 모든 걸 맡겨버리는 경우가 많습니다. 그러다 보니 모델이 자신 있게 틀린 소리를 하는 경우도 자주 보게 됩니다.

CodeBoarding은 이걸 정면 돌파합니다.

핵심 구조 분석은 정적 분석, 즉 코드 자체를 실행하지 않고 제어 흐름 그래프와 모듈 간 관계를 분석해서 수행합니다.

여기서 제어 흐름 그래프를 뽑아낸다는 말은, 코드가 어떤 순서로 실행되고, 어떤 함수가 어떤 함수를 호출하는지를 추적해서 구조를 그래프로 그린다는 뜻입니다.

이 과정은 LLM이 아니라 실제 코드 분석기에서 처리하기 때문에 다음과 같은 장점이 있습니다.

코드 구조는 환각이 아니라 사실 기반으로 나온다

타입, 모듈, 호출 관계 등은 실제 코드 기준으로 정확하게 수집된다

LLM은 이 이미 확보된 구조를 이해하기 쉽게 요약하고 설명하는 역할에 집중한다

즉, LLM이 상상력으로 구조를 만들어 내는 게 아니라, 정적 분석으로 이미 확보된 정보 위에서만 말하도록 설계된 구조입니다.

이 지점이 제가 이 도구를 신뢰해볼 만하다고 느낀 첫 번째 포인트였습니다.

CodeBoarding의 GitHub 저장소도 한 번 구경해볼 만합니다.
https://github.com/CodeBoarding/CodeBoarding

🗺 프로젝트를 다이어그램으로 보는 경험

CodeBoarding이 만들어내는 결과물의 중심에는 다이어그램이 있습니다.

단순한 박스-화살표 그림이 아니라, Mermaid.js 형식으로 구조를 표현해 줍니다.

Mermaid는 텍스트로 다이어그램을 정의할 수 있는 도구라, GitHub 리드미나 위키, 문서화 시스템에 붙이기에도 좋습니다.

Mermaid가 어떤 느낌인지 궁금하면 여기서 직접 구경해 볼 수 있습니다.
https://mermaid.js.org

CodeBoarding은 정적 분석으로 추출한 제어 흐름과 모듈 관계를 기반으로 이런 Mermaid 다이어그램을 생성해 줍니다.

중요한 건, 이 다이어그램이 단순히 예쁘기만 한 그림이 아니라 실제로 탐색 가능한 구조라는 점입니다.

특정 모듈에서 어떤 서비스가 시작되는지 한눈에 보이고

API 엔드포인트에서부터 DB 접근까지 흐름을 쫓아가 볼 수 있고

레이어드 아키텍처처럼 보이지 않던 코드도 시각적으로 레이어가 떠오르게 정리됩니다

저는 이런 다이어그램을 볼 때 두 가지 생각이 동시에 들었습니다.

하나는, 이 정도 그림을 예전에는 정말 사람이 일일이 그렸다는 사실.

다른 하나는, 코드가 더러울수록 이 다이어그램이 더 절실해진다는 사실입니다.

프로젝트가 커져갈수록 파일명만 보고 구조를 이해하기가 어려워집니다.

이때 시각적인 지도를 먼저 본 뒤, 세부 코드로 들어가는 흐름은 확실히 뇌에 부담을 덜 주는 느낌이었어요.

💬 기존 코드 AI 도구들과 뭐가 다를까

요즘 코드와 대화하는 AI 도구는 너무 많습니다.

코드 RAG, 코드 어시스턴트, GitHub Copilot, Claude Code, Cursor 같은 에디터까지, 종류도 정말 다양하죠.

이 도구들의 공통적인 사용 패턴은 이런 식입니다.

• 이 함수가 하는 일 설명해줘

• 이 파일은 어떤 역할이야

• 이 API는 어디서 호출돼

• 이 에러가 나는 이유 추측해줘

물론 이런 질의응답은 실무에서 자주 쓰이고, 저도 엄청 애용합니다.

하지만 이 방식은 기본적으로 국소적인 질문에 최적화되어 있습니다.

특정 함수, 특정 파일, 특정 버그 상황 같은 부분적 컨텍스트에 대한 답을 잘 줍니다.

CodeBoarding은 이와 다른 관점을 취합니다.

질문 이전에, 먼저 구조적인 지도를 생성합니다.

그래서 이렇게 말할 수 있습니다.

• 기존 도구: 질문을 잘 해야 답을 얻는 방식

• CodeBoarding: 질문하기 전에 전체 지도를 먼저 깔아주는 방식

개인적으로 느낀 차이는 이렇습니다.

다른 AI 도구들은 레이저 포인터처럼 특정 지점을 강하게 비춰주는 느낌이고,

CodeBoarding은 위에서 내려다보는 조명 역할을 하는 느낌에 가깝습니다.

둘은 경쟁 관계라기보다 서로 보완 관계입니다.

실제로는 CodeBoarding으로 구조를 보고, 다른 AI 도구로 개별 로직을 파고드는 조합이 꽤 괜찮습니다.

🧩 VS Code, GitHub Actions, MCP… 실전 통합 포인트

아무리 좋아 보이는 도구라도 실제 워크플로우에 자연스럽게 녹아들지 못하면 오래 못 쓰게 됩니다.

이 점에서 CodeBoarding이 재미있는 선택지를 여러 개 던져줍니다.

먼저 VS Code 확장입니다.

VS Code를 메인 에디터로 쓰신다면, 확장을 설치해서 IDE 안에서 바로 다이어그램을 띄울 수 있습니다.

코드를 읽다가 구조가 헷갈리는 지점에서 바로 다이어그램을 열어볼 수 있는 경험은 생각보다 꽤 편합니다.

VS Code 마켓플레이스 링크는 여기입니다.
https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding

두 번째는 GitHub Actions 연동입니다.

이건 개인적으로 팀 개발 환경에 특히 유용하다고 느꼈습니다.

CI/CD 파이프라인에 CodeBoarding을 넣어두면, 코드가 변경될 때마다 아키텍처 다이어그램과 문서를 자동으로 갱신할 수 있습니다.

예를 들어 이런 흐름이 가능하겠죠.

• PR이 머지될 때마다 최신 구조 다이어그램을 생성

• 리포지토리의 docs 폴더나 Wiki를 자동 업데이트

• 변경된 아키텍처를 PR 검토 과정에서도 바로 참고

GitHub Actions 마켓플레이스 링크는 이쪽입니다.
https://github.com/marketplace/actions/codeboarding-diagram-first-documentation

세 번째는 MCP 서버입니다.

MCP(Model Context Protocol)를 지원하는 Claude, Cursor 같은 AI 도구와 연결해서,

코드베이스의 압축된 구조 정보를 AI 어시스턴트에게 제공할 수 있습니다.

즉, 단순히 파일 텍스트를 잘라서 넣는 게 아니라, 정적 분석과 요약을 거친 구조 정보를 컨텍스트로 함께 넣는 방식입니다.

이건 장기적으로 AI 개발 환경이 가야 할 방향과도 맞닿아 있다고 느꼈습니다.

MCP 서버 구현은 여기서 확인할 수 있습니다.
https://github.com/CodeBoarding/CodeBoarding-MCP

🐍 Python 기반 설치와 사용 흐름

CodeBoarding은 Python 기반 환경에서 동작합니다.

공식적으로는 uv 패키지 매니저를 활용하는 흐름을 추천하고 있고, 로컬 가상 환경을 만들어서 필요한 구성 요소를 세팅하는 방식입니다.

대략적인 흐름은 이런 느낌입니다.

1. uv 설치 여부 확인

2. uv sync로 의존성 동기화

3. 가상 환경 활성화

4. 설정 스크립트 실행

5. 환경 변수 설정 후 분석 실행

구체적인 명령어와 설정법은 GitHub 저장소의 가이드를 참고하는 게 가장 안전합니다.

문서가 꽤 잘 정리된 편이라, Python 환경에 익숙하다면 큰 어려움 없이 따라갈 수 있는 수준이었습니다.

다만, 여기서 하나 짚고 싶은 건 이 도구가 아직은 개발자 친화적인 단계에 있다는 점입니다.

완전 노코드 느낌으로 클릭 몇 번에 해결되는 도구라기보다는,

어느 정도 터미널에 익숙하고, 프로젝트 설정을 만지작거리는 데 거부감이 없는 사람들에게 더 잘 맞습니다.

🧱 레거시 온보딩, 문서화, 시스템 이해에 어떻게 쓸 수 있을까

제가 이 도구를 보면서 가장 먼저 떠올린 사용처는 세 가지였습니다.

첫 번째는 신규 팀원 온보딩입니다.

새로 들어온 개발자에게 가장 필요한 건 코드 구조를 빠르게 이해할 수 있는 지도입니다.

기존에는 시니어 개발자가 화이트보드에 그림을 그려주고, 구두로 설명하는 게 전부였다면,

이제는 실제 코드베이스에서 바로 뽑아낸 다이어그램을 기반으로 설명할 수 있습니다.

두 번째는 문서 자동화입니다.

대부분의 팀은 문서와 코드가 금방 어긋나기 시작합니다.

누구나 알지만 아무도 제대로 해결하지 못한 고질적인 문제죠.

CodeBoarding을 GitHub Actions와 묶으면, 코드 변경에 맞춰 구조 다이어그램과 상위 수준 설명을 반복적으로 업데이트할 수 있습니다.

물론 이것만으로 완벽한 설계 문서가 만들어지진 않겠지만,

기본 골격을 자동으로 유지해준다는 점만 해도 유지보수 효율을 꽤 높일 수 있습니다.

세 번째는 시스템 구조 파악입니다.

특히 MSA나 복잡한 모듈 구조를 가진 서비스에서,

각 컴포넌트가 어떤 흐름으로 연결되어 있는지, 어디서 어디로 호출이 이어지는지 시각적으로 보는 것은 상당히 큰 도움이 됩니다.

이건 개발자뿐 아니라, 기획자나 아키텍트, 심지어는 기술에 관심 있는 PM에게도 유용한 그림입니다.

텍스트 위주의 설계서보다 다이어그램이 훨씬 빨리 이해되는 경우가 많으니까요.

🧪 개인적으로 느낀 장단점과 한계

이런 도구를 볼 때 저는 항상 세 가지를 따져봅니다.

• 실제 내 워크플로우에 녹아들 수 있는가

• 장기적으로 쓸 만한 구조인가

• AI에 너무 기대지 않고 사실 기반을 유지하는가

CodeBoarding은 이 세 가지 중 두 개는 상당히 잘 잡고 있다고 느꼈습니다.

정적 분석 기반이라는 점에서 사실 기반은 탄탄하고,

GitHub Actions와 VS Code 연동이라는 부분도 실사용에 필요한 축을 잘 건드리고 있습니다.

다만, 몇 가지 현실적인 제약도 보입니다.

먼저, 도입 장벽입니다.

개인 프로젝트보다 중대형 프로젝트에서 더 빛나는 도구인데,

정작 그런 프로젝트일수록 새로운 도구를 도입하는 절차가 간단하지 않습니다.

CI에 넣고, 팀에 설명하고, 문서화 흐름까지 바꾸려면 누군가가 꽤 강하게 추진해야 합니다.

또 하나는, 다이어그램의 품질과 해석 문제입니다.

구조가 복잡한 프로젝트일수록 자동으로 생성한 다이어그램이 너무 복잡해질 수 있습니다.

이때는 결국 사람 손으로 일부 레이어를 나누고, 관심 영역을 잘라내서 보여주는 작업이 필요할 수 있습니다.

그리고 마지막으로, 이 도구가 완성된 답이 아니라는 점도 분명합니다.

코드베이스를 이해하는 일은 여전히 사람의 몫이고,

CodeBoarding은 그 과정을 단축시키는 좋은 도우미에 가깝습니다.

📚 비슷한 흐름의 도구들과의 연결점

CodeBoarding을 보면서 떠오른 다른 흐름의 도구들도 몇 가지 있습니다.

AI가 코드 리뷰를 도와주는 도구들, 레거시 코드를 현대화하는 에이전트, 보안 관점의 코드 분석 도구 등입니다.

예를 들어, 이런 흐름들이 있습니다.

• ARM에서 개발한 Metis처럼 AI 기반 보안 코드 리뷰 도구

• 레거시 코드를 현대화하는 L2M 같은 터미널 기반 에이전트

• AI가 작성한 코드를 다시 AI가 리뷰하는 Quibbler 같은 에이전트

이 도구들이 다루는 문제는 조금씩 다르지만, 공통적으로 느껴지는 건 하나입니다.

이제 AI는 코드 한 파일을 잘 만들어주는 수준을 넘어서,

코드베이스 전체를 이해하고 관리하는 방향으로 진화하고 있다는 점입니다.

CodeBoarding은 그 중에서도 구조 이해와 문서화에 특화된 축을 잡고 있고,

이 부분은 앞으로도 꽤 중요한 영역으로 남을 거라고 생각합니다.

⚖️ MIT 라이선스와 오픈소스라는 점이 가지는 의미

CodeBoarding은 MIT 라이선스로 공개된 오픈소스 프로젝트입니다.

이 말은 개인 프로젝트에서든, 회사 서비스에서든, 상업적인 용도로도 자유롭게 활용할 수 있다는 뜻입니다.

라이선스 전문은 여기서 확인할 수 있습니다.
https://github.com/CodeBoarding/CodeBoarding/blob/main/LICENSE

저는 이런 타입의 도구가 오픈소스로 나왔다는 점이 꽤 중요하다고 봅니다.

코드베이스 분석 도구는 결국 회사의 핵심 자산인 소스 코드 전체를 다뤄야 하기 때문에,

클로즈드 SaaS 형태의 도구보다 오히려 오픈소스, 자체 호스팅 가능한 도구가 더 마음 편할 때가 많습니다.

특히 내부망에서만 돌려야 하는 프로젝트라면, 이런 오픈소스 도구의 가치가 훨씬 커집니다.

🔍 앞으로의 코드 이해 방식이 바뀔까? (개인적인 생각)

개발자로 일하면서 한 가지 확신하게 된 건,

코드를 잘 짜는 능력만큼이나 코드를 빨리 이해하는 능력이 중요하다는 점입니다.

특히 실무에서는 후자가 전자보다 훨씬 더 자주 요구됩니다.

그런 의미에서 CodeBoarding 같은 도구는 꽤 상징적인 방향을 보여준다고 느꼈습니다.

• 지금까지: 사람 머리와 IDE 기능에 의존해서 구조를 복원

• 이후에는: 정적 분석 + AI로 구조를 먼저 시각화한 뒤, 사람은 그 위에서 판단

물론, 모든 프로젝트에 당장 이런 도구를 도입하자는 얘기는 아닙니다.

하지만 최소한, 이제 코드베이스를 보는 기본 단위가 파일 리스트에서 다이어그램으로 조금씩 이동할 거라는 생각은 듭니다.

개인적으로는 이런 식으로 써보면 좋겠다고 생각합니다.

• 새로운 레거시 프로젝트에 들어간다? CodeBoarding으로 구조 다이어그램부터 뽑아본다

• 팀 내에서 설계 문서를 유지하기 어렵다? GitHub Actions로 기본 구조 문서는 자동화한다

• AI 코딩 어시스턴트를 쓰고 있다? MCP를 통해 구조 정보를 함께 주는 방향을 검토해본다

결국 중요한 건 도구가 아니라, 이 도구를 통해 우리가 어떤 방식으로 코드를 이해하게 되는가입니다.

CodeBoarding은 그 방식에 작은 변화의 시그널을 던지는 도구 같다는 느낌이 들었습니다.

✅ 마무리: 이런 분들에게 특히 추천하고 싶습니다

정리해보면, CodeBoarding은 이런 키워드로 요약할 수 있습니다.

• 정적 분석 + LLM 하이브리드 코드베이스 분석 도구

• Mermaid.js 기반 인터랙티브 다이어그램 생성

• VS Code, GitHub Actions, MCP 등 개발 환경 통합 지원

• MIT 라이선스 오픈소스, 상업적 활용 가능

그리고 제 기준에서 이런 분들에게 특히 한번 써보시라고 추천하고 싶습니다.

• 레거시 프로젝트의 구조를 파악해야 하는 개발자

• 팀 온보딩 문서와 설계 다이어그램을 유지하는 역할을 맡은 사람

• 코드베이스 전체 구조를 기반으로 AI 개발 환경을 고도화해보고 싶은 팀

• 서비스 아키텍처를 빠르게 이해해야 하는 PM, 테크 리드, 아키텍트

관심이 생겼다면, 이 두 링크부터 천천히 살펴보면 좋습니다.

공식 홈페이지
https://www.codeboarding.org

GitHub 저장소
https://github.com/CodeBoarding/CodeBoarding

실제로 한 번 자기 프로젝트에 적용해서 다이어그램을 뽑아보면,

지금까지 익숙했던 코드 읽기 방식과는 조금 다른 감각을 경험하게 될 겁니다.

개인적으로는 이 방향이 앞으로의 코드 이해 방식에서 점점 더 중요한 축이 될 거라고 보고 있습니다.