기술 요약: Code2UML – 확장 가능한 소프트웨어 시각화를 위한 컨텍스트 엔지니어링이 적용된 에이전트 기반 LLM

문제 제기

소프트웨어 문서화, 특히 최신 상태의 UML 다이어그램은 수동 생성의 높은 비용과 오류 발생 가능성으로 인해 자주 소홀히 처리됩니다. 대규모 언어 모델 (LLM) 은 이러한 작업을 자동화할 잠재력을 제공하지만, 실제 코드베이스에 적용할 때 근본적인 확장성 장벽에 직면합니다. 중규모에서 대규모 프로젝트의 중간 표현 (IR) 은 가장 진보된 LLM 의 유효한 컨텍스트 창을 초과하는 경우가 많습니다. 전체 코드베이스 표현을 단일 LLM 호출에 주입하려는 단순한 접근 방식은 잘라낸 출력, 환각된 관계, 그리고 구조적으로 중요한 구조를 포착하지 못하는 실패로 이어집니다. 또한 클래스, 시퀀스, 배포 등 다양한 UML 다이어그램 유형은 각각 고유한 표기 규칙과 정보 요구 사항을 필요로 하므로, "일률적"인 생성 방식으로는 부족합니다.

방법론

본 논문은 LLM 컨텍스트 제약을 준수하면서 소스 코드 저장소에서 직접 UML 다이어그램을 생성하도록 설계된 에이전트 아키텍처인 Code2UML을 소개합니다. 이 시스템은 Claude Agent SDK(Claude Sonnet 4.6 사용) 를 기반으로 구축되었으며, 4 단계 파이프라인을 통해 작동합니다.

1. IR 생성 및 정규화: Java, Python, JavaScript, PHP 로 작성된 소스 코드는 Tree-sitter 를 사용하여 언어 중립적인 JSON 중간 표현 (IR) 을 생성하도록 파싱됩니다. 결정론적 후처리 단계는 접근 한정자, 상속 등 언어별 구성 요소를 일관된 스키마로 정규화합니다.
2. 컨텍스트 엔지니어링 (IR 뷰 생성): 컨텍스트 제한을 해결하기 위해 시스템은 결정론적, 중요도 가중 IR 압축 계층을 사용합니다. 이 순수 Python 변환은 전체 프로젝트 IR 을 토큰 제약 (단일 경로 60KB, 심층 경로 100KB) 내에 보장되도록 다이어그램별 뷰로 변환합니다.
   • 메커니즘: 다이어그램 유형별 중요도 점수 (예: 메서드 수, 상속 존재 여부) 를 기반으로 요소를 순위 매기고 반복적으로 축소합니다. 목표 크기를 초과하면 요소 할당량을 반으로 줄입니다.
   • 효율성: 이 과정은 LLM 호출이 필요 없으며 밀리초 단위로 완료됩니다.
3. 멀티 에이전트 아키텍처: 시스템은 5 개의 전문 에이전트 계층을 활용하며, 각 에이전트는 고유한 인지 하위 작업을 처리합니다.
   • PlannerAgent: 프로젝트 크기에 따라 논리적 범위 (워크플로우/모듈) 로 프로젝트를 분해합니다.
   • AnalyzerAgent: Planner 가 식별한 특정 소스 파일을 읽어서 각 범위에 대한 고신호 컨텍스트 (호출 체인, 관계) 를 추출합니다. 여러 에이전트가 병렬로 실행됩니다.
   • DiagramAgent: 압축된 IR 뷰 (아키텍처 개요용) 또는 풍부한 컨텍스트 (상세한 행동/구조 다이어그램용) 를 기반으로 최종 PlantUML 코드를 생성합니다.
   • CorrectorAgent: 다이어그램 유형별 규칙 세트를 사용하여 생성된 .puml 파일의 구문 오류를 검증하고 수정합니다.
   • DependencyAnalyzerAgent: 서드파티 라이브러리 소스 코드를 독립적으로 분석합니다.
4. 오케스트레이션 전략: 시스템은 2 단계 라우팅 전략을 사용합니다.
   • SINGLE 경로: 아키텍처 개요 (컴포넌트, 배포, 시스템 컨텍스트) 의 경우 단일 DiagramAgent 를 호출합니다.
   • DEEP 경로: 상세 다이어그램 (클래스, 시퀀스, 활동, 사용 사례) 의 경우 파이프라인화된 수정을 갖춘 3 단계 파이프라인 (Planner → Analyzer → Diagram) 을 호출합니다.

주요 기여

본 논문은 세 가지 주요 기여를 주장합니다.

