개요

Cursor는 프로젝트 코드베이스를 읽고 인덱싱해서 기능을 제공해. 루트 디렉토리의 .cursorignore 파일로 Cursor가 접근할 수 있는 디렉토리와 파일을 제어해. Cursor는 .cursorignore에 나열된 파일에 대한 접근을 다음에서 막아:
Agent가 실행하는 도구 호출(예: 터미널, MCP 서버)은 .cursorignore로 제어되는 코드에 대한 접근을 막을 수 없어

왜 파일을 무시할까?

보안: API 키, 크리덴셜, 시크릿 같은 민감 정보에 대한 접근을 제한해. Cursor가 무시된 파일은 차단하지만, LLM 특성상 완전한 보호를 100% 보장하긴 어려워. 성능: 대규모 코드베이스나 모노레포에선 인덱싱을 더 빠르게 하고 파일 검색 정확도를 높이려고, 관련 없는 부분은 제외하는 게 좋아.

전역 ignore 파일

프로젝트마다 설정하지 않아도 되도록, 사용자 설정에서 모든 프로젝트에 적용될 ignore 패턴을 설정해. 민감한 파일을 제외할 수 있어.
Global Cursor Ignore List
기본 패턴은 다음을 포함해:
  • 환경 파일: **/.env, **/.env.*
  • 자격 증명: **/credentials.json, **/secrets.json
  • 키: **/*.key, **/*.pem, **/id_rsa

.cursorignore 구성

루트 디렉터리에 .gitignore 문법으로 .cursorignore 파일을 만들어.

패턴 예제

config.json      # 특정 파일
dist/           # 디렉터리
*.log           # 파일 확장자
**/logs         # 중첩 디렉터리
!app/           # 무시 목록에서 제외(부정)

계층적 무시

부모 디렉터리에서 .cursorignore 파일을 찾으려면 Cursor Settings > Features > Editor > Hierarchical Cursor Ignore를 켜. 참고: 주석은 #로 시작해. 나중에 나온 패턴이 이전 패턴을 덮어써. 패턴은 파일 위치를 기준으로 해.

.cursorindexingignore로 인덱싱 제한하기

.cursorindexingignore를 사용해 인덱싱에서만 파일을 제외해. 이 파일들은 AI 기능에선 계속 접근할 수 있지만, 코드베이스 검색에는 표시되지 않아.

기본적으로 무시되는 파일

Cursor는 .gitignore와 아래 기본 무시 목록에 있는 파일을 자동으로 무시해. .cursorignore에서 ! 접두사를 붙여서 예외 처리할 수 있어.
인덱싱에 한해, 네 .gitignore, .cursorignore, .cursorindexingignore에 있는 항목 외에도 다음 파일들이 추가로 무시돼:
package-lock.json
pnpm-lock.yaml
yarn.lock
composer.lock
Gemfile.lock
bun.lockb
.env*
.git/
.svn/
.hg/
*.lock
*.bak
*.tmp
*.bin
*.exe
*.dll
*.so
*.lockb
*.qwoff
*.isl
*.csv
*.pdf
*.doc
*.doc
*.xls
*.xlsx
*.ppt
*.pptx
*.odt
*.ods
*.odp
*.odg
*.odf
*.sxw
*.sxc
*.sxi
*.sxd
*.sdc
*.jpg
*.jpeg
*.png
*.gif
*.bmp
*.tif
*.mp3
*.wav
*.wma
*.ogg
*.flac
*.aac
*.mp4
*.mov
*.wmv
*.flv
*.avi
*.zip
*.tar
*.gz
*.7z
*.rar
*.tgz
*.dmg
*.iso
*.cue
*.mdf
*.mds
*.vcd
*.toast
*.img
*.apk
*.msi
*.cab
*.tar.gz
*.tar.xz
*.tar.bz2
*.tar.lzma
*.tar.Z
*.tar.sz
*.lzma
*.ttf
*.otf
*.pak
*.woff
*.woff2
*.eot
*.webp
*.vsix
*.rmeta
*.rlib
*.parquet
*.svg
.egg-info/
.venv/
node_modules/
__pycache__/
.next/
.nuxt/
.cache/
.sass-cache/
.gradle/
.DS_Store/
.ipynb_checkpoints/
.pytest_cache/
.mypy_cache/
.tox/
.git/
.hg/
.svn/
.bzr/
.lock-wscript/
.Python/
.jupyter/
.history/
.yarn/
.yarn-cache/
.eslintcache/
.parcel-cache/
.cache-loader/
.nyc_output/
.node_repl_history/
.pnp.js/
.pnp/

부정 패턴의 한계

부정 패턴(!로 시작)을 쓸 때, 상위 디렉터리가 *로 제외되어 있으면 해당 파일을 다시 포함할 수 없어.
# public 폴더의 모든 파일 무시
public/*

# ✅ 이건 잘 작동함 — 파일이 최상위에 있기 때문
!public/index.html

# ❌ 이건 작동하지 않음 — 중첩 디렉터리의 파일은 다시 포함할 수 없음
!public/assets/style.css
우회 방법: 중첩 디렉터리를 명시적으로 제외하기:
public/assets/*
!public/assets/style.css # 이제 이 파일에 접근할 수 있어
성능을 위해 제외된 디렉터리는 순회하지 않으니까, 그 안의 파일에 대한 패턴은 적용되지 않아. 이건 중첩 디렉터리에서의 부정 패턴 처리 방식이 .gitignore 구현과 같아. 더 자세한 내용은 gitignore 패턴에 대한 공식 Git 문서를 참고해.

문제 해결

git check-ignore -v [file]로 패턴을 테스트해봐.