Cursor 대형 프로젝트 인덱스 거버넌스: 진단부터 재구축까지 완전 가이드

지난주 한 팀의 Cursor 엔지니어링 감사를 도왔습니다. 그 팀의 Monorepo에는 200개가 넘는 패키지가 있었습니다. 프로젝트를 열 때마다 마우스를 코드 위에 올려 힌트를 보려면 4초를 기다려야 했고, 자동완성 응답은 평균 6초가 걸렸습니다. 코드 한 줄을 치고, 커피를 한 모금 마시고, Cursor가 생각을 끝내길 기다리는 식이었습니다. 팀은 이틀 동안 하드웨어를 업그레이드하고, 모델을 바꾸고, Cursor를 다시 설치했습니다. 마지막에야 문제는 모델이나 네트워크가 아니라 Cursor가 기본적으로 전체 packages/ 디렉터리 트리를 컨텍스트로 삼고 있다는 데 있음을 발견했습니다. 이 글에서는 진단 흐름, 설정 템플릿, 재구축 방법을 정리해 10분 안에 Cursor를 다시 매끄럽게 만드는 방법을 안내합니다.

Cursor 인덱스 메커니즘 빠르게 보기 — 5분 만에 느려지는 이유 이해하기

Merkle Tree가 배후의 핵심 주인공입니다. Cursor는 이를 사용해 파일 변경을 추적합니다. 각 파일마다 해시값을 계산하고, 폴더는 그 안에 있는 모든 파일의 해시를 바탕으로 다시 하나의 해시를 계산합니다. 이 과정이 계층적으로 위로 올라가 최종적으로 루트 해시가 만들어집니다. 파일 하나가 바뀌면 그 파일의 해시가 바뀌고, 해당 파일이 들어 있는 폴더의 해시도 바뀌며, 변경은 루트 노드까지 전파됩니다. 그래서 Cursor는 전체 저장소가 아니라 변경된 파일만 다시 인덱싱하면 됩니다.

문제는 여기서 시작됩니다. node_modules 안에는 파일이 50,000개 있을 수 있고, 각각 해시를 계산하면 해시 데이터만 3.2 MB가 됩니다. 더 나쁜 점은 Cursor가 이 파일들에 대한 임베딩 벡터까지 계산해야 한다는 것입니다. npm 패키지 안의 코드는 지금 작성 중인 비즈니스 로직과 별 관련이 없지만, 인덱서는 그 사실을 모릅니다. 모든 것을 성실하게 컨텍스트에 밀어 넣습니다.

Cursor 공식 블로그 데이터에 따르면 99퍼센타일 대형 저장소의 첫 질의에는 4.03시간이 걸립니다. 하지만 팀 협업에는 숨은 장점이 있습니다. 같은 코드베이스를 클론한 경우 평균 92%의 파일이 서로 유사합니다. Cursor는 이 인덱스 데이터를 재사용해 첫 질의 시간을 21초까지 줄입니다. 인덱스가 깨끗하다면 동료가 프로젝트를 열 때 이미 계산된 캐시를 바로 사용할 수 있습니다.

한 문장으로 말하면: 인덱스가 느린 이유는 Cursor의 계산이 느려서가 아니라, 너무 많은 것을 인덱싱하고 있고 그중 상당수가 인덱싱할 필요가 없는 파일이기 때문입니다.

진단 흐름 — 3단계로 진짜 원인 찾기

설정을 급하게 바꾸지 말고 먼저 진단하세요.

1단계: 인덱스 상태 확인. 프로젝트를 열고 상태 표시줄 오른쪽 아래의 작은 아이콘을 봅니다. 계속 “Indexing…”이 표시되거나 진행률 표시줄이 특정 퍼센트에서 멈춰 있다면 인덱스에 문제가 생긴 것입니다. Cmd+Shift+P를 누르고 Windows에서는 Ctrl+Shift+P를 누른 뒤 “Show Cursor Logs”를 입력합니다. 로그의 마지막 몇 줄을 보면 “Indexing 1,342 files…” 같은 출력을 볼 수 있습니다. 숫자가 5000을 넘나요? 그렇다면 거의 원인이 맞습니다.

