코드를 읽는 지루함은 이제 그만! AST와 Gemini로 만드는 AI 기반 코드베이스 지도

안녕하세요, 10년 차 IT 실무자이자 테크 블로거입니다. 오랜 시간 여러 프로젝트의 코드베이스를 넘나들며 느꼈던 지독한 문제가 하나 있습니다. 새로운 프로젝트에 합류할 때마다 늘 똑같은 패턴을 보게 됩니다. 신규 개발자가 복잡한 시스템 전체를 온전히 이해하는 데 짧게는 3개월, 길게는 6개월까지 걸리는 거죠.

Copilot이나 Cursor 같은 AI 도구들이 코드 작성 속도를 획기적으로 높여준 건 분명합니다. 하지만 개발자들은 여전히 시간의 거의 절반을 코드를 읽고 탐색하는 데 씁니다. 정작 '이해'의 영역, 즉 복잡한 시스템이 어떻게 서로 맞물려 돌아가는지에 대한 통찰을 제공해주는 도구는 마땅치 않았습니다.

그래서 저는 직접 그 빈틈을 채울 도구를 만들기로 결심했습니다. 드디어 여러분께 제가 개발해 온 결과물을 공유하게 되어 정말 기쁩니다. 바로 AuraCode입니다! (라이브 데모에서 직접 경험해보는 걸 강력 추천합니다!)

🤔 AuraCode, 무엇을 해결하나요?

AuraCode는 지저분하고 문서화가 부족한 레포지토리를 대화형 시각 지도와 문맥 인식 채팅으로 바꿔주는 지능형 코드 에이전트입니다. 제가 현재까지 구현한 주요 기능들은 다음과 같습니다.

• 인터랙티브 아키텍처 캔버스 🗺️: GitHub URL만 붙여넣으면, D3.js 기반의 아름답고 인터랙티브한 방사형 트리(radial tree)를 생성해줍니다. 이를 통해 컴포넌트 간의 관계와 시스템 구조를 한눈에 파악할 수 있습니다.
• 상황 인지 채팅 & 음성 지원 🗣️: "이 인증 유틸리티를 변경하면 어떤 부분이 망가지나요?" 같은 질문을 하면 실제 코드 구조에 기반한 답변을 얻을 수 있습니다. ElevenLabs TTS 엔진과 연동해 답변을 음성으로 들을 수도 있어서, 코드를 보면서도 두 손을 자유롭게 사용할 수 있습니다.
• 스마트 온보딩 ✅: 더 이상 시대에 뒤떨어진 setup.md 파일에 의존할 필요가 없습니다. AuraCode는 스캔한 코드베이스의 아키텍처에 맞춰 구조화된 온보딩 체크리스트를 자동으로 생성해줍니다. 제가 실무에서 수많은 setup.md 파일을 보며 좌절했던 기억이 저뿐만은 아닐 겁니다. AuraCode의 온보딩 기능은 이런 고질적인 문제를 근본적으로 해결해 줍니다.
• 코드 리뷰 요약 🚀: PR(Pull Request)을 지정하면, 변경 사항(delta)을 기반으로 트렌드 분석을 실행하고 간결한 리뷰 요약을 제공합니다.

🛠️ 어떻게 작동할까요? (Under the Hood)

이 도구를 개발하면서 가장 중요했던 건 '정확한 정보 검색'과 'LLM 컨텍스트 윈도우 관리' 사이의 균형이었습니다. 코드 자체를 단순히 '평면적인 텍스트'로만 보면 호출 그래프나 의존성 체인 같은 핵심적인 구조적 관계를 모두 놓치게 되죠. 이 부분을 해결하기 위해 AuraCode는 레포지토리 규모에 따라 두 가지 다른 접근 방식을 사용합니다.

• 소규모/중규모 레포지토리: AST(Abstract Syntax Trees)를 모델의 컨텍스트 윈도우에 직접 주입합니다. 이 부분이 정말 중요합니다. 제가 실제 프로젝트에서 수많은 코드베이스를 뜯어보면서 느낀 건, 단순히 텍스트 검색으로는 절대 파악할 수 없는 '숨겨진 맥락'이 존재한다는 점이었거든요. AST를 활용하면 AI가 코드의 연결 방식을 실제 아키텍처 패턴 그대로 이해할 수 있습니다.
• 대규모 모노레포: 제가 'Lean RAG'라고 부르는 방식을 사용합니다. 이는 컨텍스트 주입 전에 가장 구조적으로 관련된 노드들을 선별적으로 추출하는 경량화된 검색 레이어입니다. 이를 통해 토큰 제한을 초과하지 않으면서도 높은 정확도를 유지할 수 있습니다.

🚀 다음 단계는?

현재 AuraCode는 사전 출시(pre-launch) 단계에 있습니다. 개인적으로 개발하고 있고 LLM 토큰 비용이 사용량에 따라 빠르게 증가하기 때문에, 현재 웨이트리스트에 등록된 선착순 50명의 개발자에게만 프라이빗 레포지토리 전체 접근 권한을 제공하고 있습니다.

하지만 데모 버전은 웹사이트에서 누구에게나 공개되어 있으니, 자유롭게 둘러보셔도 좋습니다!

사실 이 도구는 제가 거대한 레거시 코드베이스 컨설팅을 맡을 때마다 '이런 게 있으면 좋겠다'라고 간절히 바라왔던 바로 그 도구입니다.

여러분들의 생각은 어떠신가요? 보통 거대하고 문서화가 부족한 코드베이스에 새로 합류할 때 어떻게 적응하시나요? 기술 스택이나 Lean RAG 접근 방식, D3 시각화에 대해 궁금한 점이 있다면 언제든 댓글로 남겨주세요! 함께 이야기 나눌 수 있다면 좋겠습니다. 👇

---

원문: https://dev.to/tworrell/how-im-using-asts-and-gemini-to-solve-the-codebase-onboarding-problem-1la9 수집일: 2026-04-16 01:20:42