바이브코딩으로 만든 프로젝트가 어느 정도 커지면 이상한 일이 생깁니다. AI에게 “이 기능 좀 고쳐줘”라고 했는데, 엉뚱한 파일을 열어보다가 이미 있는 함수를 또 만듭니다. 그때마다 “그건 저기 있어”라고 파일 경로를 손으로 짚어주게 되죠.
처음엔 AI가 멍청해진 줄 알았는데, 당연한 일이었습니다. AI는 제 프로젝트 폴더를 통째로 외우고 있지 않습니다. 한 번에 읽을 수 있는 양(컨텍스트)이 정해져 있어서 파일이 수백 개가 되면 길을 잃습니다. 더 나쁜 건 AI가 답을 찾겠다고 파일을 하나씩 열어볼 때예요. 파일을 열 때마다 그 내용이 컨텍스트를 잡아먹어서, 정작 코드를 고칠 즈음엔 앞의 대화를 잊어버립니다.
이걸 해결해준 게 MCP였습니다.
MCP가 뭔가
MCP(Model Context Protocol): AI에게 외부 도구·데이터를 붙여주는 표준 연결 규격.
쉽게 말해 AI에게 눈과 손을 달아주는 것입니다. 다 외우게 하는 대신, 필요할 때 직접 찾아볼 수 있는 창구를 열어주는 겁니다.
제가 쓰는 건 codebase-memory-mcp
코드 인덱싱 MCP는 여러 개가 있는데, 저는 codebase-memory-mcp를 씁니다. 이게 다른 것들과 결정적으로 다른 점이 있습니다.
보통의 코드 검색 도구는 텍스트를 찾아줍니다. “login이라는 단어가 있는 파일” 같은 식이죠. 반면 이건 코드베이스를 지식 그래프로 만듭니다.
지식 그래프: 개념들을 점(노드)으로, 그 사이 관계를 선(엣지)으로 이어 만든 지도. 여기선 “함수 A가 함수 B를 호출한다” 같은 관계가 저장됩니다.
즉 단어를 찾는 게 아니라 구조를 이해합니다. 그래서 이런 질문이 가능해집니다.
- “이 함수 누가 호출해?” → 호출 체인을 거슬러 올라가 추적
- “내가 이걸 고치면 어디가 깨져?” → git 변경사항에서 영향받는 코드와 위험도를 분류
- “이 프로젝트 구조가 어떻게 생겼어?” → 라우트·핫스팟 등으로 개요 제공
- “안 쓰는 죽은 코드 있어?” → 아무도 호출하지 않는 함수 탐색
위 네 가지는 전부 텍스트 검색으로는 못 하는 일입니다. 함수 이름이 겹치거나 호출이 여러 파일에 흩어져 있으면, 단어를 아무리 잘 찾아도 “누가 이걸 쓰는지”는 답이 안 나오니까요.
효과: 토큰을 99% 아낍니다
이 도구가 내세우는 숫자가 인상적입니다. 구조 쿼리 다섯 번에 약 3,400토큰인데, 같은 걸 AI가 파일을 하나씩 열어보며 알아내면 약 412,000토큰이 든다고 합니다. 토큰을 아낀다는 건 비용 문제만이 아닙니다. AI가 정작 중요한 일에 쓸 머리를 남겨둔다는 뜻이고, 앞서 말한 “탐색하다 앞의 대화를 잊는” 문제가 바로 여기서 생깁니다.
저도 효과를 바로 체감했습니다. 프로젝트를 인덱싱한 뒤 “이전에 완료한 작업과 해야 할 작업을 리스트업해줘” 라고 했더니, AI가 코드를 스스로 훑어서 정리해줬습니다. 예전 같으면 제가 파일을 하나하나 열어 보여주며 설명해야 했던 일입니다.
설치와 사용법
설치가 의외로 간단합니다. 단일 실행 파일이라 파이썬이나 Node 같은 런타임을 따로 깔 필요가 없습니다. macOS·리눅스는 스크립트 한 줄이고, Windows는 릴리스에서 install.ps1을 받아 실행합니다.
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
편한 건 설치 스크립트가 알아서 에이전트를 찾아 설정해준다는 점입니다. Claude Code·Cursor·VS Code 등을 자동 감지해 등록하므로 설정 파일을 손댈 일이 거의 없습니다. 설정이 끝나면 명령어를 외울 필요도 없습니다. 평소 말하듯 부탁하면 AI가 알아서 맞는 도구를 골라 씁니다.
| 이렇게 말하면 | AI가 하는 일 |
|---|---|
| “이 프로젝트 인덱싱해줘” | 코드베이스를 그래프로 색인 |
“ProcessOrder 누가 호출해?” | 호출 체인 추적 |
| “이번 변경으로 어디가 영향받아?” | git diff → 영향 심볼·위험도 분류 |
| “아키텍처 개요 보여줘” | 라우트·핫스팟 등 구조 요약 |
표에서 눈여겨볼 건 왼쪽이 전부 평범한 한국어 문장이라는 점입니다. 도구 이름도, 옵션도 외울 필요가 없습니다. 처음 인덱싱만 한 번 시켜두면 그 뒤로는 파일이 바뀔 때마다 알아서 갱신됩니다.
“인덱싱”이 실제로 뭘 하는 건지 궁금하실 텐데, 책의 목차를 만드는 일이라고 보시면 됩니다. 코드베이스를 전부 읽어서 “이런 함수가 있고, 얘는 저기서 불리고, 이 파일은 저 파일을 가져다 쓴다”는 지도를 미리 만들어두는 거예요. 그러니 첫 인덱싱은 프로젝트 크기만큼 시간이 걸립니다. 대신 그건 한 번뿐입니다. 목차를 한 번 만들어두면 그 뒤론 “이 내용 몇 쪽에 있지?”를 책 전체를 넘겨보지 않고도 답할 수 있는 것과 같아요. 앞서 나온 3,400토큰 대 412,000토큰의 차이가 정확히 이 차이입니다.
실제로 겪은 함정: .mcp.json을 그대로 커밋하면 안 된다
설정 파일에는 내 컴퓨터에만 맞는 경로가 들어갑니다. 실행 파일 위치가 대표적이고, 저는 에러 추적용으로 붙인 Sentry MCP 주소에 조직 이름까지 들어 있었습니다. 이걸 그대로 깃허브에 올리면 다른 사람은 물론 다른 PC의 나에게서도 깨집니다. 그래서 이렇게 갈랐습니다.
.mcp.json→ gitignore에 넣어 커밋에서 제외.mcp.json.example→ 틀만 담아 커밋하고, 각자 복사해서 자기 경로로 수정
gitignore: “이 파일은 깃에 올리지 마”라고 지정하는 목록. 개인 설정처럼 공유하면 안 되는 걸 넣습니다.
이 .example 짝짓기는 저만의 요령이 아니라 널리 쓰이는 관행입니다. 설정 파일에는 보통 두 가지가 섞여 있거든요. “이런 항목들이 필요하다”는 구조(모두에게 같음)와 “내 경우엔 이 값이다”라는 내용(각자 다름). 구조는 공유해야 남이 따라 할 수 있고, 내용은 공유하면 안 되거나 공유해봤자 안 맞습니다. 그래서 구조만 담은 .example을 올려두고 실제 값이 든 파일은 각자 로컬에 두는 거예요. 나중에 새 PC에서 프로젝트를 받아도 .example을 복사해 값만 채우면 되니, 미래의 저를 위한 메모이기도 합니다.
그래서 뭘 하면 되나
| AI가 자꾸 엉뚱한 파일을 뒤진다 | 🔴 설치 후 “이 프로젝트 인덱싱해줘” |
| 파일 위치·함수를 매번 짚어준다 | 🔴 “~ 누가 호출해?”처럼 말로 묻기 |
| 고치기 전 영향 범위가 궁금하다 | 🟡 “이번 변경으로 어디가 영향받아?” |
| 설정에 내 PC 경로·조직명이 있다 | 🔴 .mcp.json은 gitignore + .example |
한 문장으로 요약하면: AI가 프로젝트에서 길을 잃는다면, 더 잘 설명하려 애쓰지 말고 스스로 찾게 만들어라.
프롬프트를 아무리 길게 써도 제가 아는 만큼만 알려줄 수 있고, 그마저 매번 반복해야 하는 수작업입니다. 반면 창구를 한 번 열어주면 그 뒤로는 AI가 알아서 찾습니다. 공식을 다 외우게 하는 것보다 찾아보기 좋은 참고서를 쥐여주는 게 나은 것과 같은 이치이고, 프로젝트가 커질수록 이 차이는 점점 벌어집니다.