불필요한 껍데기 걸러내기 — vulture를 이용한 데드 코드 탐지 및 지식 정제

정적 분석 도구에 새 이름을 붙이는 건 흔한 일이 아니다. 그런데 이 도구의 이름은 vulture(독수리) — 죽은 것만 먹는 새다. 이름이 왜 독수리일까?

vulture는 사자나 매처럼 살아있는 먹이를 직접 사냥하지 않는다. 이미 죽어 아무도 돌보지 않는 사체(carrion)만 탐색하며, 썩어가는 것을 치워 생태계를 정화한다. 이 이름을 소프트웨어에 그대로 가져왔다 — 아직 삭제되진 않았지만 아무도 호출하지 않는 코드, 즉 데드 코드(Dead Code)를 찾아내는 역할이기 때문이다. 도구 이름 하나에 설계 철학이 압축된다: 살아있는 코드에는 손 안 댄다. 죽은 것만 골라낸다.

소프트웨어가 진화하면서 필연적으로 레거시가 쌓인다. 기능이 변경되어 필요 없어진 유틸리티 함수나 과거에 쓰이던 비즈니스 로직들이 소스코드 한편에 조용히 웅크리고 있는 경우가 많다. 당장 컴파일 에러를 유발하지 않기 때문에 방치되기 일쑤인 이 미사용 코드를 데드 코드(Dead Code) 혹은 좀비 코드라고 부른다.

이 데드 코드는 개발자에게 혼란을 줄 뿐만 아니라, 코드를 분석하고 수정을 시도하는 AI 에이전트에게는 치명적인 독이 된다. 에이전트가 RAG를 통해 위키에서 관련 코드를 검색해 가져올 때, 이미 쓰이지 않는 폐기된 코드 청크가 컨텍스트 창에 입력되면 에이전트는 그것을 현재 작동하는 활성 소스코드로 오인하여 잘못된 수정안을 제안(환각 현상)하기 때문이다. deep-wiki Stage C의 또 다른 축인 vulture는 이 좀비들을 사냥하기 위해 정적 분석을 수행한다.

1. 왜 vulture인가: 레거시 코드와 RAG 컨텍스트 오염 예방

vulture는 파이썬 코드베이스를 정적으로 분석하여 사용되지 않는 함수, 클래스, 변수, 속성 등을 자동으로 찾아내는 도구다. 파이썬의 동적 특성 때문에 데드 코드를 완벽하게 잡아내기는 쉽지 않지만, vulture는 아래와 같은 장점을 무기로 삼는다.

• Broad Target Scans: 프로젝트 전반에 걸쳐 선언만 되고 호출되거나 참조된 흔적이 전혀 없는 미사용 심볼을 일괄 감지한다.
• Confidence Thresholding: 정적 분석의 한계로 오판할 가능성이 있는 항목들을 구분하고, 사용자가 화이트리스트(Whitelist)를 지정해 false positive를 억제할 수 있게 돕는다.
• Context Optimization: 쓸모없는 코드를 삭제하거나 위키 지식에서 제외하도록 하여, RAG 검색 공간의 순도를 극적으로 높여 준다.

2. 작동 원리: 선언과 참조의 불일치 추적

vulture의 원리는 명쾌하다. 소스코드를 AST 트리를 파싱해 탐색하며, "정의된 모든 심볼 집합"과 "사용/호출된 모든 심볼 집합"을 각각 수집한 뒤 차집합을 구한다.

예를 들어, `def run_backup():` 으로 함수를 정의하여 `Defined Set`에는 등록되었으나, 전체 프로젝트 내의 다른 소스 파일과 구문 전체를 뒤져봐도 `run_backup`이라는 식별자(Identifier)를 참조하는 구문이 전혀 없다면, 이 함수는 사용되지 않는 데드 코드로 분류된다.

3. Stage C 핵심 구현 예시

vulture의 작동 방식을 파이썬 코드로 간략히 모델링한 에뮬레이터 코드다.

import ast

class DeadCodeFinder(ast.NodeVisitor):
    def __init__(self):
        self.defined_functions = set()
        self.used_names = set()

    def visit_FunctionDef(self, node):
        # 함수 선언 목록에 이름 추가
        self.defined_functions.add(node.name)
        self.generic_visit(node)

    def visit_Name(self, node):
        # 변수나 함수가 식별자로 쓰인 경우(참조/호출 등) 기록
        if isinstance(node.ctx, ast.Load):
            self.used_names.add(node.id)
        self.generic_visit(node)

def find_dead_functions(source_code: str):
    tree = ast.parse(source_code)
    finder = DeadCodeFinder()
    finder.visit(tree)
    
    # 선언되었지만 사용 흔적이 없는 함수를 도출
    dead_funcs = finder.defined_functions - finder.used_names
    return dead_funcs

# 분석 예시
code = """
def active_func():
    print("I am used")

def unused_func():
    print("I am dead code")

active_func()  # active_func만 호출
"""
# 결과: {'unused_func'}
print("Dead functions:", find_dead_functions(code))

4. 우리 프로젝트에서의 효과와 가치

vulture를 Stage C의 검증 도구로 채택하면서 deep-wiki 프로젝트가 얻는 가장 큰 기대 효과는 두 가지다.

첫째, RAG 지식의 청정도 극대화이다. 위키 생성 파이프라인에서 vulture 스캔 결과를 활용해 미사용 코드 페이지를 자동으로 배제하거나, 위키 본문 상단에 <!-- status: dead-code --> 같은 경고 주석을 박아둘 수 있다. RAG를 통해 에이전트에게 주입되는 컨텍스트에서 죽은 지식을 원천 차단하여 쓸모없는 토큰 낭비와 엉뚱한 로직 생성을 방지한다.

둘째, 에이전트의 레거시 청소 태스크 지원이다. 리팩토링 미션이 주어졌을 때, 에이전트는 위키의 dead-code 리포트를 보고 안심하고 소스코드 파일에서 함수와 클래스를 날려버릴 수 있다. 보통 데드 코드를 수동으로 지우려면 대대적인 grep 검증이 필요하지만, 위키가 매일 밤 신뢰성 높은 vulture 분석 엣지를 관리하고 있기에 에이전트의 코드 정리 속도가 비약적으로 향상된다.

5. 정리

vulture는 정적 분석으로 사용 흔적이 없는 코드를 사냥하는 도구다. deep-wiki 지식베이스가 Stage C 단계에서 vulture를 연계하면 지식의 불순물을 걸러내는 훌륭한 필터가 되며, 이는 RAG를 소비하는 AI 에이전트의 추론 품질과 리팩토링 능력을 대폭 끌어올려 줄 것이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.