Post

코드의 '의미'를 발굴하는 AI 고고학: Understand-Anything 아키텍처 심층 해부

Posted
AI Archaeology Unearthing the 'Meaning' of Code: A Deep Dive into Understand-Anything
AI Archaeology Unearthing the 'Meaning' of Code: A Deep Dive into Understand-Anything
By
16 min read
코드의 '의미'를 발굴하는 AI 고고학: Understand-Anything 아키텍처 심층 해부

[Metadata]

  • Repository: github.com/Lum1104/Understand-Anything
  • Ecosystem Compatibility: Claude Code, Cursor, Copilot CLI, Gemini CLI
  • Core Architecture: Multi-agent LLM pipeline, React, TypeScript
  • Recent Stats: 15,000+ GitHub Stars (As of May 2026)

솔직히 처음 이 툴의 이름을 들었을 땐 속으로 피식했습니다. ‘Understand-Anything’? 이름 한 번 거창하네, 또 그저 그런 겉멋 든 AI 래퍼(Wrapper) 툴이 하나 더 나왔구나 싶었죠. 현업에서 수십만 줄짜리 얽히고설킨 스파게티 레거시 코드를 마주해 본 분들이라면 제 냉소에 공감하실 겁니다. 새 팀에 합류했을 때, 도큐먼트는 마지막으로 업데이트된 지 3년이 지났고, 핵심 비즈니스 로직을 머릿속에 꿰고 있던 유일한 시니어 개발자는 이미 퇴사하고 없는 막막한 상황. 우리는 코드를 ‘읽는’ 게 아니라, 단서를 찾아 헤매는 고고학자가 되어야 합니다.

게다가 최근 화제가 되는 Cursor나 Claude Code 같은 AI 코딩 에이전트를 실무에 딥하게 도입해 보신 분들은 또 다른 치명적인 한계를 느끼셨을 겁니다. 에이전트한테 “인증(Auth) 모듈의 세션 버그 좀 고쳐줘”라고 던지면, 이 녀석이 수많은 디렉토리 트리를 맹목적으로 헤매고, 엉뚱한 파일을 열었다 닫았다 하며 귀중한 컨텍스트 윈도우와 토큰을 허공에 날려버리거든요. 코드를 본격적으로 짜보기도 전에 탐색(Exploration) 과정에서 숨이 차버리는 거죠. 이 뼈아픈 문제를 기가 막히게, 그리고 기술적으로 꽤나 우아하게 해결한 놈이 바로 오늘 밑바닥까지 뜯어볼 Understand-Anything(이하 UA)입니다.

TL;DR (The Core) UA는 수십만 줄의 코드베이스를 다중 에이전트 파이프라인으로 스캔하여, 단순한 파일 구조가 아닌 인간과 AI가 즉시 소화할 수 있는 ‘비즈니스 도메인 중심의 인터랙티브 지식 그래프(Knowledge Graph)’로 변환하는 메타-분석 프레임워크입니다.

Deep Dive: Under the Hood (핵심 아키텍처 심층 분석)

기존에도 코드를 분석해 주는 정적 분석(Static Analysis) 도구나 의존성 그래프 툴은 많았습니다. 하지만 UA가 보여주는 접근 방식은 근본적으로 다릅니다. 단순히 AST(Abstract Syntax Tree)를 파싱해 물리적인 호출 관계(Call Graph)를 그리는 선에서 멈추지 않고, 코드 이면에 숨겨진 ‘의미(Meaning)’를 추출해 비즈니스 맥락으로 매핑하기 때문이죠.

이게 어떻게 가능할까요? UA의 내부 아키텍처는 토큰 낭비를 최소화하고 분석 퀄리티를 높이기 위해 철저히 다중 에이전트 파이프라인(Multi-agent Pipeline)으로 분리되어 있습니다.

비교 항목기존 정적 분석 툴 (예: SonarQube 등)Understand-Anything (UA)
분석 단위물리적 파일, 클래스, 함수 단위의 구조비즈니스 플로우(결제, 인증 등), 도메인 레이어 중심
관계 추론AST 기반의 명시적인 코드 호출 관계 (Hard-link)LLM 기반의 의미론적(Semantic) 관계 및 암시적 컨텍스트 추론
AI 연동성AI 에이전트에 주입하기 어려움JSON 포맷의 지식 그래프로 변환되어 AI의 컨텍스트 맵으로 즉시 활용 가능
UI/UX트리 구조의 파일 탐색, 정적 리포트React 기반의 인터랙티브 대시보드, 퍼지(Fuzzy) 검색 지원