2단계: 의심 디렉터리 나열. 터미널을 열고 프로젝트 루트에서 find . -type d -name "node_modules" -o -name "dist" -o -name "build" -o -name ".git" | wc -l을 실행합니다. 흔한 “인덱스 킬러”는 다음과 같습니다.

폴더 유형	파일 수 규모	인덱스 영향
node_modules/	50,000+	해시 계산과 임베딩 벡터 공간을 대량으로 사용
dist/, build/	5,000+	바이너리 산출물이라 AI가 코드를 이해하는 데 의미가 적음
.git/	3,000+	버전 관리 데이터라 인덱싱 가치가 낮음
coverage/	2,000+	테스트 리포트 HTML/JSON으로 노이즈 데이터가 많음
.next/, .nuxt/	10,000+	프레임워크 컴파일 캐시이며 컴파일 산출물을 포함

3단계: CPU와 메모리 관찰. Activity Monitor(macOS) 또는 Task Manager(Windows)를 열고 Cursor 프로세스를 봅니다. CPU가 80% 이상으로 치솟고 메모리 사용량이 4GB를 넘나요? 인덱스가 해시와 임베딩 벡터를 미친 듯이 계산하고 있다는 뜻입니다.

아래 의사결정 트리는 빠른 원인 파악에 도움이 됩니다.

증상	잠재 원인	우선 조치
입력 지연이 3-5초	인덱싱 파일이 너무 많음	.cursorignore를 추가해 의심 폴더 제외
검색이 버벅이고 @Codebase 응답이 느림	바이너리/생성 산출물을 스캔 중	dist/, .nuxt/ 등 제외
@ 기호에서 후보가 나오지 않음	컨텍스트 창 한도 초과	인덱스 범위를 줄이거나 Monorepo 분리
인덱스가 99%에서 멈춤	symlink 루프 또는 파일 권한 문제	.cursorignore가 재귀 폴더를 제외하는지 확인

Zest의 Troubleshooting Guide에 따르면 Cursor 불안정 문제의 90%는 확장 충돌과 부적절한 인덱스 설정에서 옵니다. 여러분은 높은 확률로 후자에 해당합니다.

.cursorignore 설정 — 주요 상황을 덮는 3가지 템플릿

.cursorignore 문법은 .gitignore와 완전히 같습니다. 프로젝트 루트에 두면 됩니다. Cursor가 이 파일을 읽으면 그 안에 적힌 내용은 인덱싱하지 않습니다.

템플릿 1: JavaScript/TypeScript 프로젝트

# 의존성 패키지
node_modules/
.npm/
.yarn/

# 빌드 산출물
dist/
build/
out/
.next/
.nuxt/

# 테스트와 커버리지
coverage/
.nyc_output/

# 로그와 임시 파일
*.log
*.tmp
.DS_Store

프로젝트가 Monorepo를 사용한다면, 예를 들어 pnpm workspace라면 단계적으로 인덱싱할 수 있습니다. 먼저 모든 패키지를 제외하고, 현재 수정 중인 패키지만 다시 허용하는 방식입니다.

