46개 리포지토리에 걸친 컨텍스트를 AI가 시맨틱하게 검색할 수 있도록 만든 이야기 (후편)

여러분 안녕하세요! 에어클로젯(aircloset)에서 CTO를 맡고 있는 츠지(辻)입니다.

전편에서는 46개 리포지토리에 걸친 운영 시스템의 코드베이스를 정적 분석(Static Analysis)을 통해 하나의 지식 그래프(Knowledge Graph)로 통합한 이야기를 썼습니다. 완성은 되었지만, 마지막에 4가지 과제(시맨틱 검색을 할 수 없음 / 노드 폭발 / 함수 내용은 파일을 보지 않으면 알 수 없음 / 새로운 파서(Parser) 추가에 따른 운영 부하)가 남아 있다는 이야기로 끝을 맺었습니다.

이번에는 이 중, 첫 번째인 「시맨틱 검색을 할 수 없는 문제 (입구 문제)」를 어떻게 해결했는가에 대한 이야기입니다. 나머지 3개는 전편의 상태 그대로 남겨두었습니다 ── 후반부의 「아직 해결되지 않은 과제」 섹션에서, 입구 문제를 해결한 결과 새롭게 드러난 다음 과제들과 함께 정리하겠습니다.

입구 문제부터 시작하는 이유는 단순합니다. 그래프(Graph)가 만들어졌더라도, 그곳에 도달하기 위한 입구가 grep밖에 없다면 결국 AI는 추론에 의존할 수밖에 없습니다. 「사실로서 전달한다」라는 본래의 목적이 성립되지 않습니다. 그래서 입구 문제는 다른 3개보다 먼저 해결할 필요가 있었습니다.

힌트는 db-graph에 있었다

사실, 동일한 구조의 문제를 몇 달 전 다른 영역에서 해결한 적이 있습니다. 바로 db-graph 이야기입니다.

사내에는 여러 서비스에 걸친 방대한 DB 테이블이 있으며, 「어떤 테이블이 어떤 업무에 사용되는지」를 정확하게 모두 파악하고 있는 사람은 거의 없는 상태였습니다. 지식의 폭과 깊이도 사람마다 제각각이라, 전체상을 누구의 머릿속에도 담을 수 없는 구조였습니다. 그래서 ORM 정의로부터 정적 분석으로 스키마(Schema)를 추출하고, Gemini를 사용하여 테이블 설명문을 자동 생성하여 768차원의 벡터(Vector)로 만들어 그래프에 저장함으로써, 자연어 쿼리(Natural Language Query)로 의미 검색을 할 수 있도록 만든 것이 db-graph입니다.

글을 작성할 당시에는 991개 테이블이었지만, 지금은 21개 스키마 / 1,133개 테이블 / 10,815개 컬럼까지 확장되어, 「테이블 이름을 몰라도 자연어로 목적하는 데이터에 도달할 수 있는 것」이 일상적으로 이루어지고 있습니다.

여기서 증명된 패턴이 바로,

정적 분석 그래프 + AI로 생성한 컨텍스트(Context) 주입 = 자연어로 의미 검색이 성립한다

라는 것입니다.

같은 패턴을 code-graph에도 도입하고 싶다

db-graph에서 효과가 있었다면, code-graph에서도 효과가 있을 것입니다. 그렇게 생각했을 때 깨달은 점이 있습니다.

code-graph 안에는 이미 「DB 테이블 노드」가 경계 노드(Boundary Node)로서 존재하고 있다는 점입니다 (전편에서 썼던 경계 노드 중 하나).

즉, code-graph와 db-graph를 접합하는 것만으로도 code-graph가 자동으로 DB의 의미적 컨텍스트를 갖게 됩니다. 어노테이션(Annotation)을 하나도 달지 않고도, 기존 자산만으로 그래프가 한 단계 더 풍부한 의미를 갖게 된다는 뜻입니다.

「그래프를 잇는다」라는 발상이 여기서 처음 나왔습니다. 개별 그래프로 닫히지 않고, 그래프끼리 접합해 나가는 설계로 말이죠.

단, API / Event / Page의 의미 부여는 별도로 필요 ── 모든 함수에 어노테이션을 다는 것은 불가능

