Cursor Codebase 인덱스 완전 가이드: 원리, 설정, @ 기호 실전

화면에는 Cursor가 제안한 다섯 번째 잘못된 수정안이 떠 있었습니다.

“이 로그인 버그 좀 고쳐줘”라는 요구는 분명히 명확했습니다. 그런데 Cursor가 내놓은 코드는 프로젝트 안에 이미 있는 auth 유틸 함수를 전혀 모르고, 검증 로직을 새로 한 번 더 쓰라고 했습니다. 더 황당한 건 코드를 utils 디렉터리에 넣으라고 했는데, 정작 이 프로젝트에는 그런 폴더가 없었다는 점입니다.

그 순간 깨달았습니다. AI가 아무리 똑똑해도 프로젝트 전체를 보지 못하면, 결국 코드를 쓸 줄 아는 기계일 뿐입니다. 내놓는 제안은 늘 핵심에서 살짝 비켜갑니다.

이후 20분을 들여 Codebase 인덱스와 .cursorignore 파일을 설정했습니다. 다시 시도하자 Cursor는 바로 이해했습니다. auth 유틸을 찾아냈을 뿐 아니라, 세 군데에서 반복 작성된 검증 코드까지 발견하고 공통 모듈로 묶자고 제안했습니다. “이제야 AI가 내 프로젝트를 이해하네”라는 느낌이 꽤 짜릿했습니다.

Cursor 인덱스의 기본 원리

Codebase 인덱스란 무엇인가요?

솔직히 말해, 처음 “인덱스”라는 말을 들었을 때 저도 조금 막막했습니다. 뭔가 대단해 보이지만, 이해하고 나면 사실 간단합니다.

도서관에서 책을 찾는 상황을 떠올려 보세요. 목록 시스템이 없다면 책장을 한 줄씩 훑어야 하고, 하루 종일 찾아도 못 찾을 수 있습니다. 하지만 목록 카드가 있으면 책 제목이나 키워드를 입력해 몇 초 만에 위치를 찾을 수 있습니다.

Cursor의 Codebase 인덱스도 같은 원리입니다. 프로젝트 전체에 “지능형 목록”을 만들어 AI가 관련 코드를 빠르게 찾게 해 줍니다. 추측으로 답하는 것이 아니라 실제 코드에서 근거를 찾는 방식입니다.

구체적으로 말하면, 인덱싱은 코드 파일을 한 번 훑고 각 함수, 클래스, 변수가 무엇을 하는지 분석한 뒤, 이를 수학적인 방식(벡터화)으로 “태그”처럼 표시하는 과정입니다. 그러면 AI에게 질문했을 때 가장 관련 있는 코드 조각을 매우 빠르게 매칭할 수 있습니다.

인덱싱의 여섯 가지 핵심 단계

기술 세부 사항을 길게 풀지는 않겠습니다. 너무 지루해질 수 있으니까요. 다만 이 흐름을 이해하면 왜 가끔 인덱싱이 느린지, 왜 .cursorignore 설정이 중요한지 알 수 있습니다.

1단계: 파일 스캔과 전처리

Cursor가 프로젝트를 열면 가장 먼저 모든 파일을 스캔합니다. 이때 .gitignore와 .cursorignore에 표시된 파일은 건너뜁니다. 그래서 .cursorignore를 설정하지 않았다면 Cursor가 node_modules를 성실하게 인덱싱하고 있을 수 있습니다. 그 안에는 파일이 수만 개 있습니다.

2단계: 코드 분할

파일 스캔이 끝나도 Cursor는 파일 전체를 하나의 덩어리로 다루지 않습니다. 꽤 똑똑하게 함수, 클래스, 논리 블록 단위로 나눕니다. 예를 들어 1000줄짜리 유틸 파일은 30개의 작은 블록으로 나뉘어 각각 인덱싱될 수 있습니다. 이렇게 해야 질의할 때 정확도가 높아집니다.

3단계: 벡터 임베딩(핵심 단계)

이 단계는 조금 추상적이지만 쉽게 말하면, 벡터화는 코드를 숫자 배열로 바꾸는 작업입니다. 이 숫자 배열은 코드의 “지문” 같은 역할을 합니다. 기능이 비슷한 코드는 지문도 비슷합니다. 예를 들어 서로 다르게 작성된 두 로그인 함수라도, 벡터화 후에는 수학적 공간에서 서로 가까운 위치에 놓입니다.

