신뢰도 태그가 지정된 코드 지식 그래프(Code Knowledge Graph)를 통한 AI 코딩 에이전트의 그라운딩(Grounding)

공개 사항: 이것은 저의 개인 오픈 소스 프로젝트(forensic-deepdive, Apache-2.0)입니다. dev.to 커뮤니티는 에이전트 툴링(agent tooling)에 대해 날카로운 의견을 내는 경향이 있어, 비판을 받고자 이곳에 공유합니다.

AI 에이전트를 위한 대부분의 "레포지토리 컨텍스트(repo context)" 툴링은 검색(retrieval) 방식입니다. 파일을 임베딩(embed)하고, 프롬프트와 유사해 보이는 청크(chunks)를 가져온 뒤, 모델이 이를 바탕으로 추론하기를 기대하는 방식이죠. 이는 괜찮은 기준점(baseline)이지만, "어떤 텍스트가 관련 있어 보이는가"에 대해서는 답할 수 있어도, "이것을 변경하면 무엇이 망가지는가", "어떤 파일이 핵심적인 역할을 하는가(load-bearing)", 또는 "이 코드의 소유자는 누구이며 버스 지수(bus factor)가 1인가"에 대해서는 답할 수 없습니다. 그것들은 그래프(graph)와 git 히스토리(git-history)에 관한 질문들입니다.

제가 이러한 질문에 답할 수 있는 도구를 어떻게 만들었는지, 무엇을 잘 수행하는지, 그리고 명시적으로 아직 무엇을 수행하지 못하는지에 대해 설명하겠습니다.

[

]

문제점: 검색(retrieval)은 그라운딩(grounding)이 아니다

현재의 AI 코딩 툴 흐름은 대체로 검색 증강 컨텍스트(retrieval-augmented context) 방식에 안착했습니다. 즉, 저장소를 임베딩하고, 프롬프트와 가장 유사한 청크를 가져와 모델이 그 위에서 추론하게 만드는 방식입니다. 이는 유용하며 올바른 기준점입니다. 하지만 구조적인 한계가 있습니다.

유사도 검색(Similarity retrieval)은 "어떤 텍스트가 관련 있어 보이는가?"라는 질문에 답합니다. 숙련된 엔지니어가 반사적으로 답하는 다음과 같은 질문들에는 답하지 못합니다:

이 함수를 변경하면, 파일 전반에 걸쳐 이행적(transitively)으로 실제로 무엇이 망가지는가?
2,000개의 파일 중 핵심적인 역할을 하는 20개 파일은 무엇인가?
역사적으로 이 모듈을 담당해 온 사람은 누구이며, 버스 지수(bus factor)가 1인가?
이 프론트엔드 호출이 백엔드 핸들러로 연결되는가, 연결된다면 어떤 것인가?

이것들은 구조적이고 역사적인 질문들입니다. 코사인 유사도(cosine similarity)가 아니라, 그래프(graph)와 git 히스토리(git history)를 통해 답할 수 있는 문제들입니다. forensic-deepdive는 바로 이러한 전제를 바탕으로 구축된 오픈 소스(Apache-2.0) 도구입니다.

생성 결과물

저장소를 대상으로 지정하면 세 가지의 조정된 출력물을 생성합니다:

지속적인 임베디드 지식 그래프 (persistent embedded knowledge graph, <repo>/.deepdive/graph.lbug).
MCP를 인식하는 모든 에이전트에게 9개의 복합 도구 (composite tools)를 노출하는 MCP 서버.
사람이 읽을 수 있는 투영물 (projection)로서의 5가지 내구성 있는 마크다운 아티팩트 (markdown artifacts).

이 도구는 tree-sitter (9개 언어에 걸친 파싱), 중심성을 위한 PageRank 스타일의 저장소 맵 (repo-map), 임베디드 그래프 데이터베이스 (embedded graph database), 그리고 이력 레이어를 위한 git log를 기반으로 구축되었습니다. 추출 과정은 LLM 호출, 네트워크, API 키가 전혀 필요 없이 완전히 로컬에서 실행됩니다. 클라우드 및 시맨틱 (semantic) 기능은 엄격하게 선택 사항 (opt-in)입니다.

