이 서비스만 고치면 되겠지? AI가 놓치는 숨은 의존성을 추적하는 법

AI 코딩 도구를 1년 넘게 전면 도입한 채널톡 팀이 부딪힌 천장과, 그것을 그래프 DB 기반 지식 그래프로 뚫으려 한 시도다. 컨텍스트 윈도우 한계는 모델 발전으로 완화되고 있지만 진짜 문제는 따로 있었다. 마이크로서비스로 구성된 환경에서 AI 도구는 현재 열려 있는 단일 레포만 볼 수 있어 서비스 간 의존성을 파악하지 못한다.

핵심 포인트

UserChat에 필드를 추가해 달라고 하면 AI는 열린 레포의 관련 API만 짚지만, 실제로는 다른 서비스가 간접적으로 그 데이터에 접근하고 여러 프론트엔드가 여러 경로로 소비한다.
이 숨은 의존성을 모르고 배포하면 장애로 이어진다. 하나의 마이크로서비스만 열어놓고 작업하면서 다른 서비스는 전혀 못 보는 상황과 같다.
필요한 것은 의미적으로 비슷한 문서를 찾는 문제가 아니라 A를 바꾸면 무엇이 영향받는지를 따라가는 관계 추적 문제다.
엔티티에서 서비스로, API로, 다시 서비스로 이어지는 호출 체인은 벡터 유사도로 발견할 수 없다.
정적 분석은 구조는 알아내지만 의미는 모른다. 테이블이 있다는 건 알아도 그것이 무엇을 뜻하는지는 코드만으로 알 수 없다.

상세 정리

컨텍스트 한계의 증상: 대화가 길어지거나 코드베이스가 커지면 앞서 한 결정을 잊고 일관성 없는 코드를 만들거나, 심지어 방금 수정한 부분을 원래대로 되돌리는 경우도 생긴다. 다만 이 영역은 모델과 도구 개선으로 완화되고 있다고 본다.
그래프 DB가 강한 이유: 관계형 DB로 "이 서비스를 호출하는 서비스를 3단계까지 찾아라"를 구현하면 깊이가 깊어질수록 JOIN이 늘고 성능도 떨어지지만, 그래프 DB는 동일한 패턴으로 표현되고 각 노드가 연결된 노드의 직접 참조를 가져 탐색이 본질적으로 빠르다.
지식 그래프가 답해야 할 세 질문: 어떤 서비스가 이 엔티티를 소유하고 접근하는가(탐색 범위 최소화), 이 API를 바꾸면 어떤 서비스가 영향받는가(파급 효과 사전 파악), 그리고 직접 의존뿐 아니라 간접 의존까지 추적해 숨은 의존성을 발견하는 것이다.
3계층 구조: 코드 분석 계층이 GitHub의 마이크로서비스 코드를 파싱해 API·테이블·큐·이벤트 같은 구조 정보를 추출하고, 지식 저장소 계층이 도메인 지식을 더해 Neo4j에 저장하며 Git 기반 YAML로 버전 관리하고, 쿼리 인터페이스 계층이 MCP 서버로 Claude Code나 Cursor가 실시간 조회하게 한다.
언어별 파서: 서비스들이 Java·Go·TypeScript 등 여러 언어로 작성돼 있어 언어별 전용 파서를 구현했고, 각 서비스가 제공하는 API의 경로와 HTTP 메서드, 파라미터 등을 추출한다.
사람이 이 모든 정보를 수작업으로 정리하면 몇 주가 걸릴 작업을 정적 분석으로 자동화해 기반 데이터를 빠르게 구축했다.
정적 분석의 한계와 보완: 3단계로 나눴다. 1단계는 코드 파싱으로 JSON 스키마를 뽑고(1,029개 컬럼 정보), 2단계는 LLM으로 엔티티 YAML 기본 구조를 자동 생성하며, 3단계에서 도메인 전문가가 비즈니스 의미를 추가하고 검수한다.
그래프 스키마의 진화 3단계: 처음에는 서비스·API·테이블 간 기본 관계를 구축했고, 다음으로 DDD 개념을 그래프에 녹여 BoundedContext 7개에서 DomainEntity 42개, BusinessRule 19개로 이어지는 계층을 만들었으며, 마지막에 테이블 컬럼 수준까지 내려가 정밀 매핑을 달성했다.
최종 구조: 마이크로서비스를 나타내는 노드, REST API 엔드포인트 노드 등 9개 노드 타입과 10개 이상의 관계 타입으로 6,000개 이상의 노드와 수만 개의 엣지를 구성했다.
주요 관계 타입으로 서비스가 엔티티를 소유하거나 접근하는 관계, 엔티티가 테이블에 저장되는 관계, 엔티티가 비즈니스 규칙에 의해 관리되는 관계를 든다.
저자는 코드를 생성하는 것과 시스템을 이해하는 것이 전혀 다른 문제이며 현재 AI 도구는 후자에서 크게 부족하다고 정리한다.