4단계: 벡터 데이터베이스 구성

모든 코드 블록의 “지문”은 로컬 데이터베이스에 저장됩니다(Cursor는 FAISS 계열 기술을 사용합니다). 이 데이터베이스가 바로 인덱스의 실체이며, 사용자의 컴퓨터에 저장되고 클라우드로 업로드되지 않습니다.

5단계: 질의 매칭

사용자가 “로그인 로직을 최적화해 줘”라고 입력하면 Cursor는 이 문장도 벡터화한 뒤, 데이터베이스에서 가장 가까운 “지문”을 가진 코드 블록을 검색합니다. 이 과정은 매우 빠르며 밀리초 단위로 처리됩니다.

6단계: 컨텍스트 주입

관련 코드를 찾은 뒤 Cursor는 그 코드 조각들을 AI에게 전달할 컨텍스트에 넣습니다. AI가 실제 코드를 보게 되니 답변도 자연스럽게 더 믿을 만해집니다.

인덱스가 왜 이렇게 중요한가요?

비교 실험을 해 본 적이 있습니다. 같은 요구 사항을 두고 인덱스를 쓰지 않으면 Cursor는 현재 열려 있는 파일만 볼 수 있어서 엉뚱한 답을 자주 냈습니다. 인덱스를 켜면 관련 파일 3-5개를 자동으로 연결하고, 바로 쓸 수 있는 해결책을 제시했습니다.

차이는 작지 않았습니다. 한 번은 API 계층, 데이터 계층, UI 계층 세 파일의 상호작용이 얽힌 버그가 있었습니다. 인덱스가 없을 때는 세 파일을 모두 수동으로 @에 넣고, AI에게 파일 간 관계를 한참 설명해야 했습니다. 인덱스가 있으니 “왜 사용자 데이터가 업데이트되지 않지?”라고 묻기만 해도 Cursor가 세 파일을 직접 찾았고, 제가 놓친 네 번째 파일(middleware의 데이터 검증)까지 찾아냈습니다.

개인정보와 보안

“클라우드 업로드”, “AI가 코드 분석” 같은 표현을 보면 걱정하는 분들이 많습니다. 저도 처음에는 그랬습니다.

안심할 만한 사실을 몇 가지 정리하면 다음과 같습니다:

1. 코드는 평문으로 저장되지 않습니다. 인덱스에는 소스 코드가 아니라 벡터(숫자 배열)가 저장됩니다
2. 파일 경로는 암호화됩니다. 누군가 인덱스 파일을 가져가더라도 어떤 프로젝트인지 알기 어렵습니다
3. Privacy mode. Cursor 설정에는 개인정보 보호 모드가 있으며, 켜면 벡터도 로컬 밖으로 나가지 않습니다

솔직히 민감한 프로젝트(금융, 의료 등)라면 저는 Privacy mode를 켭니다. 하지만 일반적인 Web 프로젝트나 개인 프로젝트라면 기본 모드로도 충분하고, 보안 측면에서 큰 문제는 없습니다.

@ 기호 완전 가이드

Cursor를 처음 쓸 때는 @가 그냥 @인 줄 알았습니다. 그런데 알고 보니 꽤 많은 차이가 있었습니다. 잘못 쓰면 시간을 낭비할 뿐 아니라 AI가 엉뚱한 제안을 내놓기도 합니다.

이 장에서는 6가지 @ 기호의 사용법, 적합한 상황, 장단점을 모두 정리합니다. 읽고 나면 언제 어떤 것을 써야 하는지 감이 잡힐 것입니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

@Codebase - 프로젝트 수준 컨텍스트

용도: AI가 프로젝트 전체의 코드 구조와 로직을 이해하게 합니다.

가장 강력한 @ 기호이면서도 가장 과소평가되기 쉬운 기능입니다. @Codebase를 입력하면 Cursor가 인덱스 데이터베이스를 기반으로 질문과 가장 관련 있는 코드 조각을 자동으로 찾아냅니다.

적합한 상황:

• 여러 파일을 넘나드는 문제 추적: “사용자가 로그인한 뒤 데이터가 왜 동기화되지 않지?”
• 아키텍처 수준 질문: “이 프로젝트는 권한 검증을 어디에서 처리하지?”
• 새 프로젝트 학습: “이 프로젝트의 라우팅은 어떻게 구성되어 있지?”

제 실제 경험: 한 번은 문서가 거의 없는 오래된 프로젝트를 맡았습니다. 파일이 천 개가 넘었습니다. 저는 바로 @Codebase 결제 흐름은 어떻게 구현되어 있나요?라고 물었습니다. Cursor는 몇 초 안에 API 호출, 데이터 검증, 콜백 처리까지 이어지는 관련 파일 5개를 찾아 전체 흐름을 정리해 줬습니다. 수동으로 코드를 뒤졌다면 반나절은 걸렸을 겁니다.

한계:

• 인덱스 품질에 의존하므로 설정이 엉성하면 효과가 떨어집니다
• 전체 데이터베이스를 검색해야 하므로 질의 속도가 상대적으로 느립니다(보통 1-3초)
• 초대형 프로젝트(10만 줄 이상)에서는 일부 주변부 코드를 놓칠 수 있습니다

@Files - 정확한 파일 참조

용도: AI가 특정 파일 몇 개에만 집중하도록 명확히 지정합니다.

가장 직관적인 방식입니다. @Files를 입력하면 파일 선택기가 뜨고, 하나 이상의 파일을 선택할 수 있습니다. AI는 선택한 파일만 보고 다른 곳으로 벗어나지 않습니다.

적합한 상황:

• 문제가 어느 파일들에 있는지 분명히 알고 있을 때
• 특정 파일의 코드를 수정해야 할 때
• AI가 관련 없는 코드를 연결하지 않게 하고 싶을 때

실전 사례: 어떤 컴포넌트를 리팩터링해야 했고, 컴포넌트 본문, 스타일 파일, 테스트 파일 세 개가 관련되어 있었습니다. @Files로 이 세 파일을 선택한 뒤 “이 컴포넌트를 함수형 방식으로 바꿔줘”라고 요청했습니다. AI는 세 파일만 보고 매우 집중된 수정안을 내놓았고, 불필요한 제안이 없었습니다.

장점: 정확하고 빠르며 제어하기 쉽습니다
단점: 관련 파일을 미리 알아야 하고, 빠뜨리기 쉽습니다

@Folders - 디렉터리 수준 참조

용도: 전체 폴더의 코드를 컨텍스트로 참조합니다.

문제가 특정 모듈 안에 있다는 것은 알지만, 정확히 어떤 파일인지 모를 때 적합합니다.

적합한 상황:

• “/components/auth/ 디렉터리의 모든 컴포넌트를 최적화해 줘”
• “/api/ 디렉터리 코드에 보안 문제가 있는지 확인해 줘”
• 특정 모듈의 코드를 일괄 처리할 때

주의 사항: 폴더가 너무 크면 컨텍스트 제한을 넘을 수 있습니다. 일반적으로 파일 10개 이하의 디렉터리가 적당합니다. 파일이 수십 개라면 AI가 앞부분만 보고 뒤쪽은 잘릴 수 있습니다.

@Code - 정확한 코드 조각

용도: 특정 함수, 클래스, 코드 블록을 참조합니다.

꽤 유용한 기능입니다. 코드 한 조각을 선택한 뒤 우클릭으로 Add to Chat을 선택하거나, @Code를 입력한 뒤 함수명을 선택할 수 있습니다.

적합한 상황:

• “이 validateUser 함수에 버그가 있는데 봐줘”
• “이 로직을 더 명확하게 리팩터링해 줘”
• 코드 리뷰에서 특정 조각만 지정할 때

제가 가장 좋아하는 사용법: 1000줄짜리 유틸 파일 안에서 50줄짜리 함수 하나만 AI가 보게 하고 싶을 때가 있습니다. @Code로 그 함수를 선택하면 AI가 다른 코드에 흔들리지 않고 해당 함수 문제에만 집중합니다.

@Docs - 외부 문서 참조

용도: 프레임워크 공식 문서나 API 문서 같은 외부 문서를 AI가 참고하게 합니다.

이 기능은 2024년 말에 Cursor에 추가되어 아직 모르는 사람이 많습니다.

적합한 상황:

• “Next.js 공식 문서를 참고해서 동적 라우팅을 설정해 줘”
• “이 API 문서를 기준으로 호출 코드를 만들어 줘”
• 새 기술을 배울 때 AI가 문서와 함께 조언하게 할 때

사용 방법: @Docs를 입력한 뒤 문서 URL을 넣거나, Cursor에 내장된 주요 프레임워크 문서를 선택합니다.

한계:

• 일부 주요 프레임워크의 공식 문서만 지원합니다
• 사용자 정의 문서 URL은 가끔 실패합니다(네트워크 문제 또는 형식 미지원)

@Web - 실시간 웹 검색

용도: AI가 인터넷에서 최신 정보를 검색하게 합니다.

예를 들어 막 출시된 라이브러리를 쓰려는데 공식 문서가 아직 AI 학습 데이터에 충분히 반영되지 않았다면 @Web으로 최신 사용법을 검색할 수 있습니다.

적합한 상황:

• “React 19의 최신 기능을 검색해 줘”
• “이 npm 패키지의 최신 버전 사용법을 확인해 줘”
• 최근에 등장한 버그나 오류를 해결할 때

주의: 실시간 검색이 필요하기 때문에 조금 느립니다. 저는 정말 최신 정보가 필요할 때만 사용합니다.

비교표: 6가지 @ 기호는 어떻게 고를까요?

제 사용 경험

솔직히 처음에는 @Files만 썼습니다. 그게 가장 안전하다고 느꼈기 때문입니다. 하지만 나중에는 80%의 경우 @Codebase가 더 효율적이라는 것을 알게 됐습니다. AI가 직접 찾게 하는 편이 제가 파일을 고르는 것보다 빠르고, 제가 놓친 관련 코드도 자주 찾아냅니다.

지금 제 사용 비율은 대략 이렇습니다:

• @Codebase: 60%
• @Files: 30%
• @Code: 5%
• 기타: 5%

이 비율을 그대로 따라 할 필요는 없습니다. 자신에게 맞는 리듬을 찾으면 됩니다. 핵심은 각 @ 기호의 특징을 이해하고, 상황에 맞는 도구를 고르는 것입니다.

.cursorignore 설정 실전

여기까지 왔다면 .cursorignore 이야기를 꼭 해야 합니다. 이 파일은 눈에 잘 띄지 않지만, 인덱싱 속도를 50% 이상 높이고 CPU 사용량을 절반 가까이 줄여 줍니다.

제가 처음 Cursor를 쓸 때는 이 파일을 전혀 설정하지 않았습니다. node_modules가 포함된 프로젝트를 열자 노트북 팬이 거세게 돌고, Cursor는 쓰기 힘들 정도로 버벅였습니다. 나중에 알고 보니 Cursor가 node_modules 안의 3만 개 파일을 열심히 인덱싱하고 있었습니다. 사실 전혀 필요 없는 서드파티 라이브러리 코드였는데 말입니다.

왜 .cursorignore가 필요할까요?

이유는 간단합니다. 모든 파일이 인덱싱할 가치가 있는 것은 아닙니다.

프로젝트 안에는 다음 같은 파일이 있을 수 있습니다:

• 의존성 파일: node_modules, vendor, .venv 등. 파일은 수만 개지만 대부분 볼 필요가 없습니다
• 빌드 산출물: dist, build, .next 등. 컴파일로 생성된 파일이지 소스 코드가 아닙니다
• 임시 파일: .log, .cache, .DS_Store 등. 완전히 무관합니다
• 대형 정적 리소스: 동영상, 이미지, 폰트 파일. 인덱싱해도 도움이 되지 않습니다

이들을 제외하면 인덱싱 시간이 5분에서 30초로 줄고, AI 질의도 더 정확해집니다. 관련 없는 코드에 방해받지 않기 때문입니다.

.cursorignore vs .gitignore

많은 사람이 묻습니다. 이미 .gitignore가 있는데 .cursorignore도 필요할까요?

답은 필요하다입니다. 둘의 논리가 다릅니다.

.gitignore의 목적은 “버전 관리에 커밋하지 않을 파일”을 정하는 것입니다. 하지만 커밋하고 싶지는 않아도 AI가 봐야 하는 파일이 있습니다. 예를 들면:

• 로컬 설정: .env.local은 커밋하고 싶지 않지만, AI가 환경 변수 구성을 이해해야 할 수 있습니다
• 개인 메모: TODO.md는 커밋하지 않지만, AI가 참고할 수 있습니다

반대로 커밋해야 하지만 인덱싱할 필요가 없는 파일도 있습니다:

• package-lock.json: 커밋은 해야 하지만 AI가 의존성 잠금 파일을 읽을 필요는 없습니다
• 테스트 커버리지 리포트: CI에 제출할 수는 있지만 인덱싱할 필요는 없습니다

그래서 .cursorignore는 별도로 설정해야 합니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

범용 설정 템플릿(바로 사용 가능)

아래는 제가 정리한 범용 템플릿이며, 대부분의 프론트엔드 프로젝트에 적합합니다. 프로젝트 루트에 .cursorignore 파일을 만들고 그대로 붙여 넣으면 됩니다:

# 의존성 디렉터리
node_modules/
.pnp/
.pnp.js
vendor/
.venv/

# 빌드 산출물
dist/
build/
.next/
out/
.cache/
.parcel-cache/

# 로그와 임시 파일
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
Thumbs.db

# IDE와 에디터 설정
.idea/
.vscode/
*.swp
*.swo

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

# 정적 리소스(선택, 프로젝트에 맞게 조정)
*.mp4
*.avi
*.mov
*.zip
*.tar.gz

# 대형 JSON 파일(선택)
package-lock.json
yarn.lock
pnpm-lock.yaml

주의: 이것은 기본 템플릿일 뿐입니다. 프로젝트에 맞게 조정해야 합니다. 예를 들어 Python을 쓴다면 __pycache__/와 *.pyc를 추가하세요.

고급 설정 전략

1. 대형 monorepo의 단계별 인덱싱

프로젝트가 monorepo이고 하위 패키지가 수십 개라면 전체 인덱싱은 느릴 수 있습니다. 이런 전략을 사용할 수 있습니다:

# 현재 작업 중인 패키지만 인덱싱
packages/*/node_modules/
packages/package-a/  # 지금은 보지 않는 패키지
packages/package-b/

필요할 때 주석을 제거하면 됩니다.

2. 화이트리스트 모드

프로젝트 파일이 너무 뒤섞여 있다면 제외 항목을 일일이 나열하기보다 “이것만 인덱싱”하도록 지정하는 편이 낫습니다:

# 모두 제외
*

# src 디렉터리만 포함
!src/
!src/**/*

# 설정 파일만 포함
!*.config.js
!tsconfig.json

이 방식은 대형 레거시 프로젝트에서 AI가 핵심 코드에만 집중하게 하고 싶을 때 적합합니다.

3. 파일 크기 기준 필터링

Cursor는 보통 초대형 파일(일반적으로 >1MB)을 자동으로 건너뛰지만, 직접 제외할 수도 있습니다:

# 대형 데이터 파일 제외
*.sql
*.csv
*.json  # 수십 MB짜리 JSON 데이터가 있다면

설정 후 어떻게 검증하나요?

.cursorignore를 수정했다면 실제로 적용됐는지 확인해야 합니다. 방법은 세 가지입니다.

방법 1: 인덱싱 속도 보기

프로젝트를 닫고 다시 열어 오른쪽 아래의 Indexing... 진행 표시를 봅니다. 설정 전에는 3-5분 걸리던 것이 설정 후에는 30초-1분 안에 끝나야 합니다.

방법 2: 인덱싱 파일 수 확인

Cursor 설정에서 Codebase Index를 검색하면 현재 인덱싱된 파일 수가 표시됩니다. 3만 개에서 몇백 개로 줄었다면 설정이 적용된 것입니다.

방법 3: @Codebase 테스트

@Codebase 프로젝트에는 어떤 파일들이 있나요?라고 입력해 AI가 반환하는 파일 목록을 확인합니다. node_modules 안의 파일이 여전히 나타난다면 .cursorignore가 적용되지 않은 것이므로 문법을 확인하세요.

성능 최적화 효과 비교

실제 Next.js 프로젝트에서 측정한 데이터는 다음과 같습니다:

데이터는 분명합니다. .cursorignore 설정은 Cursor를 제대로 쓰기 위한 첫 단계입니다.

