[심층분석] 코드 20만 줄 앞에서 막막했던 적 있나요? 코드베이스를 지식 그래프로 바꿔주는 Understand-Anything

새 팀에 합류한 첫날, 그 막막함을 기억하시나요?

혹시 이런 경험 있으세요? 새 회사, 새 팀에 들어갔는데 첫날 받은 게 IDE 셋업 가이드랑 "일단 코드 좀 보면서 익혀보세요"라는 말 한마디. 그런데 막상 IDE를 열어보니 파일이 수천 개고, 폴더 구조는 미로 같고, main.py 하나 열었더니 거기서 import하는 모듈만 50개가 넘어요. 어디부터 봐야 할지 정말 막막하죠.

이게 진짜 신입의 통과의례처럼 여겨지는데요, 사실 시니어들도 마찬가지예요. 회사를 옮기거나, 인수합병으로 다른 팀 코드를 떠안거나, 오픈소스에 기여하려고 처음 보는 레포를 열었을 때 "이게 다 뭐냐..." 하는 순간이 옵니다. 코드 20만 줄짜리 프로젝트에 새로 들어간다고 상상해보세요. README는 3년 전에 멈춰 있고, 문서는 위키 어디엔가 흩어져 있고, 코드를 짠 시니어는 이미 퇴사했어요. 어디서부터 시작해야 할까요?

이 막막함을 풀어주려는 시도가 그동안 정말 많았어요. UML 다이어그램, Doxygen 같은 문서 자동 생성 도구, Sourcegraph 같은 코드 검색 엔진, 그리고 최근에는 GitHub Copilot이나 Cursor 같은 AI 코딩 어시스턴트까지. 그런데 이런 도구들의 한계가 분명했어요. "코드를 검색하는 것"과 "코드를 이해하는 것"은 완전히 다른 문제거든요. 검색은 "이 함수 어디 있지?"에 답하는 거고, 이해는 "이 함수가 왜 여기 있고, 어디서 호출되고, 비즈니스적으로 어떤 의미가 있지?"에 답하는 거예요.

이번에 소개할 Understand-Anything은 바로 이 두 번째 문제, 즉 "이해"에 정면으로 도전한 오픈소스 도구입니다. Claude Code, Cursor, Copilot, Gemini CLI 같은 AI 코딩 도구들과 모두 연동되고, 코드베이스를 인터랙티브 지식 그래프(interactive knowledge graph)로 변환해줘요. 지식 그래프라는 게 뭐냐면, 쉽게 말해서 코드의 각 조각들(파일, 함수, 클래스)을 점(노드)으로 만들고, 그 점들이 어떻게 연결되는지(호출 관계, 의존성 등)를 선(엣지)으로 표현한 지도라고 생각하시면 돼요. 지하철 노선도처럼요.

Understand-Anything이 풀려고 하는 진짜 문제

프로젝트 README에 쓰여 있는 말 중에 인상 깊은 문장이 있어요. "Graphs that teach > graphs that impress" — 사람들 입을 떡 벌어지게 만드는 화려한 그래프 말고, 조용히 가르쳐주는 그래프가 더 중요하다는 거예요.

이게 무슨 뜻이냐면요, 사실 코드를 시각화해주는 도구는 이미 많아요. 의존성 그래프, 콜 그래프 같은 것들요. 그런데 막상 켜보면 노드가 수천 개고 선이 거미줄처럼 얽혀서 "우와 우리 코드가 이렇게 복잡했구나" 하는 감탄만 하고 끝나요. 정작 "그래서 이 함수가 뭐하는 건데?"라는 질문에는 답을 못 해주죠.

Understand-Anything의 접근 방식은 다릅니다. 그래프의 각 노드를 클릭하면 평이한 영어(plain-English) 설명이 떠요. "이 함수는 사용자 인증을 담당하며, login_handler에서 호출되고, JWT 토큰을 생성합니다" 같은 식으로요. 게다가 가이드 투어(guided tours) 기능도 있어서, 마치 박물관 도슨트처럼 "먼저 여기 main 함수부터 보시고, 다음은 이쪽 데이터베이스 레이어로 가시죠" 하고 코드를 따라가며 설명해줘요.

핵심 기술: 멀티 에이전트 파이프라인

자, 그럼 이게 어떻게 동작하는지 좀 더 깊이 들어가볼게요. 핵심은 멀티 에이전트 파이프라인(multi-agent pipeline)이라는 구조예요.

