포스트

Understand-Anything 지식 그래프를 믿어도 될까: AST 관계와 LLM 추론 구분법

Understand-Anything의 지식 그래프는 코드 탐색을 시작할 지도에는 유용하지만, 호출 관계와 비즈니스 의미를 모두 증명하는 원본 자료로 믿어서는 안 됩니다.

구조와 의미는 근거의 강도가 다르다

AST에서 읽은 import, export, 함수와 클래스 같은 구조는 코드에 명시된 사실에 가깝습니다. 반면 “이 파일은 사용자 생명주기의 일부다”, “변경 영향도가 높다” 같은 도메인 분류는 LLM이 이름과 주변 문맥을 바탕으로 추론한 해석입니다. Understand-Anything의 특징은 둘을 결합해 파일 트리보다 읽기 쉬운 비즈니스 중심 지도를 만든다는 데 있습니다.

문제는 화면에서 두 관계가 똑같은 선과 노드로 보이면 독자가 증거 수준을 잊기 쉽다는 점입니다. 지도에서 발견한 관계는 실제 정의, 참조, 테스트를 열어 확인해야 합니다. 특히 동적 호출, 리플렉션, 런타임 설정처럼 정적 구조에서 놓치기 쉬운 연결은 “없음”이 아니라 “아직 관찰되지 않음”으로 다루는 편이 안전합니다.

세 에이전트가 지도를 만드는 순서

원문이 설명한 파이프라인은 다음과 같습니다.

  1. Project Scanner가 디렉터리를 돌며 프레임워크를 식별하고 제외할 빌드 산출물 등을 줄입니다.
  2. File Analyzer가 최대 3개 병렬 프로세스로 파일 목적, import, export, 외부 의존성을 구조화합니다.
  3. Architecture Analyzer가 파일별 결과를 묶어 도메인과 비즈니스 흐름을 추론합니다.

결과는 대시보드, 대화형 탐색, 변경 영향 확인에 쓰는 JSON 지식 그래프로 이어집니다. /understand로 분석을 시작하고, 원문은 /understand-dashboard, /understand-chat, understand-diff, /understand-domain과 --language ko 같은 사용 예를 제시합니다. 명령 이름과 지원 범위는 프로젝트 버전에 따라 달라질 수 있으므로 이 글만으로 설치 절차를 완성했다고 보면 안 됩니다.

원문의 JSON은 공식 스키마가 아니라 개념을 단순화한 예시입니다.

1
2
3
4
5
6
7
8
9

{
  "node_id": "src/auth/login.ts",
  "type": "business_logic",
  "domain": "User Authentication",
  "business_flow": ["User Lifecycle", "Session Management"],
  "exports": ["login", "verify_token"],
  "dependencies": ["src/db/models/user.ts", "src/utils/crypto.ts"],
  "impact_radius": "HIGH"
}

exports와 dependencies는 코드로 역검증하기 쉽지만, domain과 impact_radius는 판단 근거를 추가로 확인해야 합니다. 이 차이를 UI와 리뷰 절차에 표시할 수 있어야 그래프가 새 오해를 만들지 않습니다.

가장 좋은 용도는 질문 범위를 줄이는 일이다

새 팀원이 결제 흐름을 파악할 때 그래프는 먼저 볼 파일과 용어를 제안할 수 있습니다. AI 코딩 에이전트도 전체 저장소를 맹목적으로 읽는 대신 관련 노드에서 탐색을 시작할 수 있습니다. 변경 diff가 어느 도메인에 닿는지 후보를 찾는 데도 도움이 됩니다.

하지만 그래프가 “영향 없음”이라고 답했다고 테스트를 생략해서는 안 됩니다. 오래된 인덱스는 어제 코드의 지도이고, LLM이 만든 도메인 경계는 저장소의 실제 런타임 경계와 다를 수 있습니다. 원문이 언급한 토큰 절감 효과 역시 저장소 크기, 질문 종류, 갱신 빈도에 따라 달라지는 주장이지 고정값이 아닙니다.

초기 전수 스캔 비용도 고려해야 합니다. 파일이 많은 모놀리스에서는 첫 분석에 큰 토큰 비용이 들고, 변경 때마다 충분히 갱신하지 않으면 지도의 신뢰도가 빠르게 떨어집니다. 생성 비용뿐 아니라 최신 상태를 유지하는 비용을 함께 계산해야 합니다.

파일럿은 정답률보다 탐색 개선을 측정한다

도입할 저장소 한 개와 실제 질문 10~20개를 고른 뒤 기존 탐색과 비교해 보세요.

  • 첫 관련 파일을 찾기까지 걸린 시간과 연 파일 수
  • 그래프가 제시한 명시적 의존성의 실제 일치율
  • 도메인 분류 중 사람이 수정한 비율
  • merge 뒤 그래프가 최신 상태가 되기까지의 시간
  • 분석과 질의에 사용한 토큰
  • 영향 분석에서 놓친 파일과 불필요하게 포함한 파일

