원본: GeekNews — CodeBoarding, 코드베이스용 인터랙티브 아키텍처 다이어그램
한 줄 요약: 정적 분석과 LLM 추론을 결합해 코드베이스의 아키텍처 다이어그램을 자동 생성하는 오픈소스 도구로, AI가 코드를 빠르게 생성하는 시대에 "코드 지도"를 유지하는 문제를 해결한다.
---
Claude Code로 빠르게 만들었는데 두 달 뒤에 못 읽겠더라
ClipLab 초기 버전을 Claude Code로 만들 때는 정말 빨랐습니다.
대화하듯 기능을 추가하고, 오류가 나면 바로 물어보고, 배포까지 며칠이면 됐습니다. 문제는 두 달 뒤에 새 기능을 추가하려고 코드를 열었을 때 생겼습니다.
"이 함수가 어디서 호출되지?" "이 모듈이 왜 여기 있지?" AI가 기능 단위로 빠르게 짜다 보니 전체 흐름보다 각 부분이 동작하는지에 집중했고, 아키텍처가 머릿속에 없었습니다.
CodeBoarding이 이 문제를 정확히 짚습니다.
---
코드가 커질수록 "지도"가 필요한 이유
혹시 이런 상황 겪어본 적 있으신가요?
버그가 생겼는데 어느 파일에서 왔는지 찾는 데 30분이 걸립니다. 새 기능을 추가하려고 기존 코드를 파악하는 데 코딩보다 더 많은 시간이 걸립니다. 바이브코딩의 속도 이점이 유지보수 비용으로 그대로 돌아오는 순간입니다.
CodeBoarding이 하는 일은 이겁니다.
스킬 1: 코드베이스를 자동으로 지도로 만든다
정적 분석으로 코드 구조를 파악하고, LLM이 고수준 맥락을 추론합니다. 결과물로 `.codeboarding/` 폴더에 Mermaid 다이어그램과 Markdown 문서가 생깁니다. 어떤 모듈이 어떤 역할을 하고, 어떻게 연결되어 있는지 한눈에 보입니다.
스킬 2: 코드가 바뀌면 지도도 따라서 갱신된다
증분 업데이트를 지원합니다. 전체를 다시 분석하지 않고 변경된 부분만 재분석합니다. "이 기능 추가하고 나서 전체 구조가 어떻게 바뀌었나?"를 PR 단계에서 바로 확인할 수 있습니다.
스킬 3: 기술 부채를 커지기 전에 잡는다
AI가 만든 코드를 시스템 맥락과 함께 리뷰할 수 있습니다. "이 변경이 전체 아키텍처에서 어떤 위치인가?"를 보면서 리뷰하면 숨어있는 기술 부채를 사전에 차단할 수 있습니다.
---
QR 앱 코드에 붙여봤을 때
QR 근태관리 앱 레포지토리에 CodeBoarding을 돌려봤습니다.
예상보다 구조가 복잡하게 얽혀 있었습니다. 인증 로직이 두 곳에 나뉘어 있었고, Google Sheets 연동 코드가 여러 파일에서 중복 호출되고 있었습니다. Claude Code가 기능이 필요할 때마다 그 자리에서 추가하다 보니 생긴 구조였습니다.
다이어그램을 보기 전에는 "그냥 돌아가고 있으니까 괜찮겠지"라고 생각했는데, 지도로 보니까 정리가 필요한 부분이 한눈에 들어왔습니다.
Claude Code로 바이브코딩을 할 때 CLAUDE.md에 규칙을 적어두는 것처럼, CodeBoarding으로 아키텍처 지도를 최신 상태로 유지하는 것도 같은 역할을 합니다. AI가 전체 맥락을 알고 코드를 짜게 하는 것. 그래야 빠르게 만들면서도 나중에 읽을 수 있는 코드가 됩니다.
빠르게 만드는 것과 나중에 고칠 수 있는 것, 두 가지를 동시에 챙기고 싶다면 코드 지도를 유지하는 습관이 필요합니다.