Cursor .cursorignore 설정 완벽 가이드: 대규모 프로젝트 인덱싱 최적화 핵심 전략 3가지

2026년 6월 8일 업데이트: 2026년 6월 Cursor 공식 문서를 기준으로 다시 확인했습니다. Cursor는 기본적으로 .gitignore와 내장된 제외 목록을 따르므로 node_modules, 잠금 파일, 빌드 결과물, 바이너리 및 미디어 파일 등은 대부분 자동으로 인덱싱에서 제외됩니다. 따라서 .cursorignore는 주로 ‘접근을 완전히 차단하고 추가 항목을 제외하는’ 용도로 사용합니다. .cursorindexingignore는 인덱싱만 막고 @ 참조를 통한 읽기는 허용합니다. 또한 루트 디렉터리의 단일 .cursorrules 파일은 공식적으로 legacy로 지정되었으며 Agent 모드에서 무시됩니다. 프로젝트 규칙은 .cursor/rules/ 아래의 .mdc 파일을 사용하세요.

지난주 화요일 오후, 회사의 코드가 50만 줄이 넘는 monorepo 프로젝트를 열었습니다. Cursor 오른쪽 아래의 Syncing 아이콘이 빙글빙글 돌기 시작했습니다. 5분이 지나도 계속 돌았고, 10분이 지나도 여전히 인덱싱 중이었습니다. 커피 한 잔을 내려 돌아왔는데도 느긋하게 돌고 있었습니다.

더 답답한 일은 그다음에 벌어졌습니다. 어렵게 인덱싱이 끝난 뒤 AI에게 React 컴포넌트를 최적화해 달라고 했더니 이렇게 제안했습니다. “node_modules/react-dom/cjs/react-dom.development.js 파일을 직접 수정하면 됩니다.” 저는 화면을 보며 3초 동안 말문이 막혔습니다. AI가 의존 패키지의 코드를 제 프로젝트 코드로 착각한 것입니다.

그 순간부터 Cursor가 대규모 프로젝트에 적합하지 않은 건 아닐까 의심했습니다. 그러다 .cursorignore라는 설정 파일을 발견하면서 모든 것이 달라졌습니다. 인덱싱 시간은 12분에서 3분으로 줄었고, AI도 더 이상 node_modules의 코드를 수정하라는 엉뚱한 제안을 하지 않았습니다.

Cursor의 인덱싱이 느리거나 AI가 코드를 잘못 이해하는 문제를 겪었다면, 아래의 즉시 효과를 볼 수 있는 최적화 전략 3가지와 그대로 복사해 쓸 수 있는 설정 템플릿이 문제를 해결하는 데 도움이 될 것입니다.

Cursor 인덱싱이 느린 이유

먼저 Cursor의 인덱싱 방식을 살펴보겠습니다. 프로젝트를 열 때마다 Cursor는 코드 파일을 embedding 벡터로 변환합니다. 쉽게 말하면 코드를 AI가 이해할 수 있는 숫자 표현으로 바꾸는 과정입니다. 모든 파일을 순회하면서 벡터를 계산하고 저장해야 하므로, 프로젝트에 파일이 많을수록 시간이 오래 걸립니다.

여기서 한 가지 질문이 생깁니다. 프로젝트의 모든 파일을 AI가 정말 이해해야 할까요?

대부분의 프로젝트에는 용량이 크고 개수도 많지만 AI 코딩 지원에는 거의 쓸모없는 파일이 몇 종류 있습니다.

node_modules - 의존성의 블랙홀
중간 규모의 프론트엔드 프로젝트도 node_modules 안에 파일이 수만 개 있을 수 있습니다. React 프로젝트에 의존성 수십 개만 설치해도 파일 수는 쉽게 1만 개를 넘습니다. Cursor는 이런 서드파티 코드를 매번 인덱싱하지만, AI가 lodash의 내부 구현까지 이해해야 할 이유가 있을까요?