그래프 스키마 (The graph schema)

노드 유형 (Node types): 파일 (File), 심볼 (Symbol), 모듈 (Module), 커밋 (Commit), 작성자 (Author), 엔드포인트 (Endpoint), 데이터베이스 테이블 (DbTable).

엣지 유형 (Edge types): DEFINES, MEMBER_OF, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, TOUCHED_BY_COMMIT, AUTHORED_BY, CO_CHANGES_WITH, 그리고 경계를 넘나드는 세트: HANDLES, CALLS_ENDPOINT, ROUTES_TO, INJECTS, PERSISTS_TO.

구조적 엣지 (CALLS/IMPORTS/EXTENDS)는 AST 분석에서 비롯됩니다. 이력 엣지 (TOUCHED_BY_COMMIT/AUTHORED_BY/CO_CHANGES_WITH)는 git에서 가져옵니다. 경계를 넘나드는 엣지는 프로토콜별 추출기 (protocol-specific extractors)에서 가져옵니다. 이들은 하나의 그래프에 존재하므로, 에이전트는 구조적인 질문과 이력에 관한 질문을 한 번에 물어볼 수 있습니다.

가장 중요한 설계 결정: 정직함 (honesty)

코드 그래프 도구의 실패 모드는 '조용한 확신'입니다. 만약 그래프가 실제로는 서로 다른 파일에 있는 이름이 같은 두 개의 심볼일 뿐인데 CALLS 엣지가 있다고 단언한다면, 에이전트는 이를 신뢰하여 전혀 건드릴 필요가 없는 코드를 "수정"할 것입니다. 숨겨진 거짓 양성 (false positives)을 동반한 높은 재현율 (high recall)은 자율 루프 (autonomous loop) 내에서 매우 위험합니다.

따라서 모든 엣지(edge)와 생성된 모든 주장(claim)에는 신뢰도 태그(confidence tag)가 부여됩니다:

EXTRACTED: AST(추상 구문 트리) 또는 git log로부터 결정론적(deterministic)으로 추출됨. 하나의 사실(fact).
INFERRED: 깔끔하게 해결된 휴리스틱(heuristic) (임포트 그래프 순회(import-graph walk), 수신자 타입 추론(receiver-type inference), 단일 동일 이름 후보). 신뢰도는 높지만 유도된(derived) 정보임.
AMBIGUOUS: 여러 후보가 존재함; 해결사(resolver)가 모호성을 제거할 수 없었으므로, 추측하는 대신 모든 후보를 드러냄.

이는 모든 곳에서 나타납니다. HOTPATHS는 행별로 신뢰도 혼합(confidence-mix) 컬럼을 포함하고 있어, 깔끔하게 해결된 심볼(대부분 EXTRACTED/INFERRED)과 동일 이름 충돌(AMBIGUOUS)로 뒤덮인 심볼을 구분할 수 있습니다. 도구는 각 주장(claim)에 대해 얼마나 신뢰할 수 있는지 알려줍니다.

다섯 가지 프로토콜을 위한 하나의 추상화: 엔드포인트(Endpoint) 핵심 요소

경계 간 추적(Cross-boundary tracing)은 대부분의 도구가 멈추는 지점인데, 프로토콜마다 서로 다르게 보이기 때문입니다. forensic-deepdive는 이 모든 것을 단일 Endpoint 조인 노드(join node)를 통해 라우팅합니다. HTTP, MCP 도구, 레지스트리 디스패치(registry dispatch), gRPC, 그리고 메시징/AMQP라는 다섯 가지 프로토콜이 해당 노드 하나와 프로토콜에 무관한(protocol-blind) 조인을 공유합니다. 프론트엔드 호출은 전체 스택에 걸쳐 단일 ROUTES_TO 엣지로 백엔드 핸들러(handler)로 해결됩니다.