멀티 에이전트가 뭐냐면, 쉽게 말해서 여러 명의 AI가 각자 다른 역할을 맡아서 협업하는 구조예요. 한 명의 AI한테 "이 코드 다 분석해줘"라고 던지는 게 아니라, 한 명은 파일 구조 파악, 한 명은 함수 의존성 분석, 한 명은 비즈니스 로직 추출, 한 명은 요약 작성 — 이런 식으로 분업하는 거죠. 마치 영화 제작팀처럼요. 감독 한 명이 다 하는 게 아니라 촬영, 조명, 편집, 음향이 각자 자기 일을 합니다.

이 방식의 장점이 뭐냐면, 각 에이전트가 좁은 범위에 집중할 수 있다는 거예요. AI 모델들이 가진 컨텍스트 윈도우(한 번에 처리할 수 있는 텍스트 양)에는 한계가 있거든요. 20만 줄짜리 코드를 한 번에 던지면 모델이 "어... 그래서 뭐가 중요했더라?" 하면서 헷갈려 해요. 그런데 작업을 잘게 쪼개서 각 에이전트가 자기 영역만 깊게 파면, 결과물의 품질이 훨씬 좋아져요.

파이프라인의 대략적인 흐름은 이래요:

1. 스캐닝 단계: 프로젝트 디렉토리를 훑어서 어떤 파일들이 있는지, 어떤 언어로 짜여있는지 파악합니다.
2. 파싱 단계: AST(Abstract Syntax Tree, 추상 구문 트리)를 만들어서 함수, 클래스, 변수 같은 코드 구조를 추출해요. AST가 뭐냐면, 코드를 사람 말고 기계가 이해하기 쉽게 트리 모양으로 재구성한 형태예요.
3. 관계 추출: 각 요소들이 어떻게 연결되는지 분석합니다. A 함수가 B 함수를 호출하는지, C 클래스가 D 인터페이스를 구현하는지 같은 거요.
4. 의미 분석: 여기가 AI의 진짜 힘이 발휘되는 단계예요. 코드를 읽고 "이 함수가 무슨 일을 하는지"를 자연어로 설명해줍니다.
5. 도메인 매핑: 코드를 비즈니스 흐름(domain, flow, step)으로 묶어줘요. 예를 들어 "결제 처리"라는 도메인 안에 "카드 검증 플로우", "결제 승인 플로우" 같은 게 들어가는 식이죠.
6. 시각화 생성: 마지막으로 인터랙티브 대시보드로 결과를 보여줍니다.

두 가지 뷰: 구조 그래프 vs 도메인 그래프

Understand-Anything의 재밌는 점은 그래프를 두 가지 관점으로 보여준다는 거예요.

구조 그래프 (Structural Graph)

첫 번째는 우리가 익숙한 형태의 그래프예요. 파일, 함수, 클래스를 노드로 두고, 호출 관계나 import 관계를 선으로 연결해요. 노드를 클릭하면 그 코드 조각이 뭐하는 건지 설명이 뜨고, 어디서 호출되는지, 뭘 호출하는지 다 보여줘요. 검색 기능도 있어서 "login"이라고 치면 관련된 노드들이 하이라이트되고요.

이건 "코드의 물리적 구조"를 보여주는 뷰예요. 마치 건물의 설계 도면 같은 거죠.

도메인 그래프 (Domain Graph)

두 번째가 진짜 차별점인데요, 비즈니스 로직 관점의 뷰예요. 코드를 "기능별"로 다시 묶어서, 도메인 → 플로우 → 스텝의 가로 방향 그래프로 보여줍니다.

예를 들어 쇼핑몰 코드라고 하면 구조 그래프는 "OrderService.java가 PaymentService.java를 호출한다"는 식으로 보여주지만, 도메인 그래프는 "주문 처리"라는 도메인 아래 "장바구니 담기 → 결제 정보 입력 → 결제 승인 → 주문 확정"이라는 플로우를 보여주는 거예요. 이게 PM이나 신입 개발자한테 훨씬 직관적이죠. 코드의 "존재 이유"를 보여주니까요.

이 두 뷰를 오가면서 "아, 이 비즈니스 흐름이 코드로는 이렇게 구현되어 있구나"를 깨닫게 되는 게 핵심 가치예요.

플러그인 방식의 영리한 설계

