소스코드 분석부터 RAG까지, 사내 문서 검색 시스템 구축하기 (1)

API를 연동해야 하는데 문서가 없다. Swagger는 있지만 필요한 정보가 빠져있고, API 명세와 실제 동작이 다른 경우도 많다. 담당자가 바뀌면서 "이 API가 왜 이렇게 동작하는지" 아는 사람도 없다. 결국 매번 담당 개발자를 찾아 물어봐야 한다. 이런 상황은 꽤 많은 팀에서 겪는 문제이다.

이 글에서는 소스코드를 AI로 분석하고, 검색 가능한 문서 시스템을 만든 과정을 정리한다. 결론부터 말하자면, 전체 파이프라인은 다음과 같다.

소스코드 -> SSoT -> 문서 -> 검색

 

1. 발생한 문제

신규 서비스 PoC를 진행하면서 기존 시스템의 API를 연동해야 했다. 문제는 세 가지였다.

(1) 개발 히스토리가 단절되었다.
팀 변동이 잦은 조직에서 흔히 발생하는 문제인데, 코드에 주석도 없고 위키도 비어있어서 이 API가 왜 이렇게 동작하는지 파악할 방법이 소스코드뿐이었다.

(2) API 명세와 실제 동작이 불일치했다.
Swagger 페이지는 있지만 응답 필드 설명이 빠져있거나, 실제 동작과 다른 경우가 많았다. 결국 소스코드를 직접 봐야 정확한 스펙을 파악할 수 있었다.

(3) 불필요한 커뮤니케이션 비용이 발생했다. 
소스코드를 볼 시간도 없으니 담당 개발자에게 물어본다. 그 사람도 바쁘니까 답변까지 시간이 걸린다. 질문하는 쪽도, 답변하는 쪽도 업무 흐름이 끊긴다.

Notion이나 Confluence에 정리하는 방법도 있다. 하지만 수십 개 서비스, 1000개 이상의 엔드포인트를 사람이 수동으로 문서화하는 건 현실적이지 않다. 문서를 만들어도 코드가 바뀌면 금방 낡는다.

그래서 방향을 바꿨다. 사람이 문서를 쓰는 게 아니라, 소스코드를 AI로 분석해서 문서를 자동 생성하자. 그리고 그 문서를 사람과 AI 모두 검색할 수 있게 만들자.

 

2. 파이프라인 3단계로 설계

전체 구조는 다음과 같다. 각 단계가 왜 필요한지 계속해서 설명하겠다.

 

1단계 : SSoT 구축

SSoT는 Signle Sourece of Truth, 단일지식공급원이다. 같은 정보가 여러 곳에 흩어져 있으면 버전이 달라지고 뭐가 맞는지 모르게 된다. 이 데이터는 여기만 보면 된다라는 원칙이 SSoT이다.

AI를 활용해서 백엔드 소스코드를 정적분석했다. 컨트롤러, 서비스, 게이트웨이, 코드를 읽어서 API 명세를 추출하고, 실제 API를 호출해서 응닶값까지 JSON으로 확보했다.

분석 대상:
├── Gateway (API 라우팅)
├── Controller (요청 처리)
├── Service (비즈니스 로직)
└── 프론트엔드 (관리자 페이지)  ← 교차검증용

데이터 신뢰도를 끌어올리기 위해 프론트엔드 코드와 교차검증도 진행했다. 관리자 페이지의 코드를 분석해서 "실제로 호출되는 API"와 "코드에는 있지만 사용되지 않은 API"를 구분했다. 이 과정에서 미사용 API나 중복 엔드포인트를 발견하는 부수 효과도 있다.

최종 산출물은 1,000개 이상의 엔드포인트 명세가 담긴 JSON과 MD 파일이다. 모든 문서와 검색 인덱스가 여기서 파생된다.

 

2단계 : 문서 생성

SSoT가 있으면 사람이 읽을 수 있는 문서를 만들 수 있다. MDX 형식으로 약 500개 문서를 생성했다.
문서 유형에 따라 생성 방식이 다르다.

문서 유형	생성 방식	설명
API 명세(endpoint)	스크립트 + AI 작성	SSoT JSON을 읽어 테이블/코드블록 자동 생성
비즈니스 플로우 (flow)	AI 작성	SSoT를 참조하며 흐름을 서술
심층 분석	AI 작성	내부 로직을 분석하고 설명
데이터 매핑	스크립트 + AI 작성	변환 규칙을 구조화

이 문서들을 React 웹사이트로 배포해서 팀원 누구나 브라우저에서 접근할 수 있게 했다.

 

3단계 검색 인터페이스