dist/build - 컴파일 부산물
빌드 도구가 생성한 압축되고 난독화된 코드입니다. 한 줄로 압축된 JavaScript 파일을 AI에게 인덱싱하게 하는 것은 해독할 수 없는 책을 읽으라고 하는 것처럼 의미가 없습니다.

.git - 쌓여 있는 과거 기록
Git 저장소에는 프로젝트의 전체 변경 이력이 들어 있습니다. 대규모 프로젝트라면 .git 폴더가 수백 MB에서 수 GB에 이를 수 있습니다. 이런 과거 데이터를 인덱싱하는 것은 시간 낭비입니다.

대용량 정적 리소스
동영상, 이미지, 글꼴 파일 등은 AI가 읽을 수도 없습니다. 이를 인덱싱하는 것은 불필요한 작업일 뿐입니다.

제가 직접 테스트해 보았습니다. 전체 node_modules와 .next 빌드 디렉터리가 포함된 10만 줄 규모의 Next.js 프로젝트는 인덱싱에 8분이 걸렸습니다. .cursorignore로 해당 디렉터리를 제외하자 2분으로 줄었습니다. 네 배 차이입니다.

더 중요한 것은 정확도입니다. AI 컨텍스트에 node_modules 코드가 가득 차면 어떤 것이 프로젝트 코드이고 어떤 것이 의존 라이브러리인지 혼동하기 쉽습니다. 그 결과 의존 패키지를 수정하라고 제안하거나, 서드파티 라이브러리의 API를 직접 작성한 함수로 착각할 수 있습니다.

.cursorignore 설정 완벽 가이드

다행히 .cursorignore의 문법은 .gitignore와 완전히 같습니다. .gitignore를 작성할 줄 안다면 이 설정 파일도 아주 쉽게 다룰 수 있습니다.

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

요금 보기 →광고

기본 문법 빠르게 살펴보기

프로젝트 루트 디렉터리에 .cursorignore 파일을 만들고(앞의 점을 잊지 마세요) 다음 규칙에 따라 작성합니다.

# 주석은 #으로 시작합니다

# 특정 파일 제외
config.json

# 디렉터리 전체 제외(끝에 슬래시 추가)
node_modules/
dist/