레포 구조를 보면 .claude-plugin, .copilot-plugin, .cursor-plugin 같은 디렉토리가 보이는데요, 이게 의미하는 게 큽니다. Understand-Anything은 독립 도구가 아니라 기존 AI 코딩 어시스턴트의 플러그인으로 동작해요.

왜 이게 영리한 설계냐면요, 사람들은 이미 Cursor나 Claude Code 같은 도구를 매일 쓰고 있거든요. 거기에 "이거 새로 깔고 별도 창에서 보세요" 하면 잘 안 써요. 사람은 도구를 새로 추가하는 걸 굉장히 싫어하니까요. 그런데 "이미 쓰는 Claude Code 안에서 슬래시 명령어 하나로 호출하세요" 하면 마찰이 확 줄어들어요.

실제로 사용 흐름은 대략 이렇습니다. Claude Code 안에서 /understand 같은 명령어를 치면 분석이 시작되고, 분석이 끝나면 로컬에서 대시보드가 열려요. 그 대시보드에서 코드를 탐색하다가 "이 부분 더 자세히 알려줘"라고 자연어로 질문하면 다시 AI가 답해주는 식이죠. "이해" → "질문" → "코드 수정"의 순환이 한 흐름 안에서 일어나는 거예요.

비슷한 도구들과 비교해보면

코드 이해를 돕는 도구가 처음 나온 건 아니에요. 비슷한 시도들과 비교해볼게요.

Sourcegraph

Sourcegraph는 강력한 코드 검색 엔진이에요. "이 함수를 어디서 호출하는지"를 정확하게 찾아줍니다. 그런데 검색에 강하지 "설명"에는 약해요. "이 함수가 왜 존재하는지"를 자연어로 설명해주진 않거든요. Understand-Anything은 여기에 AI 기반 설명을 얹은 셈입니다.

GitHub Copilot Workspace / Cursor의 코드베이스 이해

이런 AI 에디터들도 이제 "@codebase" 같은 기능으로 코드 전체를 컨텍스트로 줘서 질문할 수 있어요. 그런데 이건 시각화가 없는 채팅 인터페이스예요. 질문하고 답 받는 식이죠. Understand-Anything은 시각적 탐색을 더해서, "내가 어디 있는지"를 공간적으로 인지할 수 있게 해줍니다. 사람은 텍스트보다 공간 인지에 강하다는 점을 잘 활용한 거예요.

Doxygen, Sphinx 같은 문서 생성기

전통적인 문서 자동 생성 도구들은 코드 주석을 기반으로 문서를 만들어요. 문제는 주석이 없거나 낡았으면 결과물도 부실하다는 거죠. AI 기반 도구들은 코드 자체를 읽고 의미를 추론하기 때문에 주석 의존도가 훨씬 낮아요.

CodeSee, Sourcetrail

시각화 쪽에서는 CodeSee나 Sourcetrail 같은 도구가 비슷한 컨셉이었는데요, 이들은 AI 시대 이전의 도구라서 "의미 분석"이 약했어요. 그래프는 예쁜데 노드를 클릭해도 코드 조각만 보여주는 정도였죠. Understand-Anything의 차별점은 그래프 + AI 설명 + 가이드 투어를 합쳤다는 점이에요.

한국 개발자에게 주는 시사점

자, 이제 실용적인 얘기를 해볼게요. 한국에서 이런 도구를 어떻게 활용할 수 있을까요?

시나리오 1: 레거시 인수인계

한국 기업 환경에서 정말 흔한 상황이 있어요. 5~10년 된 시스템을 운영하던 시니어가 이직하면서 코드를 신입한테 넘기는 상황. 문서는 부실하고, 주석은 한글/영어 혼재에 오타투성이, 변수명은 "a1, b1, temp_var"... 이럴 때 Understand-Anything을 돌려보면 적어도 "어떤 모듈이 핵심인지", "어디부터 봐야 하는지" 정도는 빠르게 파악할 수 있어요. 신입의 적응 기간이 한 달에서 일주일로 줄어들 수 있는 거죠.

시나리오 2: 오픈소스 기여

한국 개발자분들이 오픈소스 기여를 시작할 때 가장 큰 장벽이 "이 큰 코드베이스를 어디서부터 봐야 하나"예요. Understand-Anything으로 레포를 분석한 뒤 도메인 그래프를 보면, 자신이 관심 있는 기능이 어느 부분에 있는지 빠르게 찾을 수 있어요.

시나리오 3: 코드 리뷰 보조