자주 발생하는 문제와 해결 방법

Cursor를 1년 넘게 쓰면서 꽤 많은 시행착오를 겪었습니다. 인덱싱 실패, 느린 질의, CPU 사용량 급증 같은 문제는 대부분의 사용자가 한 번쯤 만납니다.

이 장에서는 가장 흔한 네 가지 문제와 해결책을 정리합니다. 문제가 생기면 이 체크리스트 순서대로 확인하면 대부분 해결할 수 있습니다.

문제 1: 인덱싱이 실패하거나 계속 Indexing...에 멈춰 있음

증상:

• 오른쪽 아래에 Indexing...이 계속 표시되고 수십 분이 지나도 끝나지 않습니다
• 또는 Indexing failed가 표시됩니다
• @Codebase가 전혀 반응하지 않습니다

가능한 원인과 해결 방법:

원인 1: 프로젝트 파일이 너무 많아 인덱싱이 시간 초과됨

• 해결: .cursorignore를 설정해 node_modules 같은 무관한 파일을 제외합니다
• 검증: 프로젝트를 닫았다가 다시 열어 인덱싱이 2분 안에 끝나는지 봅니다

원인 2: 지원하지 않는 파일 형식 또는 손상된 파일이 있음

• 해결: 프로젝트에 초대형 파일(>10MB)이나 바이너리 파일이 있는지 확인하고 .cursorignore에 수동으로 추가합니다
• 흔한 사례: 동영상 파일, 대형 SQL dump 파일, 컴파일된 바이너리 파일

원인 3: 디스크 공간 부족

• 해결: 인덱스 데이터는 로컬에 저장되므로 디스크 여유 공간을 확인하세요. 일반적으로 최소 5GB가 필요합니다
• Mac 경로: ~/Library/Application Support/Cursor/
• Windows 경로: %APPDATA%\Cursor\

원인 4: 네트워크 문제(클라우드 동기화를 켠 경우)

• 해결: Privacy Mode를 꺼서 테스트하거나 다른 네트워크 환경에서 시도합니다
• 임시 방법: Settings -> Codebase Index -> Local only mode 켜기

빠른 점검 체크리스트:

☐ .cursorignore가 설정되어 있는지 확인
☐ 프로젝트 파일 수 확인(1000개를 넘으면 최적화 필요)
☐ 디스크 공간이 충분한지 확인(최소 5GB)
☐ Cursor 재시작 시도
☐ 기존 인덱스 캐시 삭제 후 재인덱싱

문제 2: @Codebase 검색 결과가 부정확함

증상:

• 프로젝트 안에 관련 코드가 분명히 있는데 @Codebase가 찾지 못합니다
• 또는 전혀 관련 없는 코드를 반환합니다

가능한 원인과 해결 방법:

원인 1: 인덱스가 불완전하거나 오래됨

• 해결: 수동으로 재인덱싱을 실행합니다
• 방법: Cmd+Shift+P(Mac) / Ctrl+Shift+P(Windows) -> Reindex Codebase 입력 -> Enter

원인 2: 방금 작성한 코드가 아직 인덱싱되지 않음

• 해결: Cursor는 인덱스를 실시간으로 갱신하지만 1-2분 지연이 있을 수 있습니다. 새 코드를 작성한 뒤 잠시 기다렸다가 다시 질의하세요
• 또는 수동으로 인덱스 업데이트를 실행합니다

원인 3: 질문 설명이 너무 모호함

• 해결: 질문을 더 구체적으로 바꿉니다. “버그가 있어”라고 묻지 말고, “사용자 로그인 후 token이 localStorage에 저장되지 않는 이유가 뭐야?”처럼 물어보세요
• 비교:
  • ❌ “성능 최적화”
  • ✅ “리스트 컴포넌트 렌더링이 느린데 반복 렌더링 원인을 찾아줘”

원인 4: 관련 코드가 제외됨

• 해결: .cursorignore를 확인해 핵심 코드가 잘못 제외되지 않았는지 봅니다
• 흔한 실수: 실수로 src 디렉터리 전체를 제외함

정확도를 높이는 팁:

• 구체적인 함수명, 변수명, 파일명을 사용합니다
• 추상적으로 말하지 말고 구체적인 비즈니스 상황을 설명합니다
• @Codebase가 부정확하면 @Files로 파일을 직접 지정해 봅니다