파이프라인이 코드를 소화하는 실제 과정을 뜯어봅시다. 사용자가 CLI에서 /understand 명령어를 입력하면 3단계의 핵심 에이전트가 순차적으로 깨어납니다.

  1. Project Scanner (경량화 및 타겟팅): 디렉토리 트리를 순회하며 프레임워크를 식별합니다. .gitignore는 기본이고, 설정된 패턴에 따라 빌드 아티팩트 등을 과감히 쳐내어 LLM이 읽어야 할 타겟을 최소화합니다.
  2. File Analyzer (Heavy-lifting): 여기가 핵심이자 가장 큰 비용(Token)이 발생하는 구간입니다. 최대 3개의 병렬 분석 프로세스가 돌아가며 각 파일을 LLM으로 읽어냅니다. 이때 단순 요약이 아니라, 파일의 목적, exports/imports, 외부 의존성을 평문과 구조화된 메타데이터(JSON)로 동시에 추출합니다.
  3. Architecture Analyzer (의미 통합): File Analyzer가 뱉어낸 파편화된 JSON 조각들을 모아 시스템 레벨의 큰 그림을 그립니다. “아, 이 login.ts와 session.ts는 물리적으로 멀리 떨어져 있지만 사실 인증 레이어(Auth Layer)를 구성하는 핵심 모듈이구나”라는 걸 파악하고 비즈니스 흐름으로 묶어주는 역할을 하죠.

실제 UA가 내부적으로 구축하는 지식 그래프 노드의 메타데이터 구조를 단순화해 보면 이런 느낌입니다. 물리적 경로가 아닌 domain과 business_flow가 포함된 것을 주목하세요.

1
2
3
4
5
6
7
8
9
10

{
  "node_id": "src/auth/login.ts",
  "type": "business_logic",
  "domain": "User Authentication",
  "business_flow": ["User Lifecycle", "Session Management"],
  "exports": ["login", "verify_token"],
  "semantic_summary": "사용자 자격 증명을 검증하고 JWT 세션을 발급하는 핵심 진입점.",
  "dependencies": ["src/db/models/user.ts", "src/utils/crypto.ts"],
  "impact_radius": "HIGH"
}

이 구조화된 JSON 데이터는 곧바로 로컬 React 대시보드(/understand-dashboard)의 렌더링 소스가 되며, 필요시 --language ko 옵션을 통해 노드 설명과 UI를 한국어로 매핑할 수도 있습니다.

Pragmatic Use Cases (실무 적용 시나리오)

“그래서 이걸로 뭐 할 건데?” 실무자라면 이 질문이 가장 먼저 나와야 정상입니다. 단순히 대시보드 띄워놓고 “와, 우리 코드 복잡하네” 하고 끝난다면 장난감에 불과하겠죠.

1. 대규모 트래픽 장애 시나리오에서의 ‘Impact Radius’ 추적 새벽 2시에 장애 알람이 울립니다. “결제 모듈에서 간헐적 타임아웃 발생.” 평소라면 수십 개의 파일을 grep으로 뒤지며 어디서부터 병목인지 추적했겠죠. UA가 도입된 환경에서는 다릅니다. 터미널에서 /understand-chat How does the payment flow work? 라고 묻거나, 대시보드의 퍼지 검색으로 payment pipeline을 검색합니다. UA는 물리적인 파일 트리가 아니라, create_order()부터 pg_gateway()를 거쳐 db_transaction()까지 이어지는 실제 비즈니스 실행 경로를 시각적으로 하이라이트 해줍니다. 특히 understand-diff 명령어를 사용하면 현재 로컬 브랜치의 변경 사항이 전체 지식 그래프의 어느 도메인에 영향을 미치는지 폭발 반경(Impact Radius)을 사전 분석할 수 있어, 핫픽스 배포 전 심리적 안정감을 극대화합니다.