약 500개의 문서가 있어도 원하는 정보를 찾을 수 없으면 소용 없다. 문서를 검색하게 만드는 게 3단계이다.
여기서 핵심 설계 결정이 있었다. 하나의 검색 엔진 위에 세 가지 인터페이스를 얹는 구조로 만들었다.

세 인터페이스 모두 같은 인덱스, 같은 검색 로직을 공유한다. 소비자만 다를 뿐이다. 이렇게 설계한 이유는 단순하다. 검색 품질을 개선하면 세 인터페이스가 동시에 좋아진다. 유지보수 포인트가 하나이다.

- 웹 검색 : 개발자가 웹에서 ⌘+ K 단축키를 통해 빠르게 문서를 찾는 용도. 가장 기본적인 인터페이스
- RAG 챗봇 : 주문 취소 시 환불은 어떻게 처리되나요? 같은 자연어 질문에 문서 기반으로 답변. 검색 키워드를 떠올리기 어려울 때 유용
- MCP 서버 : AI 코딩 도구가 개발 중에 직접 문서를 조회. 사람이 개입할 필요 없이 AI가 알아서 컨텍스트를 확보한다.

 

3. 기술 선택 과정

검색 시스템을 만들 때 가장 먼저 떠오르는 건 벡터DB + 임베딩 조합이다. 하지만 이 프로젝트에서는 BM25(키워드 기반 검색)만으로 시작했다. 이유는 다음과 같다.

(1) 규모가 작다
약 500문서, 1500청크, 인덱스 약 8MB, 서버 메모리에 전부 올라간다. 외부 DB가 필요없다.

(2) 도메인 특성
API 문서는 메소드명, 경로, 파라미터명 같은 고유 키워드가 명확하다. 키워드 매칭만으로 충분히 커버된다.

(3) 외부 의존 제거
벡터 DB를 쓰면 인프라 하나가 더 필요하다. 운영 복잡도가 올라간다. 사내 도구에 과한 구성이다.

물론 BM25에도 한계가 있다. "숙소 등록"으로 검색하면 "객실 생성 API"를 못 찾는다. 같은 의미인데 다른 단어를 쓰면 매칭이 안된다. 이건 문서가 10개여도 발생하는 본질적인 한계이다. 규모가 커지면 임베딩 기반 벡터 검색을 붙여서 하이브리도 갈 계획이다.

 

JSON 파일과 메모리

인덱스를 DB에 넣지 않고, JSON 파일 하나를 서버 시작 시 통째로 메모리에 올린다.

// 서버 시작 시 1회 실행
const index = JSON.parse(fs.readFileSync("search-index.json", "utf-8"));
// 이후 모든 검색은 이 객체에서 배열 순회로 처리

약 8MB JSON을 JSON.parse()하면 JS 객체로 약 20MB 정도가 메모리에 올라간다. 256MB 서버에는 10% 이하. 검색할 때 디스크 I/O도 없고 네트워크 요청도 없다. 그냥 RAM에 있는 배열을 for문으로 돌리는 것이다.

단점은 인덱스가 바뀌면 서버를 재시작해야 한다는 것. 하지만 사내도구 수준에서는 수용 가능하다.

 

4. 배포 구성

백엔드는 Fly.io의 auto-stop/start를 활용했다. 트래픽이 없으면 VM이 자동 정지되고, 요청이 오면 자동으로 꺠어난다. 사내 도구라 24시간 트래픽이 있는 게 아니니까, 쓸 때만 비용이 발생한다.

Docker 이미지는 멀티스테이지 빌드로 약 70MB. 빌드 도구는 첫 번째 스테이지에서만 쓰고, 런타임 이미지에는 컴파일된 JS + 프로덕션 의존성 + 인덱스 데이터만 넣는다.

 

마무리

이 글에서 다룬 내용을 정리하면

1. API 명세 부제 + 히스토리 단절 + 커뮤니케이션 병목은 많은 팀에서 겪는 문제이다.
2. 소스코드 -> SSoT -> 문서 -> 검색이라는 3단계 파이프라인으로 설계했다.
3. 하나의 검색 엔진 위에 세 가지 인터페이스(웹 검색, RAG, MCP)를 얹었다
4. 벡터 DB 대신 BM25 + JSON 메모리 로드로 시작한 이유는 규모와 도메인 특성 때문이다.

다음 편에서는 실제 구현을 다룬다. MDX를 어떻게 청킹하고, BM25로 어떻게 스코어링하고, RAG 챗봇이 어떻게 문서를 찾아서 답변을 만드는지 코드와 함께 설명한다.

https://ehdnsdlek.tistory.com/88

소스코드 분석부터 RAG까지, 사내 문서 시스템 구축하기 (2)