문제 3: Cursor의 CPU/메모리 사용량이 너무 높음

증상:

• 노트북 팬이 계속 강하게 돕니다
• Cursor CPU 사용량이 80%를 넘습니다
• 메모리를 몇 GB씩 사용합니다
• 시스템이 버벅입니다

가능한 원인과 해결 방법:

원인 1: 많은 파일을 인덱싱하는 중

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

• 해결: 정상적인 현상입니다. 인덱싱이 끝날 때까지 기다리면 됩니다
• 계속 높은 사용량이 유지되면 .cursorignore를 설정해 인덱싱 파일 수를 줄입니다

원인 2: 실시간 인덱스 업데이트가 너무 잦음

• 해결: 코드를 자주 수정하면 Cursor가 계속 인덱스를 갱신합니다
• 임시 방법: Settings -> Codebase Index -> Update frequency를 Manual 또는 On save only로 조정합니다

원인 3: 여러 대형 프로젝트를 동시에 열어 둠

• 해결: 각 프로젝트가 리소스를 사용하므로 필요 없는 프로젝트 창을 닫습니다

원인 4: 인덱스 데이터베이스 손상

• 해결: 인덱스 캐시를 삭제하고 다시 인덱싱합니다
• Mac: ~/Library/Application Support/Cursor/Index/ 삭제
• Windows: %APPDATA%\Cursor\Index\ 삭제

성능 최적화 제안:

☐ .cursorignore를 설정해 인덱싱 파일 수 줄이기(목표: 1000개 미만)
☐ 필요 없는 프로젝트 창 닫기
☐ 인덱스 업데이트 빈도를 On save only로 조정
☐ 프로젝트가 특히 크면 @Codebase 대신 @Files 사용 고려
☐ 하드웨어 업그레이드(최소 16GB 메모리, 권장 32GB)

문제 4: @Codebase 응답이 너무 느림

증상:

• 질문을 입력한 뒤 응답까지 5-10초를 기다려야 합니다
• 가끔 바로 시간 초과됩니다

가능한 원인과 해결 방법:

원인 1: 인덱스 데이터베이스가 너무 큼

• 해결: .cursorignore를 설정해 인덱싱 파일 수를 줄입니다
• 이상적인 상태: 인덱싱 파일 수가 500-2000개 사이일 때 질의 속도가 가장 빠릅니다

원인 2: 네트워크가 느림(클라우드 모델 사용 시)

• 해결: 네트워크 연결을 확인하거나 로컬 모드로 전환합니다
• Settings -> Models -> 지연이 더 낮은 모델 선택

원인 3: 질의가 요구하는 코드량이 너무 큼

• 해결: @Codebase는 관련 코드를 모두 포함하려고 하므로 수십 개 파일이 매칭되면 느려집니다
• 최적화: 질문을 더 정확히 쓰거나 @Files로 범위를 지정합니다

원인 4: 컴퓨터 성능 부족

• 해결: 벡터 검색에는 어느 정도 계산 자원이 필요합니다. 컴퓨터 사양이 낮으면 질의가 느릴 수 있습니다
• 권장 사양: 최소 16GB 메모리, SSD

가속 팁:

• @Codebase보다 빠른 @Files 또는 @Folders를 우선 사용합니다
• 오래된 인덱스 캐시를 주기적으로 정리합니다
• 프로젝트를 모듈화하고, 매번 필요한 부분만 로드합니다

제 점검 순서

문제가 생겨도 당황할 필요는 없습니다. 인덱스 문제의 90%는 .cursorignore를 설정하지 않아 너무 많은 불필요한 파일을 인덱싱한 데서 시작합니다.

저는 보통 이런 순서로 점검합니다:

1. 먼저 .cursorignore가 올바르게 설정되어 있는지 확인합니다
2. 수동 재인덱싱을 실행해 해결되는지 봅니다
3. CPU/메모리 사용량을 확인해 성능 문제인지 설정 문제인지 판단합니다
4. 그래도 안 되면 인덱스 캐시를 삭제하고 처음부터 다시 인덱싱합니다

대부분의 문제는 이 순서대로 한 번만 따라가도 해결됩니다. 그래도 안 된다면 Cursor 자체의 버그일 수 있으니 공식 GitHub에 issue를 올리면 됩니다.