db-graph의 접합으로 DB 컨텍스트는 확보되었습니다. 하지만 남은 경계(API / Event)와 그래프의 기점이 되는 Page에는 별도의 의미 부여가 필요합니다. 이것들은 정적 분석만으로는 의미를 포착할 수 없기 때문에, 어떤 형태로든 컨텍스트를 주입해야 합니다.

선택지는 명확했습니다. 어노테이션으로 코드에 직접 작성하는 것뿐입니다 (연재 Part 2에서 썼던 cortex 내부의 지식 그래프와 같은 접근 방식).

다만, 그대로 46개 리포지토리의 모든 함수에 다는 것은 불가능합니다. 함수가 몇만 개나 있는지 알 수 없습니다. 기존 조직에서, 기존 팀이 운영 중인 운영 코드에 나중에 모든 함수 어노테이션을 요구하는 것은 현실적이지 않습니다.

그런데 여기서 또 하나 깨달은 점이 있습니다.

중요한 것은 경계 노드뿐이다. 따라서 경계 주변에만 어노테이션을 달아도 충분한 의미를 갖는다.

라는 점입니다.

AI가 「이 코드를 바꾸면 무엇이 망가지는가」, 「이 API는 다른 어떤 리포지토리에서 호출되는가」를 알고 싶을 때 필요한 것은 함수 내부의 로직 설명이 아니라, 경계의 의도 (= 이 화면은 무엇을 위한 것인가, 이 API는 무엇을 반환하는가, 이 Event는 무엇의 분기점을 나타내는가)입니다.

= 최소한의 어노테이션으로 최대의 의미를 얻는다. 이것이 이후 설계의 핵심이 되었습니다.

annotation graph의 설계

정리하면 다음과 같습니다 (annotation graph는 내부적으로 service-product-graph, 약칭 SPG라고 부릅니다).

3개의 graph가 병렬로 존재하며, 서로 SAME_ENTITY로 연결되어 있는 구조입니다. 계층 관계가 아니라, 어느 graph를 기점으로 해도 다른 graph까지 도달할 수 있는 형태입니다.

code-graph (구조) ── 정적 분석으로 추출한 함수 / 클래스 / 경계 노드 (46개 리포지토리)

db-graph (DB 컨텍스트) ── 1,133개 테이블의 의미 정보

annotation graph (의도) ── 경계 주변에만 @graph-*로 부여한 의도

그리고 AI 에이전트가 호출하는 입구에 MCP 서버가 위치하여, 3개의 graph를 횡단하는 방식으로 동작합니다. db-graph에는 직접 연결하지 않고, annotation graph 측의 MCP가 프록시(Proxy)로서 db-graph도 호출하는 구조로 설계했습니다.

annotation graph의 노드 타입은 Page / Section / Dialog / Field / Action / Api / Task의 7종입니다. 원래는 화면 중심의 설계로 screen-graph라고 불렀으나, backend의 Api / Task까지 확장한 단계에서 이름을 service-product-graph로 변경했습니다.

annotation의 실례

구체적으로는 다음과 같이 작성합니다 (가상의 예시이지만, 형식은 실제와 유사합니다):