1. 결정론적 컨텍스트 엔지니어링: 프롬프트 텍스트뿐만 아니라 데이터 페이로드를 최적화하는 새로운 접근 방식입니다. LLM 호출 없이 대규모 IR 을 압축된 다이어그램별 뷰로 변환하여 공격적인 압축 비율에서도 구조적으로 중요한 요소가 살아남도록 보장합니다. 검색 증강 생성 (RAG) 과 달리, 이는 결정론적 점수 매기기를 통해 구조화된 IR 에서 작동합니다.
2. 전문 멀티 에이전트 계층: 단일 모놀리식 프롬프트 기반 접근 방식을 대체하는 5 개 에이전트 프레임워크입니다. 이러한 관심사 분리는 계획, 분석, 생성, 검증을 독립적으로 최적화할 수 있게 하여 확립된 소프트웨어 공학 원칙을 반영합니다.
3. 포괄적인 실증 평가: 12 개의 오픈소스 저장소(4 개 언어에 걸쳐 있으며 크기는 31 개에서 4,578 개 IR 엔티티까지 2 개의 차수에 달함) 와 7 가지 UML 다이어그램 유형에 대한 엄격한 평가로, 5 가지 자동화 지표로 평가된 84 개의 관찰 결과를 도출했습니다.

결과

시스템은 구문 유효성, 엔티티 재현율, 관계 정밀도, 구조적 품질, 구조적 복잡성 지수 (SCI) 라는 5 가지 자동화 지표로 평가되었습니다.

• 구문 유효성: 시스템은 평균 유효성 **91.5%**를 달성했습니다. 컴포넌트 및 배포 다이어그램은 100% 유효성을 기록했습니다. 시스템 컨텍스트 다이어그램은 C4 모델 스테레오타입의 복잡성으로 인해 유효성이 가장 낮았습니다 (58.3%).
• 관계 정밀도: 평균 정밀도는 0.858로, 생성된 관계의 대다수가 소스 코드에 실제로 선언된 엔티티를 연결하며 환각은 최소화되었음을 나타냅니다.
• 구조적 품질: 평균 품질 점수는 81.7/100이었습니다. 특히 품질 점수가 프로젝트 크기 (77.5~83.6 범위) 전반에 걸쳐 안정적으로 유지되어 컨텍스트 엔지니어링 계층이 규모와 관계없이 다이어그램 품질을 성공적으로 유지함을 입증했습니다.
• 엔티티 재현율: 평균 재현율은 0.313이었습니다. 이는 실패가 아닌 의도적인 아키텍처 우선순위화로 해석됩니다. 시스템은 포괄적인 커버리지보다는 중요한 구조에 초점을 맞춥니다. 클래스 다이어그램이 가장 높은 재현율 (0.445) 을 기록한 반면, 사용 사례 다이어그램은 추상적 성격에 따라 가장 낮았습니다 (0.165).
• 언어 간 일관성: Java, JavaScript, PHP, Python 간 성능이 매우 일관되었으며, 언어 간 품질 점수 차이는 0.6 점에 불과했습니다.
• 확장성: 민감도 분석은 IR 엔티티 수가 31 개에서 4,578 개로 증가함에 따라 품질이 저하되지 않음을 확인했습니다.

중요성 및 주장

본 논문은 Code2UML 이 현재 LLM 기반 소프트웨어 공학 도구의 중요한 한계인 컨텍스트 창 제약 내에서 대규모 코드베이스를 신뢰성 있게 처리하고 문서화하지 못하는 문제를 해결한다고 주장합니다.

• 방법론적 전환: 이 연구는 결정론적 컨텍스트 엔지니어링과 전문 에이전트 계층을 결합함으로써 확장 가능하고 정확하며 구문적으로 유효한 UML 생성이 가능함을 보여줍니다. 이 접근 방식은 복잡한 저장소 수준 작업을 위한 단일 모놀리식 프롬팅이나 단순한 RAG 를 넘어선 필수적인 진화로 제시됩니다.
• 실용적 유용성: 여러 언어에 걸쳐 아키텍처적으로 일관되고 구문적으로 유효한 다이어그램을 생성함으로써, 시스템은 자동화된 소프트웨어 문서화 및 아키텍처 이해 향상에 기여합니다.
• 소극적 한계: 저자는 자동화 지표가 주관적인 인간적 유용성을 포착하지 못함을 인정합니다. 시스템 컨텍스트 다이어그램은 C4 모델 구성 요소에 대한 규칙 세트 확장이 더 필요하며, 현재 평가는 광범위하지만 오픈소스 저장소로 제한된다고 지적합니다. 시스템은 "포괄적인 커버리지보다 아키텍처적 중요성을 우선시"하며, 이는 버그가 아닌 설계 선택입니다.

결론적으로, Code2UML 은 LLM 기반 소프트웨어 시각화를 확장하기 위한 실행 가능한 프레임워크를 제시하며, 올바른 컨텍스트 엔지니어링과 에이전트 전문화를 통해 LLM 이 실제 소프트웨어 저장소의 복잡성을 효과적으로 처리할 수 있음을 입증합니다.