Cursor 코드베이스 인덱싱: 더 잘 작동하게 만드는 방법
Cursor의 코드베이스 인덱싱은 프로젝트에 대해 "똑똑하게" 느껴지게 만드는 핵심이에요. 잘 작동하면 관련성 높은 제안, 정확한 @-멘션, 그리고 실제로 아키텍처를 이해하는 답변을 얻을 수 있어요. 잘 작동하지 않으면 Cursor는 마치 눈먼 것처럼 느껴져요.
이 가이드에서는 인덱싱이 어떻게 작동하는지, 그리고 어떻게 최적화할 수 있는지 설명할게요.
Cursor가 코드베이스를 이해하는 방식
Cursor는 백그라운드에서 두 가지를 구축해요:
-
임베딩 — 코드 파일의 벡터 표현이에요. 질문을 하거나
@를 사용할 때, Cursor는 이 벡터를 검색해 의미적으로 가장 관련성 높은 파일을 찾아요. -
AST(추상 구문 트리) 분석 — Cursor는 코드를 파싱하여 가져오기(import), 함수 정의, 클래스 계층 구조, 파일 간 관계를 이해해요.
이 두 시스템은 함께 작동해요. 임베딩이 "관련해 보이는 것"을 찾고, AST 분석이 "실제로 연결된 것"을 파악하죠.
인덱싱은 프로젝트를 열면 자동으로 시작돼요. 대규모 코드베이스의 경우 초기 스캔에 몇 분이 걸릴 수 있어요. 상태 표시줄에 진행률 표시기가 나타날 거예요.
@-심볼: 올바른 사용법
@ 심볼은 Cursor의 인덱싱에 직접 연결되는 통로예요. 채팅이나 인라인 편집에 특정 컨텍스트를 가져오는 데 사용하세요.
@file — 특정 파일 참조
@src/utils/auth.ts 토큰 검증은 어떻게 작동하나요?
이것이 Cursor가 원하는 정확한 파일을 보도록 보장하는 가장 확실한 방법이에요. 임베딩 검색을 우회하고 전체 파일 내용(컨텍스트 제한 내에서)을 첨부해요.
@folder — 전체 디렉토리 참조
@src/components 여기의 컴포넌트 계층 구조를 설명해줘
아키텍처 질문에 유용하지만, 주의하세요 — 큰 폴더는 컨텍스트 창을 빠르게 소모할 수 있어요.
@code — 특정 심볼 참조
@code:validateUser 이 함수는 어떤 엣지 케이스를 처리하나요?
AST 인덱스를 사용해 정확한 함수, 클래스, 또는 변수 정의를 찾아요. 정확하고 컨텍스트를 효율적으로 사용하죠.
한 함수만 필요할 때는 @file보다 @code:를 선호하세요. 컨텍스트 공간을 절약하고 노이즈를 줄여요.
대규모 프로젝트 최적화
프로젝트에 수천 개의 파일이 있다면 기본 인덱싱이 뭔가를 놓치거나 느리게 느껴질 수 있어요.
실제로 인덱싱된 것 확인하기
Cursor 설정 > General > Codebase Indexing을 열어보세요. 다음을 볼 수 있어요:
- 인덱싱된 총 파일 수
- 마지막 인덱싱 시간
- 파싱에 실패한 파일
컨텍스트 관련성 높이기
모노레포의 경우 Cursor가 때때로 관련 없는 파일을 선택할 수 있어요. 프롬프트에서 명확하게 하세요:
이 질문에는 @packages/api/src만 봐줘. 프론트엔드 코드는 무시해.
거대한 파일 분할하기
몇 천 줄이 넘는 파일은 문제를 일으킬 수 있어요. Cursor가 처음 부분만 인덱싱하거나 임베딩에 어려움을 겪을 수 있어요. 5000줄짜리 유틸리티 파일이 있다면 분할을 고려하세요.
.cursorignore로 파일 무시하기
모든 것이 인덱싱되어야 하는 건 아니에요. 생성된 파일, 빌드 출력, 서드파티 코드는 컨텍스트 공간을 낭비하고 검색 결과를 오염시켜요.
프로젝트 루트에 .cursorignore 파일을 생성하세요:
# 빌드 출력
dist/
build/
.out/
# 의존성
node_modules/
vendor/
# 생성된 파일
*.generated.ts
*.min.js
coverage/
# 대용량 데이터 파일
*.csv
*.json
.cursorignore는 .gitignore와 동일한 문법을 사용하지만 별도의 파일이에요. .gitignore만으로 충분하다고 가정하지 마세요 — Cursor가 이를 자동으로 존중하지는 않아요.
.cursorignore를 편집한 후에는 Cursor를 재시작하거나 재인덱싱이 될 때까지 1분 정도 기다리세요.
인덱싱이 망가졌을 때: 문제 해결
가끔 Cursor가 코드를 "보지" 못하는 것처럼 느껴질 때가 있어요. 체크리스트를 확인해보세요:
1. 파일이 인덱싱되었는지 확인
파일을 연 다음 다음과 같이 물어보세요:
지금 내가 보고 있는 파일이 뭐야?
Cursor가 대답할 수 없다면 해당 파일이 인덱스에 없을 수 있어요.
2. 강제 재인덱싱
명령 팔레트(Ctrl+Shift+P) → "Cursor: Reindex Codebase"
이렇게 하면 전체 인덱스를 처음부터 다시 구축해요. 시간이 걸리지만 대부분의 손상 문제를 해결해요.
3. 파싱 오류 찾기
설정 > General > Codebase Indexing에서 빨간색 오류 표시기가 있는 파일을 확인하세요. 이 파일들은 AST 관계 분석이 되지 않아요.
일반적인 원인:
- 파일의 구문 오류
- 지원되지 않는 언어(Cursor는 약 20개 언어를 잘 지원해요)
- 바이너리나 미니파이된 파일이 소스 코드로 잘못 식별된 경우
4. .cursorignore가 너무 공격적이지 않은지 확인
*.config.*를 무시했는데 vite.config.ts에 중요한 경로 별칭이 포함되어 있다면, Cursor는 가져오기를 이해하지 못할 거예요.
컨텍스트 품질 향상
올바른 파일을 컨텍스트에 넣는 것은 절반의 성공이에요. 그 컨텍스트를 어떻게 사용하는지도 중요하죠.
질문에서 구체적이 되세요
나쁜 예:
인증은 어떻게 작동해?
좋은 예:
@src/auth/middleware.ts에서 JWT 검증은 만료된 토큰을 어떻게 처리해?
컨텍스트를 연결하세요
Cursor가 부분적인 답변을 주면, 전체 질문을 반복하기보다 더 구체적인 @ 참조로 후속 질문을 하세요.
레이트 리미팅을 언급했네. @src/middleware/rateLimit.ts — 리밋은 어떻게 계산돼?
최근 파일 사용하기
Cursor는 최근에 연 파일을 임베딩 검색에서 더 높게 가중치를 둬요. 방금 파일을 열었다면 관련 파일에 대한 @ 참조가 명시적인 멘션 없이도 더 잘 작동할 가능성이 높아요.
복잡한 리팩토링의 경우, 변경할 계획인 모든 파일을 먼저 열어두세요. 이렇게 하면 인덱스가 이 파일들을 관련성 높은 것으로 처리하도록 "준비"시킬 수 있어요.
요약
- Cursor는 코드를 이해하기 위해 임베딩 + AST를 사용해요
- 컨텍스트를 명시적으로 제어하려면
@file,@folder,@code:를 사용하세요 - 노이즈를 제외하려면
.cursorignore를 생성하세요 - 뭔가 이상하게 느껴지면 재인덱싱하세요
- 프롬프트에서 구체적이 되세요 — 인덱스가 파일을 찾지만, 어떻게 사용할지는 사용자가 안내하는 거예요
코드베이스 인덱싱 설정 패널에는 프로젝트의 인덱싱 상태와 오류가 표시돼요.