오탐을 고칠 수 있는 피드백 경로와 인덱스 생성 시각도 함께 보여줘야 합니다. 그래프가 틀렸을 때 원본 코드로 돌아가는 비용이 낮다면 온보딩과 탐색 보조로 가치가 있습니다. 반대로 배포 승인이나 보안 판정을 그래프 하나에 맡겨야만 효과가 나는 구조라면 경계가 잘못된 것입니다.

Understand-Anything의 실용적 가치는 코드를 대신 이해하는 데 있지 않습니다. 사람이 확인해야 할 범위를 더 빨리 좁히고, 구조적 사실과 의미론적 가설을 분리해 대화를 시작하게 하는 데 있습니다.

모든 그래프 관계에 근거를 어떻게 붙일까?

노드와 edge마다 source_type을 두어 AST 추출, 설정 파일, 테스트, 검색 결과, LLM 추론과 사람이 확인한 관계를 구분합니다. AST 관계에는 파일 경로, symbol과 line 위치를, LLM 해석에는 사용한 입력 범위와 모델, 분석 버전을 붙입니다. UI에서 같은 선으로 보이더라도 필터와 색으로 근거 수준을 구분할 수 있어야 합니다.

신뢰 점수 하나로 모든 차이를 숨기지 마세요. import는 명시적이지만 실제 실행되지 않을 수 있고, 동적 호출은 코드에 직접 보이지 않아도 운영에서 중요할 수 있습니다. ‘정적 사실’, ‘런타임 관찰’, ‘의미 가설’처럼 유형을 먼저 보여 주고 각 유형의 한계를 설명합니다. 사람이 도메인 분류를 고치면 원본 추론을 덮어쓰기보다 수정자와 근거를 별도 revision으로 남깁니다.

질문 답변에도 그래프 경로만 출력하지 말고 출발 노드, 따라간 edge, 제외된 후보와 최신 분석 시각을 보여 줍니다. ‘결제에 영향 있음’이라는 결론은 어느 함수, 설정, 테스트가 연결되는지 열 수 있어야 검토자가 빠르게 확인합니다. 근거가 없는 요약은 탐색 제안으로만 표시합니다.

정적 그래프가 놓치는 런타임 연결은 무엇인가?

리플렉션, dependency injection, 플러그인 등록, 문자열로 정한 route와 동적 import는 AST만으로 실제 대상을 확정하기 어렵습니다. 메시지 queue의 producer, consumer, 데이터베이스 테이블을 통한 간접 결합, feature flag와 배포 설정도 파일 import 그래프 밖에 있습니다. 연결이 없다고 ‘영향 없음’으로 표시하지 말고 분석되지 않은 관계 유형을 경고합니다.

테스트, 구성 파일과 코드 검색으로 일부 빈틈을 채울 수 있습니다. framework별 route, DI, migration parser가 있으면 해당 edge에 추출 근거를 붙이고, 지원하지 않는 경우 이름 기반 후보로 낮은 신뢰도에 둡니다. 운영 trace를 사용할 수 있다면 실제 호출 관계를 별도 층으로 추가하되 특정 트래픽 기간에 관찰되지 않았다는 사실이 호출 불가능을 뜻하지는 않습니다.

예를 들어 인증 함수의 명시적 caller가 하나뿐이어도 middleware 설정이나 annotation을 통해 전체 route에 적용될 수 있습니다. 영향 분석은 직접 edge, 간접 구성, 공유 데이터와 테스트 후보를 단계별로 확장해야 합니다. 확장 깊이가 커질수록 오탐도 늘어나므로 ‘왜 포함됐는지’를 각 후보에 표시하세요.

증분 인덱스는 언제 오래된 지도가 되는가?

변경 파일만 다시 분석하면 비용을 줄일 수 있지만 그 파일을 참조하는 소비자와 도메인 요약도 갱신해야 합니다. 파일 삭제, 이동, export 이름 변경과 설정 변화는 역방향 edge를 무효화합니다. 변경 파일, 직접 이웃, 해당 도메인 요약을 하나의 증분 단위로 처리하고 동일 커밋 ID에서 만들어졌는지 확인합니다.

파서 버전, 제외 규칙, 지원 언어 또는 그래프 스키마가 바뀌면 변경 파일만으로 충분하지 않습니다. 전체 재분석이 필요한 조건을 버전에 포함하고, 이전 그래프와 새 그래프가 섞이지 않게 원자적으로 전환합니다. 분석 중 실패한 파일과 마지막 성공 커밋을 대시보드에 표시해 부분 인덱스를 완전한 지도로 오해하지 않게 합니다.