2. AI 에이전트의 ‘Token 다이어트’ (Prompt Compression) 이건 비용 최적화 측면에서 엄청난 가치가 있습니다. GitHub에 공개된 “Caveman: Cut Claude Token Use by 65%” 가이드를 보면 그 위력이 실감 납니다. 기존에는 Claude Code가 전체 디렉토리를 순회하며 수만 토큰을 태웠다면, 이제는 UA가 미리 만들어둔 가벼운 JSON 지식 그래프 맵만을 초기 컨텍스트로 제공합니다. 에이전트는 이 ‘지도’를 보고 자신이 정확히 어떤 파일(src/auth/login.ts 등)만 까봐야 할지 단번에 결정하죠. 탐색 비용은 극단적으로 줄고, 실제 코드 수정(Execution)에 가용할 수 있는 토큰 윈도우는 대폭 늘어납니다.

3. 비개발 직군(PM, 기획자)과의 커뮤니케이션 브릿지 /understand-domain 명령어는 코드를 ‘도메인, 플로우, 스텝’의 비즈니스 언어로 번역해 줍니다. PM이 “우리 현재 유저 온보딩 로직이 어떻게 구현되어 있나요?”라고 물었을 때, 코드를 보여주는 대신 UA가 자동 생성한 Guided Tour(종속성 순서대로 재생되는 코드 워크스루)를 제공하거나 필터링된 SVG 이미지를 익스포트해서 던져주면 끝납니다.

Honest Review & Trade-offs (진짜 장단점과 한계)

물론 시니어 엔지니어의 깐깐한 시선으로 보면 피할 수 없는 함정들도 존재합니다.

첫째, 초기 스캐닝의 ‘Token Bill’ 쇼크. UA의 강력함은 모든 코드를 LLM이 한 번 정독한다는 데서 나옵니다. 문제는 레포지토리가 20만 줄, 50만 줄 넘어가는 엔터프라이즈급 모놀리스(Monolith)라면? File Analyzer가 돌아가는 동안 Claude API 청구서를 보며 식은땀을 흘릴 수 있습니다. 아직 증분 스캐닝(Incremental Scanning)이나 로컬 경량 모델(Ollama 기반의 Llama3 등)과의 매끄러운 오프라인 연동이 완벽하지 않아 벤더 종속(API 비용 종속) 리스크가 큽니다.

둘째, 환각(Hallucination)이 빚어낸 잘못된 아키텍처 매핑. LLM이 암시적인 관계를 ‘추론’하다 보니, 우연히 변수명이 비슷한 유틸리티 함수나 전혀 다른 맥락의 레거시 모듈을 같은 비즈니스 바운더리로 엮어버리는 경우가 종종 발생합니다. “어? 이 결제 모듈이 왜 로깅 시스템에 강하게 결합되어 있다고 나오지?” 하고 까보면 LLM의 헛발질인 경우가 있죠. 그래프를 100% 신뢰하기보다는, 코드 리뷰를 돕는 ‘보조 지표’로 삼아야 하는 이유입니다.

Closing Thoughts

과거에는 “코드는 기계가 실행하기 위해 작성되지만, 결국 사람이 읽기 위해 존재한다”고 했습니다. 하지만 2026년 현재, 우리는 “코드는 기계와 사람, 그리고 AI 에이전트가 함께 읽고 소통하기 위한 매개체”인 시대에 살고 있습니다.

Understand-Anything은 단순한 시각화 툴이 아닙니다. 파편화된 레거시 코드와 인간의 멘탈 모델, 그리고 AI의 컨텍스트 윈도우 사이를 이어주는 ‘공통의 언어(지식 그래프)’를 만들어냈다는 점에서 극찬받아 마땅합니다. 여전히 토큰 비용의 압박이나 간헐적인 환각 이슈는 존재하지만, 이 기술이 제시한 ‘구조를 넘어선 의미의 매핑’이라는 패러다임은 앞으로 우리 프론트엔드/백엔드 생태계의 개발 경험(DX)을 완전히 뜯어고칠 것입니다. 당장 내일, 먼지 쌓인 사내 레거시 레포지토리에서 /understand를 한 번 실행해 보세요. 아마 그동안 보지 못했던 코드의 진짜 맨얼굴이 보일 겁니다.

References

  • https://github.com/Lum1104/Understand-Anything
  • https://betterstack.com/community/
Tech
This post is licensed under CC BY 4.0 by the author.