Kwangmin Kim - GraphRAG 기반 Blackbox 코드 분석기 아키텍처

1 개요

GraphRAG을 코드 분석에 적용하는 접근은 “연구 단계의 실험”이 아니라 “엔지니어링 완성도”의 문제이다. 기술적 불가능성이나 미해결 연구 과제가 아니라, 설계 선택과 구현 품질에 따라 성패가 결정된다.

전체 파이프라인의 구조는 다음과 같다:

AST 파서
 → Fact Graph 생성
 → 메타데이터 결합
 → LLM 의미 추출
 → Semantic Edge 생성
 → Graph DB
 → GraphRAG
 → Code Analysis Agent

AST(Abstract Syntax Tree)에서 추출한 구조적 사실을 그래프의 불변 기반으로 삼고, LLM이 생성하는 의미 관계를 그 위에 층위적으로 추가하는 아키텍처이다.

2 성공 가능성을 결정하는 5가지 핵심 조건

2.1 1. AST를 사실 계층으로 고정

AST 기반 관계를 다음과 같이 취급해야 한다:

변경 불가
논쟁 불가
추론 대상이 아닌 전제로 사용

AST에서 추출한 관계(함수 호출, 클래스 상속, 모듈 의존성 등)는 코드가 실제로 그렇게 작성되어 있다는 사실이다. 이를 LLM이 재해석하거나 추론하도록 두면 안 된다. 이 조건을 충족하면 GraphRAG의 가장 큰 실패 원인 하나를 제거한 상태가 된다.

2.2 2. GraphRAG의 역할을 정확히 설정

GraphRAG은 코드 생성 도구가 아니다. 다음과 같은 역할 구분이 중요하다:

GraphRAG이 할 수 없는 것:

자동 리팩터링
완전한 변경 제안

GraphRAG이 잘하는 것:

변경 판단 보조
영향 범위 설명
코드 구조 이해

코드의 구조, 의미, 책임을 이해하는 데 초점을 맞추면 성공 확률이 높아진다.

2.3 3. 의미 관계를 제한된 집합으로 통제

이 조건이 성공과 실패의 분기점이다.

성공하는 경우:

의미 edge를 10~20개 이내의 고정된 관계 유형으로 제한
관계 이름이 추상적이지 않고 도메인/아키텍처 관점에서 명확
예: delegates_to, validates_input_for, shares_state_with

실패하는 경우:

LLM이 매번 새로운 관계를 자유롭게 생성
관계 이름이 설명 문장처럼 길어짐
그래프가 “지식 그래프”가 아니라 “생각 그래프”가 됨

의미 관계의 어휘를 통제하는 것이 그래프 품질을 결정한다.

2.4 4. KPI를 의사결정 보조로 설정

실패하는 팀의 KPI:

설명이 100% 정확해야 한다
한 번도 틀리면 안 된다

성공하는 팀의 KPI:

판단 속도가 빨라졌는가
질문이 사람에서 시스템으로 이동했는가
변경 전 검토 시간이 줄었는가

GraphRAG은 정확도 도구가 아니라 판단 가속기이다. 이 관점으로 성과를 측정해야 한다.

2.5 5. 그래프 유지 비용을 통제

현실적인 운영 관점에서 가장 중요한 조건이다.

성공하는 설계:

AST 기반 관계는 코드 변경 시 자동 갱신
의미 관계는 confidence 기반으로 승격
낮은 confidence의 추론 결과는 그래프에 미반영

실패하는 설계:

모든 추론 결과를 그래프에 저장
그래프가 빠르게 오염되어 신뢰 붕괴

3 실패 패턴

다음 중 하나라도 해당되면 실패 위험이 높다:

“GraphRAG로 코드 리뷰를 대체하겠다”
“시니어 개발자 역할을 자동화하겠다”
“자동 리팩터링까지 확장하겠다”
“모든 언어, 모든 레포에 일반화하겠다”

이는 기술 문제가 아니라 기대치 문제이다. GraphRAG의 강점은 이해와 판단 보조이지, 자율적 코드 수정이 아니다.

4 성공 시 실질적 성과

GraphRAG 기반 코드 분석기가 성공적으로 작동할 때 나타나는 변화는 구체적이다:

영역	개선 효과
신규 인력 온보딩	코드 이해 시간 단축
변경 영향 분석	영향 범위 파악 시간 단축
내부 질의	“이 코드 왜 이렇게 되어 있나?” 질문 감소
아키텍처 리뷰	리뷰 준비 시간 단축
레거시 관리	레거시 영역 식별 시간 단축

이는 체감 가능한 생산성 향상이다.

5 설계 검증을 위한 핵심 질문

코드 분석 Agent를 설계할 때 다음 세 가지 질문에 모두 “Yes”라고 답할 수 있어야 한다:

이 Agent가 대신 판단하는가, 판단을 돕는가? 판단을 돕는 방향이 올바르다.
이 설명이 틀려도, 사람이 더 빨리 판단할 수 있는가? 힌트의 가치가 있어야 한다.
그래프를 신뢰하지 않아도, 탐색 도구로서 가치가 있는가? 신뢰와 무관하게 유용해야 한다.

이 세 조건을 충족하면, 성공 여부는 기술적 가능성이 아니라 시간과 집중도의 함수가 된다.

6 다음 단계

PoC 단계에서 고려해야 할 사항은 다음과 같다:

PoC 성공 기준: 코드 구조 질문에 대해 사람보다 빠르게 답변하는가
MVP에서 반드시 버려야 할 기능: 자동 수정, 범용 언어 지원, 완전 자동화
처음부터 넣으면 실패하는 요소: 모든 추론 결과의 그래프 저장, 무제한 관계 유형, 정확도 100% 목표