실전 사례: Next.js 프로젝트 인덱스를 처음부터 설정하기

이론은 충분히 봤으니 이제 실제로 해 보겠습니다. 실제 Next.js 프로젝트를 예로 들어 .cursorignore 생성부터 효과 검증까지 전체 과정을 한 번 진행합니다.

따라 하면 10분이면 끝납니다.

실전 요약: 설정 전후 비교

실제 Next.js 프로젝트(컴포넌트 라이브러리, API 라우트, 데이터베이스 통합 포함)에서 전체 테스트를 해 봤습니다:

마지막 항목인 “AI 제안 정확도”는 실제 개발 질문 20개로 수동 테스트한 결과입니다. AI가 내놓은 제안이 바로 쓸 수 있는지 비교했습니다. 인덱스를 설정한 뒤 정확도는 60%에서 92%까지 올라갔고, 효과는 매우 뚜렷했습니다.

핵심 포인트

이 실전 예제를 통해 다음을 익혔을 것입니다:

1. ✅ Next.js 프로젝트에 .cursorignore를 만드는 방법
2. ✅ 인덱스 설정이 적용됐는지 확인하는 방법
3. ✅ @ 기호 기능을 테스트하는 방법
4. ✅ 실제 상황에 맞게 설정을 최적화하는 방법

이 흐름은 Next.js에만 적용되는 것이 아닙니다. React, Vue, Angular, 또는 백엔드 프로젝트에서도 생각은 같습니다. 불필요한 파일을 제외하고 AI가 핵심 코드에 집중하게 만드는 것입니다.

결론

이제 거의 마무리할 때입니다.

글의 처음 장면으로 돌아가 보겠습니다. 새벽 한 시, Cursor가 내놓은 다섯 번째 잘못된 제안을 바라보고 있던 그 답답함 말입니다. 많은 분이 비슷한 경험을 해 봤을 것입니다. AI가 아무리 강력해도 프로젝트 전체를 보지 못하면 결국 추측할 수밖에 없습니다.

인덱스 설정은 이 문제를 푸는 핵심입니다.

세 가지 핵심만 기억하면 됩니다:

1. 원리를 이해하는 이유는 뽐내기 위해서가 아니라 함정을 피하기 위해서입니다. 인덱스가 어떻게 작동하는지 알면 왜 node_modules를 제외해야 하는지, 왜 질의가 가끔 느린지, 왜 AI가 코드를 못 찾는지 이해할 수 있습니다.

2. .cursorignore가 최우선입니다. 다른 것은 몰라도 이것은 반드시 설정해야 합니다. 인덱싱 속도 50% 향상, CPU 사용량 절반 감소, AI 정확도 60% 향상은 실제 테스트에서 나온 수치입니다.

3. @ 기호는 외우지 말고 사용 상황을 이해하세요. 80%는 @Codebase로 충분하고, 나머지 20%는 @Files로 정확히 지정하면 됩니다. 너무 고민하지 말고 쓰다 보면 감이 생깁니다.

지금 바로 할 수 있는 세 단계:

1. 지금 프로젝트 루트에 .cursorignore 파일을 만들고, 이 글의 템플릿을 복사해 저장합니다
2. Cursor를 다시 시작하고 인덱싱 속도를 관찰합니다, 설정 전후 차이를 직접 느껴 보세요
3. @Codebase를 테스트합니다, 예전에 AI가 잘 답하지 못했던 질문을 다시 던져 보세요

간단합니다. 10분을 투자하면 앞으로 수백 시간의 효율을 얻을 수 있습니다.

이 글이 도움이 됐다면 아직 Cursor 인덱스와 씨름하는 친구에게 공유해 주세요. 우리 모두 시행착오를 거쳐 여기까지 왔으니까, 하나라도 덜 겪으면 좋습니다.

물론 Cursor의 인덱스 기능은 계속 발전하고 있습니다. 이 글은 2026년 1월 버전을 기준으로 했고, 이후에는 새 기능이나 새 문제가 생길 수 있습니다. 여기서 다루지 않은 상황을 만나면 공식 문서에서 최신 정보를 확인하세요.

이제 읽기만 하지 말고, 바로 설정해 보세요.