# Monorepo 단계별 인덱싱
packages/*/
!packages/api/        # 현재 개발 중인 패키지는 허용
!packages/shared/     # 참조가 필요할 수 있는 공유 라이브러리
node_modules/
dist/

템플릿 2: Python 프로젝트

# 가상 환경
venv/
.venv/
env/
.env/

# 컴파일 캐시
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# 패키징 산출물
*.egg-info/
build/
dist/

# Jupyter Notebook
.ipynb_checkpoints/

Python의 가상 환경에는 파일이 수천 개 들어 있는 경우가 많고, 대부분은 서드파티 라이브러리 소스입니다. venv/를 제외하면 인덱스 크기를 90% 줄일 수 있습니다.

템플릿 3: Go 프로젝트

# 의존성 캐시
vendor/

# 빌드 산출물
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib

# 테스트 캐시
*.test
*.out
coverage.txt

Go의 vendor/ 디렉터리는 node_modules/와 비슷합니다. 의존성 파일이 쉽게 수천 개까지 늘어납니다.

효과 비교: Developer Toolkit 데이터에 따르면 기본 인덱스 설정, 즉 .cursorignore가 없는 상태의 컨텍스트 정확도는 노이즈가 너무 많아 65%에 그칩니다. 합리적인 제외 규칙을 추가하면 정확도는 98%까지 올라갑니다. 쉽게 말해 파일의 20%를 제외하고 정확도는 50% 높이는 셈입니다.

Monorepo 다중 저장소 워크스페이스 설정

Monorepo에 서비스가 수십 개 있고, 열 때마다 인덱스가 끝날 때까지 기다려야 한다면 .code-workspace 파일로 현재 수정할 몇 개 패키지만 로드하는 방법을 고려할 수 있습니다.

프로젝트 루트에 workspace.code-workspace 파일을 만듭니다.

{
  "folders": [
    {"name": "payments", "path": "./services/payments"},
    {"name": "shared-libs", "path": "./libs"}
  ],
  "settings": {
    "cursor.indexing.maxFileSize": 512000,
    "cursor.chat.scopeSelection": "activeFolder"
  }
}

그다음 전체 저장소가 아니라 이 파일을 Cursor로 엽니다. 사이드바에는 payments와 shared-libs 두 폴더만 보이고, 다른 서비스는 시야에서 완전히 사라집니다. 인덱스도 이 두 디렉터리만 대상으로 실행되므로 속도가 10배 빨라질 수 있습니다.

핵심 설정 설명:

• maxFileSize: 512000: 512KB를 넘는 파일은 인덱싱하지 않아 큰 JSON/CSV가 컨텍스트를 터뜨리는 일을 피합니다.
• scopeSelection: "activeFolder": Agent 모드는 현재 활성화된 폴더에서만 컨텍스트를 가져오며 패키지를 넘어 검색하지 않습니다.

이 설정은 대형 Monorepo에 특히 유용합니다. iamraghuveer의 글에 따르면 서비스 10개가 각각 파일 5000개를 가진 프로젝트에서는 인덱스 데이터가 1-5GB에 이를 수 있습니다. 전부 로드하면 CPU와 메모리 모두 버티기 어렵습니다. 현재 작업 중인 패키지만 로드하면 인덱스 크기를 약 50MB까지 낮출 수 있습니다.

언제 워크스페이스 설정을 쓰면 좋을까요?

• Monorepo가 20개 이상의 패키지를 넘고, 각 패키지가 비교적 독립적일 때
• 특정 패키지 안에서 개발하며 패키지 간 참조가 자주 필요하지 않을 때
• 팀원들의 역할 분담이 뚜렷하고 각자 다른 서비스를 맡을 때

패키지 간 의존성이 무겁다면, 예를 들어 마이크로서비스끼리 공유 라이브러리를 자주 호출한다면 .cursorignore를 쓰는 편이 더 안정적입니다. 필요 없는 것은 제외하고 필요한 것은 남기면 되며, 워크스페이스 파일을 계속 바꿔 열 필요가 없습니다.

캐시 정리와 인덱스 재구축 — 버벅임에서 매끄러움으로

가끔 설정을 바꿨는데도 인덱스가 여전히 이상할 때가 있습니다. 캐시에 예전 해시 데이터가 남아 있을 수 있습니다. 이때는 정리가 필요합니다.

빠른 정리(먼저 시도)

Cmd+Shift+P를 누르고 “Reindex Codebase”를 입력한 뒤 선택합니다. Cursor가 프로젝트를 다시 스캔하고 인덱스를 재구축합니다. 이 과정은 보통 수십 초가 걸리고, 대형 프로젝트에서는 2-3분이 필요할 수 있습니다. 완료되면 상태 표시줄의 인덱스 진행률이 0%에서 100%까지 올라갑니다. 물 한 모금 마시며 기다리면 됩니다.

심층 정리(빠른 정리가 효과 없을 때)

Cursor의 설정 디렉터리를 삭제합니다. 운영체제별 경로는 다음과 같습니다.

운영체제	설정 디렉터리 경로
macOS	~/Library/Application Support/Cursor
Windows	%APPDATA%\Cursor
Linux	~/.config/Cursor

Cursor를 닫고 위 디렉터리를 찾아 삭제합니다. 또는 다른 곳으로 옮겨 백업해도 됩니다. Cursor를 다시 열면 설정과 인덱스를 새로 초기화합니다.

⚠️ 주의: 설정 디렉터리를 삭제하면 사용자 설정(settings.json), 키보드 단축키, 확장 설정이 모두 지워집니다. 먼저 User/settings.json 파일을 백업하는 것을 권장합니다.

완전 초기화 단계

1. Cursor 닫기
2. ~/Library/Application Support/Cursor/User/settings.json 백업하기, 파일이 있다면
3. 전체 설정 디렉터리 삭제하기
4. Cursor 다시 시작하기
5. 프로젝트가 다시 인덱싱될 때까지 기다리기, 몇 분 걸릴 수 있음
6. settings.json을 다시 복사해 사용자 설정 복원하기

Zest의 Troubleshooting Guide에 따르면 재시작 → 캐시 정리 → 상태 확인 흐름은 5분 안에 인덱스 문제의 80%를 해결할 수 있습니다. 대부분의 경우 빠른 정리만으로 충분합니다. 심층 정리는 .cursorignore를 수정한 뒤에도 인덱스가 계속 비정상일 때만 사용하세요.

언제 인덱스를 재구축해야 할까요?

• 상태 표시줄이 계속 “Indexing…”을 표시하고 10분 넘게 움직이지 않을 때
• 자동완성 응답이 정상적인 1-2초에서 5초 이상으로 느려졌고 며칠 동안 계속될 때
• .cursorignore를 수정했지만 @Codebase 검색 결과에 제외한 파일이 여전히 포함될 때

결론

Cursor 인덱스가 느린 핵심 원인은 인덱싱하지 않아도 될 파일을 너무 많이 인덱싱하는 것입니다. 해결 방향은 단순합니다. 진단하고, 제외하고, 재구축하세요.

실행 체크리스트:

1. 대형 프로젝트를 열고 Cmd+Shift+P에서 “Show Cursor Logs”를 입력해 인덱싱 파일 수를 확인합니다.
2. 5000개를 넘으면 즉시 .cursorignore를 만듭니다. 이 글의 템플릿을 복사해도 됩니다.
3. node_modules/, dist/, .git/ 같은 생성 산출물 디렉터리를 제외합니다.
4. “Reindex Codebase”를 실행하고 인덱스가 끝날 때까지 기다립니다.
5. 여전히 느리다면 CPU와 메모리 사용량을 확인하고, .code-workspace로 현재 작업 중인 패키지만 로드하는 방법을 고려합니다.

장기 유지보수 제안:

• 새 의존성이나 빌드 설정을 추가할 때마다 .cursorignore 업데이트가 필요한지 확인합니다.
• 팀 프로젝트에서는 .cursorignore를 저장소 루트에 추가해 모든 사람의 설정을 일관되게 유지합니다.
• 대형 Monorepo는 오래된 서비스의 인덱스를 정기적으로 정리하고, 활발하게 개발 중인 패키지만 남깁니다.

지금 바로 시도해 보세요. 10분 안에 Cursor가 다시 매끄러워지는 것을 느낄 수 있습니다. 자동완성 응답은 1-2초로 돌아오고, @Codebase 검색은 더 이상 버벅이지 않으며, 마우스 오버 힌트도 즉시 나타납니다. 개발 생산성이 다시 돌아올 것입니다.

---

참고 자료

이 글의 데이터 출처:

• Securely indexing large codebases - Cursor — Cursor 공식 블로그, 2026-01-27
• Performance Optimization for Cursor - Developer Toolkit — 기술 블로그, 2026-05-28
• Cursor Codebase Indexing for Multi-Repo Workspaces - iamraghuveer — 개인 블로그, 2026-04-25
• A Practical Guide to Cursor Troubleshooting - Zest — 기술 블로그, 2025-12-24
• How to setup Cursor for Large Scale Repositories - NOVA AI — 기술 블로그, 2026-04-07