이러한 설계의 결과로: 여섯 번째 프로토콜을 추가하는 것은 새로운 키 빌더(key-builder)와 제공자/소비자 추출기(provider/consumer extractors)를 만드는 작업이 됩니다. 이는 트레이스(trace), 방출(emit), 또는 서빙(serve) 레이어에는 전혀 영향을 주지 않습니다. 표출(surfacing) 레이어는 설계상 프로토콜에 무관합니다. trace(symbol)는 어떤 프로토콜이 엣지를 생성했는지에 관계없이 프론트엔드 호출 -> CALLS_ENDPOINT -> Endpoint -> HANDLES -> 핸들러 -> CALLS tail을 일반적인 방식으로 순회합니다.

에이전트가 인지하지 못하는 역사적 레이어

Git 고고학 (Git archaeology)은 부수적인 요소가 아닌 일급 레이어 (first-class layer)입니다. 즉, 코드 변경량 (churn), 기여도 비율(%)을 포함한 주요 저자, 버스 팩터 (bus factor), 공동 변경 클러스터 (co-change clusters, 항상 함께 변경되는 파일들), 그리고 결함 근접성 (defect proximity, 버그 수정 커밋과의 근접성) 등을 포함합니다. 실제 테스트에서 이 레이어는 일관되게 가장 신뢰도가 높고 가치가 높은 레이어였으며, 리스크가 어디에 집중되어 있는지와 누구에게 물어봐야 하는지를 파악하는 가장 빠른 방법이었습니다. 그래프가 형태를 알려준다면, 고고학은 이야기를 들려줍니다.

9가지 MCP 도구

impact: CALLS 엣지(edge)에 대한 영향 범위 (blast-radius) BFS (너비 우선 탐색), 깊이별 버킷화 (depth-bucketed), 신뢰도 필터링 가능.
context: 단일 호출을 위한 종합 도구 (one-call kitchen sink): 정의 (definition) + 호출자 (callers) + 피호출자 (callees) + 부모/멤버 (parents/members) + 최근 커밋 (recent commits) + 주요 저자 (dominant author) + 인사이트 (insights).
archaeology: 코드 변경량 (churn), 주요 저자, 버스 팩터 (bus factor), 공동 변경 클러스터 (co-change cluster), 결함 근접성 (defect proximity).
flow: 사이클 탐지 (cycle detection) 기능이 포함된 CALLS 기반 DFS (깊이 우선 탐색).
query: 로우 Cypher (raw Cypher), 또는 하이브리드 자연어 검색 (NL retrieval) (BM25 + 구조적 신호 + 선택적 오프라인 시맨틱 (semantic), RRF 융합).
record_insight: 심볼 (symbol)에 대해 검증된 학습 내용을 영구 저장.
recall_insights: 저장된 인사이트를 최신순으로 호출.
visualize: 특정 이웃 영역에 대한 제한된 Mermaid 다이어그램; 엣지 점선 스타일로 신뢰도 인코딩.
trace: 엔드포인트 조인 노드 (Endpoint join node)를 가로지르는 크로스 스택 (cross-stack) 기능 슬라이스.

각 도구 설명은 약 200 토큰 미만으로 유지되어, 9개 도구 모두가 에이전트의 턴당 메타데이터 예산 (per-turn metadata budget) 안에 여유롭게 들어갑니다.

사용자가 아무것도 연결하지 않아도 에이전트가 통합하는 방법

추출(extract) 시, 도구는 대상 저장소(repo)에 파일이 없을 경우에만 작성되는 심(shim) 파일들을 삽입합니다: CLAUDE.md, AGENTS.md, .cursor/rules 파일, .continue/rules 파일, Claude Code 플러그인 매니페스트(manifest), 그리고 5가지 단일 의도 스킬(codebase-exploring, -debugging, -impact-analysis, -refactoring, -onboarding)이 포함됩니다. 각 스킬의 설명에는 해당 스킬을 언제 사용해야 하는지, 그리고 언제 형제 스킬로 라우팅(route)해야 하는지가 인코딩되어 있습니다.