# 와일드카드 매칭
*.log          # 모든 로그 파일
**/*.test.js   # 모든 계층의 테스트 파일

# 부정 규칙(다시 포함)
!important.log # 모든 .log는 제외하되 이 파일은 유지

바로 사용할 수 있는 설정 템플릿

대부분의 프로젝트에 맞는 기본 설정을 정리했습니다. 다음 내용을 .cursorignore 파일에 그대로 복사해서 사용할 수 있습니다.

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

# 빌드 결과물
dist/
build/
out/
.next/
.nuxt/
.cache/
.vite/
.turbo/

# 테스트와 커버리지
coverage/
.nyc_output/
*.spec.js
*.test.js
__tests__/

# 로그와 임시 파일
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
*.swp
*.swo
*~

# 환경 설정(보안 고려)
.env
.env.local
.env.*.local
credentials.json
*.key
*.pem

# 버전 관리
.git/
.svn/
.hg/

# IDE 설정(선택 사항)
.vscode/
.idea/
*.sublime-*

# 대용량 리소스 파일(필요에 따라 조정)
*.mp4
*.mov
*.avi
*.zip
*.tar.gz
*.pdf
public/videos/

이 설정은 일반적인 상황의 90%를 처리할 수 있습니다. 저장한 뒤 Cursor에서 Settings > Features > Codebase Indexing을 열고 새로 고침 버튼을 눌러 설정을 적용하세요.

상황별 고급 설정

프로젝트 유형에 따라 기본 템플릿을 조금씩 조정할 수 있습니다.

React/Vue 프로젝트: public 디렉터리의 대용량 파일 제외

# 기본 설정에 추가
public/assets/
public/images/*.png
public/fonts/

Monorepo 프로젝트: 관련 없는 하위 패키지 제외(매우 중요)

# 프론트엔드 팀이며 apps/web만 사용한다고 가정
apps/mobile/
apps/admin/
packages/backend-utils/

풀스택 프로젝트: 프론트엔드와 백엔드의 인덱스 분리

# 주로 프론트엔드를 개발하는 경우
server/
api/
database/
migrations/

# 또는 주로 백엔드를 개발하는 경우
client/
public/
src/components/

어떤 파일이 제외되었는지 확실하지 않을 때는 터미널에서 다음 명령을 실행하면 됩니다.

git check-ignore -v [파일 경로]

Git 명령이지만 .cursorignore의 문법이 같으므로 설정을 디버깅할 때 사용할 수 있습니다.

.cursorignore vs .cursorindexingignore - 알맞은 도구 선택하기

처음 이 두 설정 파일을 접했을 때 저도 꽤 혼란스러웠습니다. 이름은 비슷한데 무엇이 다르고, 어떤 것을 사용해야 할까요?

간단히 말하면 .cursorignore는 완전 차단이고, .cursorindexingignore는 부분 차단입니다.

본질적인 차이

.cursorignore: AI가 해당 파일에 전혀 접근할 수 없습니다. 인덱싱도, 읽기도, 참조도 하지 않습니다. Cursor의 관점에서는 이런 파일이 존재하지 않는 것과 같습니다. 보안상 민감한 파일(.env, 키 파일)이나 AI가 전혀 다룰 필요가 없는 항목(node_modules, 빌드 결과물)에 사용합니다.

.cursorindexingignore: 파일이 코드베이스 검색 결과에는 나타나지 않지만, 필요할 때는 AI가 여전히 읽을 수 있습니다. 예를 들어 @로 명시적으로 참조하거나 대화에 끌어다 놓은 경우입니다. Cursor가 성능 최적화를 위해 나중에 추가한 기능입니다.

예를 들어 오래된 프로젝트에 3년 전 레거시 코드가 들어 있는 legacy/ 디렉터리가 있다고 해봅시다. 검색 결과를 오염시키고 싶지는 않지만, 가끔 AI가 기존 구현 로직을 참고해야 할 수 있습니다. 이럴 때 .cursorindexingignore가 적합합니다.

사용 상황 비교표

설정 우선순위

Cursor는 다음 순서로 설정을 처리합니다.

1. 먼저 프로젝트의 .gitignore 읽기(자동으로 준수)
2. 이어서 .cursorignore 읽기(! 문법으로 gitignore 규칙을 덮어쓸 수 있음)
3. 마지막으로 .cursorindexingignore 적용

이것이 무엇을 의미할까요? .gitignore에서 logs/ 디렉터리를 제외했지만 AI가 특정 로그 파일에는 접근할 수 있게 하려면 .cursorignore에 다음과 같이 작성할 수 있습니다.

!logs/important-debug.log

또한 “Hierarchical Cursor Ignore”라는 유용한 기능이 있습니다. 이 기능을 켜면(Settings에서 찾을 수 있습니다) Cursor가 상위 디렉터리의 .cursorignore 파일을 재귀적으로 탐색합니다. 대규모 monorepo의 루트 디렉터리에 전역 설정을 두고, 하위 프로젝트에서 별도 설정을 추가할 때 유용합니다.

제가 사용하는 방식

솔직히 대부분의 경우에는 .cursorignore만으로도 충분합니다. .cursorindexingignore는 성능 요구가 매우 높거나 프로젝트 구조가 특히 복잡한 상황에 적합한 세밀한 최적화 도구에 가깝습니다.

처음 설정할 때는 다음 순서로 진행하는 것이 좋습니다.

• 1단계: .cursorignore만 사용해 명백히 필요 없는 항목을 제외합니다.
• 2단계: 일주일 동안 AI가 어떻게 동작하는지 관찰합니다.
• 3단계: 문제가 남아 있다면 .cursorindexingignore로 세밀하게 조정합니다.

처음부터 지나치게 복잡하게 만들 필요는 없습니다. 단계적으로 적용하는 편이 더 효과적입니다.

Monorepo 프로젝트를 위한 최적화 전략 3가지

Monorepo는 Cursor가 가장 쉽게 ‘감당하기 어려워지는’ 프로젝트 유형입니다. 하나의 저장소 안에 프론트엔드, 백엔드, 모바일, 관리자 백오피스 등이 모두 들어 있을 수 있어 AI가 수많은 코드를 마주하면 잘못 이해하기 쉽습니다.

저도 하위 앱 12개가 포함된 monorepo 프로젝트에서 문제를 겪었습니다. 당시 AI에게 프론트엔드 컴포넌트를 최적화해 달라고 하자 백엔드 API 디렉터리의 유틸리티 함수를 참조하라고 제안했습니다. 그럴듯하게 들렸지만 프론트엔드에서는 백엔드 코드에 접근할 수 없었고, 두 패키지는 아예 서로 다른 런타임 환경에서 동작했습니다.

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

시작하기 →광고

그 후 특히 유용한 최적화 전략 3가지를 정리했습니다.

전략 1: 작업 영역별로 인덱스 분할

가장 간단하고 직접적인 방법은 신경 쓸 필요가 없는 하위 프로젝트를 제외하는 것입니다.

프론트엔드 팀에 속해 주로 apps/web 디렉터리에서 작업한다면, 다른 하위 앱을 모두 제외합니다.

# .cursorignore
apps/mobile/
apps/admin/
apps/api/
packages/backend-utils/
packages/database/
services/

이 방법에는 두 가지 장점이 있습니다. 인덱싱 속도가 빨라지고, AI가 다른 하위 프로젝트의 코드에 방해받지 않습니다. 제가 한 monorepo에서 담당하는 패키지 두 개만 남겨 보니 인덱싱 시간이 15분에서 4분으로 줄었습니다.

풀스택 개발자로서 프론트엔드와 백엔드를 자주 오간다면 .cursorignore.frontend와 .cursorignore.backend 두 설정 파일을 준비한 뒤, 현재 작업에 맞는 설정을 .cursorignore로 복사할 수 있습니다.

전략 2: Project Rules로 AI의 프로젝트 구조 이해 돕기

Monorepo의 가장 큰 문제는 AI가 디렉터리 간 관계를 파악하지 못한다는 점입니다. 이럴 때 Project Rules로 AI에게 프로젝트 지도를 제공할 수 있습니다. 주의할 점은 기존 루트 디렉터리의 단일 .cursorrules 파일이 공식적으로 legacy로 지정되었고 Agent 모드에서 무시된다는 것입니다. 새 프로젝트에서는 .cursor/rules/ 디렉터리 아래의 .mdc 파일을 사용해야 합니다. 이 파일은 .cursorignore가 아닙니다.

.cursor/rules/ 아래에 규칙 파일(예: project-structure.mdc)을 새로 만들고, 파일 시작 부분의 YAML frontmatter에서 활성화 방식(description, globs, alwaysApply)을 제어한 뒤 본문에 프로젝트 지도를 작성합니다.

---
description: monorepo 프로젝트 구조 및 코드 참조 규칙
alwaysApply: true
---

# 프로젝트 구조 설명

이 프로젝트는 다음 하위 앱을 포함하는 monorepo입니다.

- apps/web: 프론트엔드 앱(Next.js), 포트 3000
- apps/api: 백엔드 API(Node.js + Express), 포트 8000
- apps/admin: 관리자 백오피스(React), 포트 3001
- packages/ui: 공유 UI 컴포넌트 라이브러리
- packages/utils: 공통 유틸리티 함수

## 코드 참조 규칙

- 프론트엔드 앱(web/admin)은 packages/ui와 packages/utils만 참조할 수 있음
- 프론트엔드에서 apps/api 코드를 직접 참조할 수 없음
- 공유 패키지(packages/*)는 특정 앱(apps/*)에 의존할 수 없음

## 현재 작업의 초점

현재 apps/web을 주로 개발하고 있으므로 최적화 제안은 프론트엔드 코드에 집중하세요.

AI는 이러한 규칙을 읽고 프로젝트 구조를 이해할 수 있습니다. 효과는 분명했습니다. 설정 후 AI가 경계를 넘는 코드 참조를 제안하는 일이 거의 사라졌습니다.

전략 3: 창을 나눠 작업하기

하위 앱이 20개가 넘는 초대형 monorepo라면 .cursorignore를 설정해도 단일 창의 컨텍스트가 여전히 너무 큽니다.

이럴 때 저는 하위 앱마다 별도의 Cursor 창을 엽니다.

• 창 1: apps/web 디렉터리 열기
• 창 2: apps/api 디렉터리 열기
• 창 3: packages/ui 디렉터리 열기

각 창은 독립적인 인덱스와 컨텍스트를 가지므로 AI가 코드를 더 정확하게 이해합니다. 창 사이를 전환해야 하는 단점은 있지만, 대규모 프로젝트에서는 그 불편보다 정확도 향상으로 얻는 이점이 더 큽니다.

하위 앱 사이에 의존 관계가 있다면(예: web이 ui 컴포넌트 라이브러리에 의존) web 창에서 @folder로 명시적으로 참조할 수 있습니다.

@folder packages/ui Button 컴포넌트의 props 정의를 확인해 주세요

이렇게 하면 창을 가볍게 유지하면서도 필요할 때 의존 패키지의 코드에 접근할 수 있습니다.

Monorepo 최적화의 핵심

요약하면 Monorepo 최적화의 핵심은 AI가 꼭 봐야 하는 것만 보게 하는 것입니다.

프로젝트가 클수록 덜어내야 합니다. AI가 사람처럼 전체 프로젝트의 아키텍처를 이해하리라 기대하지 마세요. 먼저 경계를 명확하게 정해 주어야 더 정확한 제안을 받을 수 있습니다.

설정 검증과 유지 관리

.cursorignore 설정은 한 번으로 끝나는 작업이 아닙니다. 설정이 적용되었는지 검증하고 정기적으로 관리해야 합니다.

설정 적용 여부 확인하기

가장 직관적인 방법은 인덱싱 시간을 확인하는 것입니다. 설정 전후의 Syncing 시간을 비교해 눈에 띄게 빨라졌다면 설정이 제대로 작동한 것입니다.

더 정확한 검증 방법은 다음과 같습니다.

1. 인덱싱 상태 확인
   Settings > Features > Codebase Indexing을 열면 인덱싱된 파일 수를 확인할 수 있습니다. .cursorignore를 설정한 뒤에는 이 수가 눈에 띄게 줄어야 합니다.

2. AI의 컨텍스트 범위 테스트
   @codebase로 AI에게 질문하고 답변에서 제외된 파일을 여전히 참조하는지 확인합니다. 예를 들어 node_modules를 제외한 뒤 “프로젝트에 어떤 React 컴포넌트가 있나요?”라고 물었을 때 AI가 node_modules/react 아래의 컴포넌트를 나열해서는 안 됩니다.

3. 검색 기능으로 확인
   Cursor의 코드 검색(Cmd/Ctrl + P)에서 제외된 디렉터리 안의 파일명을 검색합니다. 검색되지 않으면 설정이 적용된 것입니다.

인덱스를 수동으로 새로 고쳐야 하는 경우

Cursor는 파일 변경을 자동으로 감지하고 인덱스를 증분 업데이트하지만, 다음 상황에서는 수동으로 새로 고쳐야 합니다.

• .cursorignore 설정 파일을 수정했을 때
• 변경 폭이 큰 Git 브랜치로 전환했을 때
• 많은 파일을 한꺼번에 삭제하거나 추가했을 때
• AI가 코드를 정확하게 이해하지 못해 인덱스가 오래되었다고 느껴질 때

새로 고치는 방법은 Settings > Features > Codebase Indexing > Refresh입니다. 한 번 누르면 전체 프로젝트를 다시 인덱싱하므로 Syncing이 끝날 때까지 기다리면 됩니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

설정의 일상적인 유지 관리

.cursorignore는 한 번 작성하고 끝낼 파일이 아닙니다. 프로젝트가 발전하면서 다음과 같은 조정이 필요할 수 있습니다.

월간 점검 목록:

• 새로 생긴 빌드 디렉터리를 제외했는지 확인(예: 프레임워크 업그레이드 후 생긴 .output/ 디렉터리)
• 제외해야 할 새로운 대용량 파일 디렉터리가 있는지 확인
• 기존에 제외한 디렉터리가 여전히 존재하는지 확인(무효한 설정 정리)

팀 협업 권장 사항:

팀 프로젝트라면 .cursorignore를 Git에 커밋해야 할까요? 상황에 따라 나누는 것이 좋습니다.

• 공통 제외 규칙(node_modules, dist 등): Git에 커밋해 팀 전체가 혜택을 받도록 합니다.
• 개인 작업 선호도(특정 하위 프로젝트 제외): 커밋하지 않거나 .git/info/exclude에 추가합니다.

.gitignore에 다음 한 줄을 추가하는 방법도 있습니다.

.cursorignore.local

그런 다음 개인 설정은 .cursorignore.local에 작성하고, Cursor가 include 문법을 지원한다면 .cursorignore에서 해당 파일을 참조합니다.

주석으로 제외 이유 기록하기

매우 유용한 습관입니다. .cursorignore에 주석을 추가해 특정 디렉터리를 제외하는 이유를 설명하세요.

# 2025-01-15: 새 AI 학습 데이터 디렉터리 제외, 파일이 너무 크고 인덱싱할 필요가 없음
data/training/

# 2025-01-10: 대량의 로그 파일이 포함된 성능 테스트 디렉터리 임시 제외
perf-tests/

석 달 뒤 설정을 다시 볼 때, 주석을 남겨 둔 자신에게 고마워질 것입니다.

더 읽어보기

• Cursor 코드베이스 인덱싱 완벽 가이드: 원리, 설정, @ 기호 사용법
• Cursor 대규모 프로젝트 실전: Agent가 큰 코드베이스에서 길을 잃지 않게 하는 법
• Cursor 무료 할당량 완벽 가이드

마무리

글의 처음으로 돌아가 보겠습니다. Cursor 인덱싱이 느리고 AI가 코드를 잘못 이해하는 것이 정말 도구의 문제일까요?

그렇지 않습니다. 대부분은 AI가 무엇에 집중하고 무엇을 무시해야 하는지 알려 주지 않았기 때문입니다.

.cursorignore는 단순하지만 강력한 도구입니다. 5분만 투자해 설정하면 앞으로 몇 달 동안 개발 과정에서 기다리는 시간을 몇 시간이나 절약할 수 있습니다. 더 중요한 것은 AI가 더 정확한 제안을 하게 된다는 점입니다.

3단계 실행 목록:

1. 바로 실행: 이 글의 기본 설정 템플릿을 복사해 프로젝트 루트 디렉터리에 .cursorignore 파일을 만듭니다.
2. 맞춤형 최적화: 프로젝트 유형(React/Vue/Monorepo)에 따라 필요한 제외 규칙을 추가합니다.
3. 지속적인 개선: 일주일 동안 AI의 동작을 관찰하고 문제를 기록해 설정을 반복적으로 개선합니다.

한 번에 완벽하게 설정하려고 할 필요는 없습니다. 기본 템플릿으로 먼저 문제의 80%를 해결하고, 나머지 20%는 실제로 사용하면서 천천히 조정하세요.

대규모 프로젝트에서 Cursor를 사용하고 있다면 이 전략들을 시도해 보세요. 댓글로 설정 경험이나 겪고 있는 문제를 공유해 주셔도 좋습니다. 같은 어려움을 겪는 다른 개발자에게 도움이 될 수 있습니다.