/**
* @graph-page /home
* @graph-business 메인 화면. 회원이 현재 대여 중인 아이템의 확인, 구매, 반납을 할 수 있음
...

포인트는 두 가지입니다.

@graph-business가 일본어 의도 텍스트입니다. 이것이 그대로 벡터화되어 시맨틱 검색 (Semantic Search)의 본체가 됩니다.

@graph-flow / @graph-status가 회원 라이프사이클(무료 등록 → 월정액 등록 → 스타일링 루프 → 해지 등)과 회원 구분입니다. "이 화면은 월정액 회원의 스타일링 루프 중에 등장한다"라는 가로축의 의미를 담습니다.

여기에 더해, 테스트 케이스를 도출하는 근원이 되는 @graph-case (조건 분기 패턴)도 있지만, 그 부분은 다른 기회에 다루겠습니다.

annotation을 "현장 개발 플로우에 간섭하지 않고" 운영하는 설계

여기서부터가 실용성의 핵심입니다.

annotation graph를 만들기로 결정한 뒤 직면한 제약 사항은 다음과 같았습니다:

• 현장 엔지니어는 통상적인 프로덕트 개발 + 사람에 의한 리뷰로 진행하고 있음
• 모든 리포지토리에 AI 리뷰가 아직 침투한 것은 아님 (cortex 내부의 전자동 리뷰는 연재 Part 6에서 기술했듯이, cortex 모노레포(Monorepo) 안에서만 성립하는 이야기임)
• annotation 리뷰를 사람이 하는 것은 부담임
• "통상 코드 리뷰는 사람, annotation 리뷰는 AI"라는 분업도, 하나의 PR에 두 계통의 리뷰를 섞게 되어 현장의 혼란을 초래함

즉, **"사람과 AI를 동일한 PR 내에서 혼재시키지 않는 것"**이 필요했습니다.

해결책은 annotation을 물리적으로 별도의 브랜치(Branch)로 분리하는 설계입니다.

• main의 코드는 그대로 유지하며, 현장 엔지니어의 개발 플로우에는 일절 관여하지 않음
• annotation을 부여한 별도의 브랜치를 생성하여, 그곳을 AI 전용 영역으로 만듦
• main이 변경되면 webhook으로 감지
• 차분(Diff) annotation의 생성과 차분 annotation의 리뷰는 annotation branch 측에서 AI가 전자동으로 수행
• 현장 엔지니어 입장에서는 자신은 main을 건드리고 있을 뿐, annotation의 존재를 의意识할 필요조차 없음

이는 연재 Part 6에서 기술한 "AI에게 모든 코드를 통과시키는 게이트 설계"의 이상향을, 기존 조직의 현실적인 조건에 맞춰 분리 설계한 것입니다. cortex(사내 AI 플랫폼)는 자신이 처음부터 조립하고 있는 모노레포이기에 "모든 코드는 반드시 AI 게이트를 통과해야 한다"가 성립하지만, 46개 리포지토리의 운영 환경에서는 성립하지 않습니다. 그래서 이상을 포기하는 것이 아니라, "사람의 개발 플로우"와 "AI의 annotation 운영"을 물리적으로 나누어 둘 다 가동하는 선택을 했습니다.

3개 graph 간의 정합성을 SLO로 수호하기

annotation 운영이 돌아가는 것만으로는, 3개의 graph(code-graph / db-graph / annotation graph)의 접합 품질 (接合の質) 이 보장되지 않습니다. 그래서 graph 전체의 정합성을 기계적으로 검사하는 SLO를 정의하고 있습니다.

주요 규칙은 다음과 같습니다:

• API 체인의 연결── HANDLES_API
  핸들러의 95% 이상이 하류(downstream) 함수 호출을 가질 것 (= API를 받고 아무것도 하지 않는 핸들러가 남아있지 않은가)
• DB 액세스의 완전성── DB 읽기/쓰기 에지(edge)의 80% 이상이 db-graph 측의 컬럼 노드와 접합되어 있을 것 (= code-graph의 DB 경계가 db-graph의 의미와 연결되어 있는가)
• Event 필드의 해결── Event 에지의 70% 이상이 필드 정보까지 가질 것
• 모호한 매칭의 박멸── 이름 해결이 모호한 에지는 0건 (severity: error)

이것들은 요컨대, "서로 경계가 연결되어 있지 않으면 이상하지 않을까?"라는 소박한 질문을 SLO로 구현한 것입니다. 임계값 아래로 떨어지면 알람이 발생하여, graph 전체의 신뢰도를 매일 수호합니다.

전편에서 작성한 경계 분석 cron(연결률 5% 저하 알람)은 code-graph 단독의 이야기였지만, 이것은 3개의 graph를 횡단하는 SLO로, graph들 사이의 접합까지 지키러 가는 메커니즘입니다. 1개 리포지토리에 parser를 추가했다, annotation을 추가로 작성했다, schema가 변경되었다 ── 어떤 일이 일어나도, 다음 날 아침에는 접합 품질의 저하를 확인할 수 있는 상태가 됩니다.

정적 분석 그래프와 annotation 그래프를 SAME_ENTITY 브릿지로 접합

지금까지 "접합"이라고 써왔지만, 실제 접합은 그렇게 순탄하지 않았습니다.

정적 분석으로 추출한 API / Page / Task 노드와, annotation graph에서 작성한 API / Page / Task 노드는 별개의 노드로 생성됩니다. 같은 의미를 가지고 있어야 함에도 불구하고, 이름 / 경로 / 식별자의 표현이 다르기 때문에 기계적으로는 연결되지 않습니다.

이를 접합하기 위해, SAME_ENTITY라는 별도의 에지를 생성하고 있습니다. 3가지 종류의 브릿지:

• API 브릿지── API 경로의 정규화를 4단계의 폴백(fallback)으로 처리
  • 리포지토리별 prefix 변환 (콘솔 계열의 /console/api/를 /api/로 맞추는 등)
  • 버전 제거 (/v1.x/ → /)
  • 파라미터 정규화 (/:id, /{id}를 /:dynamic으로 통일)
  • 완전 일치 → 끝부분 ? 차이 흡수 → :dynamic? 끝부분 제거 → 경계 :dynamic의 동적 dispatch fallback 순으로 단계적으로 완화
• Page 브릿지── 6가지 전략을 우선순위와 함께 적용 (URL 직접 매칭, component 경로, itemId, PascalCase화 매칭, 부모 디렉토리 연결, 경계의 동적 부분 strip 후 부모 URL과 대조)
• Task 브릿지── 리포지토리별 8가지 패턴

그리고 운영상의 함정도 하나 있었습니다. 초기 구현은 INSERT NOT EXISTS로 중복을 피하려 했으나, BigQuery streaming buffer의 반영 지연으로 인해 중복 삽입이 발생하여, 어떤 리포지토리에서는 에지가 106개에서 214개로 배증했습니다. 이는 MERGE INTO로 다시 작성하여 멱등성(idempotency)을 확보함으로써 해결했습니다.

결과: "회원의 구독 요금 계산"으로 graph에 진입

이렇게까지 만든 후, 전편 마지막에 썼던 입구 문제가 해결되었습니다.

"회원의 구독 요금 계산이 틀린 것 같다"

이것을 자연어 그대로 annotation graph에 던지면, 벡터 검색(vector search)을 통해 관련 노드(Page / Api / Function / DB 테이블)가 사실로서 반환됩니다. 거기서부터 SAME_ENTITY를 경유하여 code-graph의 함수로 전달되고, 관련 있는 다른 리포지토리의 호출자(caller) / 호출 대상(callee)까지 추적할 수 있습니다. 나아가 code-graph의 DB 경계에서 db-graph로 넘어가면, 관련 컬럼까지 가져올 수 있습니다.

물론 시작점은 어디든 상관없습니다. "테이블 이름으로 역추적하고 싶다"면 db-graph를 시작점으로, "이 함수의 영향을 보고 싶다"면 code-graph를 시작점으로 하여 동일한 네트워크를 따라갈 수 있습니다. 하나의 자연어 쿼리(Natural Language Query)로도, 혹은 특정 노드(Node)를 시작점으로 해도, **3개의 graph를 횡단하여 관련 전체 코드 + 전체 DB 스키마 (DB Schema)**를 가져올 수 있는 상태가 되었습니다.

전편에서 언급했던 **"graph는 존재하지만, 입구를 찾을 수 없다"**는 문제가 마침내 해소된 순간입니다.

실제 이용 수치

2026년 4월 16일 (첫 실무 투입)부터 집필 시점 (약 2.5개월)까지, annotation graph의 MCP 서버에는 약 50,000회 / 약 73명의 이용 기록이 있습니다. 내역은 다음과 같습니다:

엔지니어 (PI Division + QA + 해당 엔지니어링 팀) ── 약 47,000회 / 51명 -
비엔지니어 (스타일리스트 / 고객 지원 / 몰 업무 / 임원 / 관리 부문) ── 약 2,800회 / 21명

주목해야 할 점은 두 번째 줄입니다. "코드베이스를 자연어로 검색"하는 것은 본래 엔지니어의 도구이지만, 입구 문제가 해결됨에 따라 엔지니어가 아닌 직종에서도 "이 기능은 어떻게 동작하는 거지?", "이 DB에는 무엇이 들어있지?"와 같은 질문을 자신의 언어로 검색할 수 있게 되었습니다.

이는 연재 Part 5에서 다루었던 "코드를 작성하지 않는 사람이 AI로 사양서를 만들 수 있는 시대"와 맞닿아 있는 움직임이며, graph를 의미(Semantic)로 검색할 수 있는 상태가 조직 전체에 효과를 미치고 있음을 보여줍니다. 이용 횟수 비율로는 당연히 엔지니어가 압도적이지만, "사용하기 시작한 직종의 폭"이 넓어졌다는 사실이야말로 입구 문제를 해결한 임팩트입니다.

상위 프론트도어(Front-door)로서의 MCP

이 3개 graph를 횡단하는 입구가 바로 MCP 서버입니다. 서비스 검색 / 서비스 상세 / API 상세 / 데이터 흐름(Data Flow) 추적 / 영향 범위 추적 / 비즈니스 규칙(Business Rule) 전체 검색이라는 6가지 도구를 갖추고 있어, AI 에이전트(AI Agent)가 호출하는 유일한 엔트리 포인트(Entry Point) 역할을 합니다.

특히 주목할 점은, db-graph에는 직접 연결하지 않도록 설계했다는 것입니다. annotation graph 측의 MCP가 프록시(Proxy)로서 db-graph를 호출하는 형태로 구성하여, AI 에이전트 입장에서는 "하나의 MCP에 물어보는 것만으로 모든 것이 나온다"는 상태를 유지하고 있습니다.

이로써 "화면 → API → 코드 → DB → 컬럼"으로 이어지는 풀 체인(Full Chain) 추적이 하나의 MCP 도구로 완결되는 구조가 되었습니다.

4~5월의 시행착오 타임라인

전편에서 13월의 커밋(Commit)을 살펴본 것과 동일한 방식으로, 후편에서는 45월의 주요 커밋을 나열합니다.

4월: 확장 및 브릿지(Bridge) 초기 버전

2026-04-14─refactor(graph): rename screen-graph to service-product-graph

── 화면 중심에서 서비스 전체로 확장하겠다는 선언 -
2026-04-15─feat(graph): add Api and Task node types to service-product-graph parser

── Api / Task 노드 추가 -
2026-04-15─feat(mcp): add cross-graph tools to service-product-graph MCP

── 3 graph 횡단 도구 도입 (상위 프론트도어의 성립) -
2026-04-15─feat(graph): add SAME_ENTITY bridge edges between service-product-graph and code-graph

── 브릿지 초기 버전 -
2026-04-18─feat(graph): resolve Redis keys to code-graph boundary nodes

── Redis를 통한 경계 해결 -
2026-04-19─feat(service-product-graph): add EventBridge EMITS_TO support + SAME_ENTITY bridge

2026-04-20─feat(code-graph, service-product-graph): improve SAME_ENTITY boundary bridge coverage

── 4단계 fallback 확립 -
2026-04-21─feat(auto-review): SPG annotation auto-maintenance pipeline

──AI 자동 유지보수 파이프라인 (= 전편에서 예고한 "사람만으로는 불가능, AI라면 가능하다"의 정체) -
2026-04-22─feat(service-product-graph): add Task SAME_ENTITY bridge to code-graph

── 3개의 브릿지(Bridge) 완성

5월: 안정화와 확장

2026-05-01─ annotation 생성을 로컬 실행에서 Cloud Run Job으로 이관하여 운영 안정화 -
2026-05-05─feat(spg): add mall repos to SPG indexing

── mall 계열 리포지토리(Repo) 도입 -
2026-05-06─feat(spg): add Go-aware parser

──Go 대응 -
2026-05-06〜08─ Page 브릿지 전략을 6개까지 확장, 연결률 100% 달성

이 타임라인을 통해 알 수 있는 점

4월 15일에 "확장 + 횡단 도구 + 브릿지"가 거의 동시에 도입되었고, 그로부터 1주일 동안 "Redis / EventBridge / Task 브릿지 / annotation 자동 유지보수"와 같이 주 단위로 기능을 쌓아 올렸음을 알 수 있습니다.

특히 4월 21일의 annotation 자동 유지보수 파이프라인은, 전편에서 남겨두었던 "사람만으로는 불가능, AI라면 가능하다"라는 숙제를 구현으로 해결한 순간이었습니다. 이때부터 annotation은 "사람이 열심히 쓰는 것"에서 "AI가 쓰는 것을 전제로 운영 설계하는 것"으로 스테이지가 바뀌었습니다.

아직 해결되지 않은 과제

여기까지를 통해 입구 문제는 해결했지만, 물론 모든 것이 깔끔해진 것은 아닙니다.

1. annotation 커버리지(Coverage) 유지

frontend 측은 두텁게 적용되었지만, backend / Go / batch 계열은 아직 희박합니다. "어노테이션이 부여되지 않은 노드"가 존재하는 구조를 완전히 없앨 수는 없습니다. 이는 지속적인 운영 과제입니다.

2. 브릿지(Bridge)의 오접합(Mis-connection) 완전 배제는 구조적으로 미달성

특히 Page 브릿지는 하나의 경계(Boundary)에 대해 여러 개의 annotation Page가 연결되는 케이스가 구조적으로 불가피합니다. 전략을 늘림으로써 커버리지는 100%로 끌어올릴 수 있었지만, "올바르게 연결되어 있음"을 100% 보장하기는 어렵습니다.

3. 동적 분석(Dynamic Analysis)의 부재

그래프(Graph)에 올라와 있는 것은 "edge가 정적으로 존재한다"는 사실뿐이며, "실제로 그 edge가 운영 환경에서 얼마나 사용되는지"는 알 수 없습니다. 정적 분석 그래프에 실제 실행 횟수를 흘려 넣어, dead-code edges를 별도의 시그널로 시각화하는 ── 이 부분은 아직 손을 대지 못했습니다.

4. 신규 리포지토리 추가 시의 조정 부하

새로운 리포지토리가 운영 계통에 추가될 때마다 브릿지의 정규화 규칙이나 리포지토리별 패턴의 조정이 필요합니다. 전편 4번에서 썼던 "새로운 경계 패턴이 나올 때마다 독자적인 parser를 추가하는 운영 부하"와 동일한, annotation graph 측면의 동형(Isomorphic) 과제입니다.

마치며 ── "버린" 것이 아니라 "진화시킨" 것

전편 말미의 보충 설명에서, cortex(사내 AI 플랫폼) 측에서는 code-graph 접근 방식을 조기에 포기하고 어노테이션 기반의 지식 그래프(Knowledge Graph)로 방향을 틀었다는 이야기를 했습니다. "버렸다"라고 써도 무방할 정도로 빠른 판단이었지만, 이 연재를 통해 되돌아보니 정확하게는 "버린" 것이 아니라 "진화시킨" 것이 올바른 표현이었습니다.

진화의 정체는 결국 3가지 그래프의 병렬 연결로 집약됩니다:

code-graph(구조) / db-graph(DB 컨텍스트) / annotation graph(경계의 의도)

이것들을 SAME_ENTITY로 서로 연결하여 MCP를 통해 AI에게 전달합니다. 정적 분석만으로는 도달할 수 없었던 "의미로 끌어오는 것"을, db-graph의 성공 경험을 재사용하고 경계 주변에만 annotation을 부여하는 최소한의 전략으로 성립시켰다는 이야기였습니다.

그리고 또 하나, 연재물인 AI 하네스(Part 1-6)와의 대비로 말하자면 다음과 같이 정리할 수 있습니다:

• AI 하네스 (AI Harness) 연재── 자신이 1부터 조립하는 입장에서, 어떻게 AI와 함께할 것인가
• code-graph-deep-dive 연재 (전편 + 후편)── 기존 조직의 프로덕션 환경에서, 어떻게 AI와 함께할 것인가

= 동일한 사상(AI를 신뢰하지 않고 설계한다)을 바탕으로, 서로 다른 조건에서 구현한 사례였습니다.

긴 글 읽어주셔서 감사합니다.

제가 CTO로 재직 중인 주식회사 에어클로젯(AirCloset Inc.)에서는 AI와 함께 새로운 개발 경험을 만들어 나갈 엔지니어를 모집하고 있습니다. 관심 있는 분들은 꼭 엔지니어 채용 사이트인 에어클로퀘스트(AirCloset Quest)를 확인해 주세요!

Discussion