결과적으로: 새로운 에이전트가 저장소를 열면 AGENT_BRIEF.md를 자동으로 발견하고, 프롬프트 없이도 작업에 적합한 스킬을 선택하며, 9개의 MCP 도구를 사용할 수 있게 됩니다. record_insight/recall_insights 쌍은 컨텍스트 윈도우(context window)보다 오래 지속되는 메모리를 제공합니다. (수동으로 편집된 파일은 절대 덮어쓰지 않으며, 심(shim) 파일은 빈 부분만 채웁니다.)

잘 작동하는 부분과 그렇지 않은 부분

저는 의도적으로 적대적인 검토(adversarial review)를 수행했습니다. 즉, 새로운 에이전트가 모든 MCP 답변을 실제 파일과 대조하여 교차 검증하도록 했습니다. 솔직한 점수표는 다음과 같습니다:

높은 신뢰도(High-trust): git 고고학(git archaeology), 정확한 Cypher/구조적 쿼리(structural queries), 그리고 사전 생성된 브리프(briefs). 이들은 정확하며 검증 가능했습니다.

신뢰 전 검증 필요(Verify-before-trusting): impact()/context()/flow()는 매우 훌륭한 단서 생성기(lead generator)이지만, 정밀도(precision)보다는 재현율(recall)을 최적화합니다. 동적 디스패치 언어(Dart)의 경우 일부 CALLS 엣지(edge)는 실제로는

범위(scope)에 대해서도 명확히 말씀드립니다. v0.8은 보조 분석(assisted-analysis) 도구입니다. 에이전트에 이를 시딩(seeding)하는 것이 실제 문제를 측정 가능한 수준으로 더 빠르게 해결할 수 있는지에 대한 자율적인 엔드 투 엔드(end-to-end) 질문은 아직 증명되지 않았습니다. 모델 프리(model-free) 로컬라이제이션(localization) 파일럿이 리포지토리(repo)에 기록되어 있으나(정적 시드는 약한 사전 확률(weak prior)입니다), 전체적인 측정에는 GPU와 프런티어 메인 에이전트(frontier main-agent) 엔드포인트가 필요하므로 v0.9로 연기되었습니다. 자율 실행(autonomous-execution)에 대한 주장은 하지 않습니다.

로드맵 (v0.9)

핵심은 인터랙티브 CLI입니다. 기존의 커맨드 러너(command-runner, CI 및 에이전트용으로 유지됨) 위에 지속적인 deepdive 세션, 그래프를 열어둔 상태를 유지하는 query REPL, Textual TUI 그래프 브라우저, 그리고 가이드가 포함된 onboard 위저드(wizard)가 계층적으로 추가됩니다. 또한 엔드 투 엔드 유용성 측정과 보고 정밀도(reporting-precision)에 관한 몇 가지 수정 사항이 포함될 예정입니다. 전체 연기된 작업 목록은 리포지토리에 있습니다.

사용해 보기 / 기여하기

uv tool install forensic-deepdive
forensic extract /path/to/repo

또한 MCP 레지스트리(https://registry.modelcontextprotocol.io, io.github.Dhevenddra/forensic-deepdive) 및 Claude Code 플러그인(/plugin marketplace add Dhevenddra/forensic-deepdive)에서도 확인할 수 있습니다.

이 프로젝트는 Apache-2.0 라이선스이며 기여에 열려 있습니다. CONTRIBUTING.md와 아키텍처 불변량(architectural invariants)이 문서화되어 있습니다. 에이전트 컨텍스트(agent context), 코드 그래프(code graphs), 또는 개발자 도구(developer tooling) 분야에서 작업하신다면 여러분의 이슈(issue), PR, 그리고 솔직한 비판을 환영합니다.