코드베이스를 픽셀 아트 지도로 변환하여 시각적으로 코드를 작성하는 Visual RAG 파이프라인

실용적 조언

대규모 코드베이스 분석 시 Tree-sitter를 활용해 구조적 데이터를 먼저 추출하면 AI의 이해도를 높일 수 있다.
컨텍스트 윈도우 제한이 문제일 경우 정보를 시각적으로 압축하여 VLM에 입력하는 방식을 고려할 수 있다.

섹션별 상세

Tree-sitter 라이브러리를 활용하여 JavaScript 및 TypeScript 리포지토리 내의 JSX 컴포넌트, 함수 호출 체인, 상수 및 타입 정의와 같은 핵심 구조적 패턴을 추출한다. 이 과정은 소스 코드의 단순 텍스트 나열이 아닌 추상 구문 트리(AST)를 기반으로 코드 간의 논리적 관계와 의존성을 명확히 데이터화하는 작업이다. 추출된 구조 정보는 AI가 코드베이스의 전체적인 설계 방식을 이해하기 위한 기초 데이터로 기능한다.

추출된 코드 패턴은 결정론적 해싱 알고리즘을 통해 16x16 픽셀 크기의 고유한 타일로 변환되며, 이 타일들은 거대한 캔버스 위에 배치되어 코드베이스의 시각적 지도를 형성한다. 수천 줄의 복잡한 코드를 고밀도 이미지 데이터로 압축함으로써 LLM의 컨텍스트 윈도우 제한 문제를 해결하고 정보 처리 효율성을 극대화하는 메커니즘을 구현했다. 동일한 코드 구조에 대해서는 항상 일관된 시각적 패턴이 생성되므로 모델이 구조적 유사성을 시각적으로 학습하고 인식하는 데 유리하다.

DeepSeek-OCR 논문의 초록 페이지를 보여주는 브라우저 스크린샷 — Screenshot시각적 2D 매핑을 통해 긴 컨텍스트를 압축하는 기술을 다루는 DeepSeek-OCR 논문을 보여준다. 게시글에서 설명하는 코드베이스의 시각적 압축 아이디어가 이 논문의 기술적 개념을 코드 분석에 응용한 것임을 시사한다.

LangGraph 프레임워크로 구축된 자율 에이전트는 시각 모델(Visual Model)을 탑재하여 생성된 코드 지도를 직접 분석하고 탐색하는 기능을 갖추고 있다. 에이전트는 코드를 생성하기 전 지도의 범례를 참조하여 전체 아키텍처와 모듈 간의 관계를 먼저 연구하는 탐색 후 생성(explore-before-generate) 루프를 강제로 수행한다. 이러한 아키텍처 설계는 AI가 지엽적인 코드 수정에 그치지 않고 전체 시스템의 맥락과 설계 원칙을 반영한 코드를 작성하도록 유도한다.

용어 해설

추상 구문 트리(AST): — 프로그래밍 언어의 소스 코드 구조를 트리 형태로 표현한 데이터 구조이다. 코드의 문법적 요소를 노드로 나타내어 AI가 코드의 논리적 흐름과 의존성을 정확히 파악하도록 돕는 역할을 한다.
트리 시터(Tree-sitter): — 다양한 프로그래밍 언어를 지원하는 점진적 파싱 라이브러리이다. 소스 코드를 실시간으로 분석하여 AST를 생성하며, 이 프로젝트에서는 코드의 구조적 패턴을 추출하는 핵심 도구로 사용됐다.
시각적 검색 증강 생성(Visual RAG): — 텍스트 대신 이미지나 시각적 데이터를 검색 소스로 활용하는 검색 증강 생성 기법이다. 코드베이스를 시각적 지도로 변환하여 시각 모델이 이를 참조하게 함으로써 텍스트 기반 컨텍스트의 한계를 극복한다.
랭그래프(LangGraph): — 상태를 유지하는 다중 에이전트 워크플로우를 구축하기 위한 라이브러리이다. 에이전트의 탐색 및 생성 단계를 그래프 형태로 정의하여 복잡한 논리적 루프를 안정적으로 제어하는 데 사용된다.

언급된 도구

Tree-sitter추천

코드 구조(AST) 추출 및 분석

LangGraph추천

자율 에이전트 워크플로우 및 상태 관리

언급된 리소스

논문DeepSeek-OCR: Contexts Optical Compression