merge가 빠른 저장소에서는 분석 queue가 밀릴 수 있습니다. 최신 커밋과 인덱스 커밋의 차이, 갱신 p95 시간과 실패율을 관측하고 일정 차이를 넘으면 영향 분석을 ‘stale’로 표시합니다. 배포 승인을 그래프에 연결한다면 최신성 조건을 충족하지 못할 때 자동 통과시키지 않습니다.

온보딩과 영향 분석에는 어떻게 질문해야 하는가?

‘이 저장소를 설명해 줘’보다 실제 업무 질문을 사용합니다. 새 팀원에게 로그인 요청이 어느 route, service, 저장소를 거치는지, 실패 로그의 오류 코드가 어디서 만들어지는지, 특정 API 필드를 바꾸면 어떤 소비자 테스트를 볼지 찾게 합니다. 그래프는 시작 파일과 용어를 제안하고 사람은 코드와 테스트를 열어 경로를 확인합니다.

영향 분석은 반드시 포함해야 할 정답 파일과 포함하면 유용한 후보를 분리해 평가합니다. 놓친 직접 소비자는 치명적이지만 관련 문서를 추가한 오탐은 비용이 작을 수 있습니다. recall과 precision뿐 아니라 첫 관련 파일까지의 시간, 실제로 연 파일 수와 사람이 그래프 설명을 고친 비율을 기록하세요.

AI 코딩 에이전트에는 전체 그래프를 주지 말고 질문과 관련된 subgraph, 근거 위치와 최신 시각만 제공합니다. 추론 노드를 사실처럼 다시 학습 문맥에 넣으면 가설이 반복되며 확신이 커질 수 있습니다. 코드 변경 뒤에는 실제 diff와 테스트 결과로 그래프 제안을 검증하고, 잘못된 관계를 피드백합니다.

사설 코드와 분석 비용은 어떻게 통제할까?

파일 내용이 외부 모델로 전송되는지, 생성된 그래프와 대화 로그가 어디에 저장되는지 먼저 확인합니다. 비밀, 생성 자산, vendored code와 대용량 fixture를 제외하되 제외 규칙 때문에 중요한 설정이 사라지지 않는지 검토합니다. 저장소 권한이 다른 사용자가 같은 그래프에서 노드 이름이나 요약을 볼 수 없게 프로젝트, 테넌트 경계를 유지합니다.

초기 전수 스캔은 파일 수보다 분석할 텍스트와 모델 호출량에 좌우됩니다. 언어, 디렉터리별 비용, 실패 재시도와 증분 갱신량을 기록하고 월별 상한을 둡니다. 생성된 도메인 요약이 거의 사용되지 않거나 매번 사람이 고쳐야 한다면 그 영역은 구조 정보만 인덱싱하는 식으로 범위를 줄일 수 있습니다.

파일럿은 작은 예제보다 팀이 실제로 어려워하는 중간 크기 저장소에서 합니다. 기존 IDE 검색, 문서 방식과 비교해 탐색 시간과 정확도가 개선되고, 그래프 최신성과 데이터 경계를 운영할 수 있을 때 확대하세요. 코드 리뷰나 보안 판정을 그래프 하나로 자동 승인하는 것은 파일럿의 목표가 아닙니다.

원문과 버전 확인

함께 읽으면 이해가 이어지는 글

자주 묻는 질문

Understand-Anything 그래프가 보여 주는 관계는 모두 코드 사실인가요?

아닙니다. import, export처럼 AST에서 확인한 사실과 도메인, 영향도처럼 LLM이 추론한 해석이 섞일 수 있습니다. 각 관계의 근거와 신뢰 유형을 확인해야 합니다.

그래프에서 연결이 없으면 변경 영향도 없다고 봐도 되나요?

안 됩니다. 리플렉션, 설정, 메시지, 데이터베이스처럼 정적 분석이 놓치는 런타임 관계가 있습니다. 검색, 테스트, 관측 데이터로 후보를 추가 검증해야 합니다.

대형 저장소는 매번 전체 분석해야 하나요?

기준 전체 스캔 뒤 변경 파일과 의존 이웃을 증분 갱신할 수 있지만 파서, 설정, 스키마 변경 때는 넓은 재분석이 필요합니다. 최신 인덱스 시각을 표시하세요.

참고 자료

THE END / OPSOAI

여기까지 읽었습니다

핵심 장면을 한 번 더 떠올려 보세요. 이해가 남았다면 이 책은 제 역할을 다했습니다.

다른 책 고르기
표지 1 —

←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.

CONTENTS

이 책의 목차

    13개 장 22 분읽는 시간