다른 팀이 짠 PR을 리뷰할 때, 그 변경이 시스템 전체에 어떤 영향을 미치는지 파악하기 어려울 때가 많죠. 지식 그래프 위에서 변경된 노드를 보면 영향 범위를 시각적으로 확인할 수 있어요.

도입 시 고려할 점

다만 솔직하게 짚어야 할 부분도 있어요:

• 보안: 코드를 AI에 보낸다는 점이 마음에 걸릴 수 있어요. 회사 정책상 외부 LLM API에 소스 코드를 보내면 안 되는 경우가 많거든요. 로컬 LLM과 연동하는 옵션이 있는지 확인이 필요해요.
• 비용: 20만 줄 코드를 분석하려면 토큰을 엄청 많이 쓰게 돼요. 한 번 분석에 몇 달러에서 몇십 달러까지 들 수 있다는 점을 고려하세요.
• 한국어 코드/주석 처리: 한국 기업 코드는 변수명은 영어지만 주석이나 도메인 용어가 한글인 경우가 많아요. 이런 혼재 환경에서 얼마나 잘 동작하는지는 실제로 돌려봐야 알 수 있을 것 같아요.

학습 로드맵 제안

Understand-Anything을 시작점으로 AI 코딩 에이전트 생태계를 익혀보시는 걸 추천드려요. 구체적으로는:

1. 1주차: Claude Code나 Cursor 같은 메인 도구 하나에 익숙해지기.
2. 2주차: 본인 사이드 프로젝트에 Understand-Anything 돌려보고 결과 검토.
3. 3주차: 회사 코드(허락된 범위에서) 일부에 적용해보고 신입 온보딩 가이드로 활용 가능성 테스트.
4. 4주차: 멀티 에이전트 파이프라인 개념을 이해하고, 본인의 워크플로우에 비슷한 패턴 적용해보기.

앞으로 어떻게 될까

개인적으로 이 흐름이 시사하는 바가 크다고 봐요. 우리는 그동안 AI를 "코드를 생성하는 도구"로만 봐왔거든요. Copilot이 자동완성을 해주고, Cursor가 함수를 만들어주는 식으로요. 그런데 Understand-Anything 같은 도구는 "코드를 이해시켜주는 도구"로서의 AI를 보여줍니다. 생성보다 이해가 더 어려운 문제일 수 있어요. 왜냐하면 좋은 코드를 생성하려면 결국 기존 코드를 잘 이해해야 하니까요.

앞으로 1~2년 안에 이런 도구들이 IDE에 기본 탑재될 가능성이 높다고 봐요. JetBrains의 IDE들이 인덱싱 기능을 발전시켜온 것처럼, 다음 단계는 "AI 기반 의미 인덱싱"일 거예요. 그리고 그 표준 인터페이스가 지식 그래프가 될 가능성이 크고요.

그래서 지금 이런 도구를 미리 써보고 익숙해지는 게 의미가 있어요. 2~3년 뒤에 "코드베이스를 처음 보자마자 지식 그래프부터 띄우는 게 당연"한 시대가 올 수도 있거든요.

마무리하며: 여러분의 경험은?

저는 새 코드베이스를 만날 때마다 늘 같은 의식을 치러요. git clone → README.md 열기 → package.json이나 requirements.txt 보기 → main.py 또는 진입점 파일 찾기 → 거기서부터 막 따라가기. 이게 너무 비효율적이라고 느낀 적이 많아요. 지도 없이 모르는 도시에 떨어진 기분이거든요.

Understand-Anything 같은 도구가 진짜 약속을 지킨다면, 이 의식이 바뀔 수 있어요. "먼저 그래프를 그리고, 그 위에서 탐험을 시작하는" 방식으로요.

여러분께 묻고 싶어요:

• 새 코드베이스를 처음 마주했을 때 본인만의 탐색 루틴이 있으신가요?
• AI에게 회사 코드를 보내는 것에 대해 어떻게 생각하세요? 어떤 안전장치가 있어야 마음 편히 쓸 수 있을까요?
• 만약 본인 회사 코드를 지식 그래프로 만든다면, 어떤 도메인부터 그려보고 싶으신가요?

댓글로 여러분의 생각을 공유해주시면 좋겠어요. 이 도구가 단순한 유행으로 그칠지, 아니면 우리가 코드를 대하는 방식 자체를 바꿀지 — 그 답은 결국 우리 같은 실무자들이 어떻게 쓰느냐에 달려있으니까요.

---

🔗 출처: GitHub