.cursorignore로 인덱스를 어떻게 줄이나

**.cursorignore**는 프로젝트 루트에 두는 무시 목록입니다. .gitignore와 같은 패턴 문법을 쓰며, Cursor가 Agent·Tab·Inline Edit·@ 멘션으로 그 경로에 접근하지 못하게 막습니다. 모노레포·생성물이 많은 저장소에서는 불필요한 경로를 빼 두면 인덱스가 얇아지고, 시크릿이 컨텍스트에 섞일 여지도 줄어듭니다.

이 글은 무시 패턴·빌드 산출물·에이전트가 못 읽을 때 증상만 다룹니다. 요금제·플랜 비교·개인 사용 후기는 넣지 않습니다. 내용은 Cursor Ignore file과 Ignore files 도움말을 기준으로 합니다.

gitignore와 차이는?

한 줄 답: .gitignore는 Git이 추적할지를, .cursorignore는 Cursor AI가 접근할지를 나눕니다. Cursor는 .gitignore와 기본 무시 목록을 이미 따르므로, .cursorignore는 그 위에 추가로 빼고 싶은 경로에 씁니다.

파일	주 목적	Cursor와의 관계
`.gitignore`	커밋·푸시 대상에서 제외	Cursor가 자동으로 존중 → Git이 무시하는 파일은 AI 컨텍스트에서도 빠짐
`.cursorignore`	Agent / Tab / Inline / `@` 접근 차단	Git에는 두고 AI만 막을 때, 또는 `.gitignore`에 없는 추가 제외
기본 무시 목록	Cursor 내장	`node_modules/`, `.next/`, `.env*`, lockfile, 바이너리·미디어 등 (문서 목록 참고)

실무에서 .cursorignore가 필요한 경우:

Git에는 있어야 하는데 AI에는 넣기 싫은 파일 — 예: 추적 중인 대용량 fixture, 내부 스펙 덤프, 샘플 데이터셋.
시크릿·자격 증명 — .env*, credentials.json, *.pem 등은 기본 목록·전역 ignore와 겹치더라도, 팀 합의용으로 명시해 두는 편이 안전합니다. 문서도 보안·성능 둘 다 이유로 ignore를 권합니다.
부모 디렉터리 규칙 — Cursor Settings → Indexing → Ignore Files → Hierarchical Cursor Ignore를 켜면 상위 폴더의 .cursorignore까지 검색합니다.
전역 ignore — 사용자 설정에 프로젝트 공통 패턴을 넣을 수 있습니다. 기본값은 비어 있습니다. 문서 예: **/.env, **/.env.*, **/credentials.json, **/*.pem 등.

패턴 문법은 .gitignore와 동일합니다 (*, **, ?, ! 부정, # 주석). 부모 디렉터리를 *로 통째로 막은 뒤 하위만 !로 되돌리는 방식은 중첩 경로에서 실패할 수 있습니다. 제외된 디렉터리는 성능상 순회하지 않으므로, 문서에 나온 대로 한 단계씩 명시적으로 제외·재포함해야 합니다. 패턴 검증은 git check-ignore -v [file]로 시험할 수 있습니다.

중요 한계: Agent가 쓰는 터미널·MCP 도구는 .cursorignore의 파일 접근 통제 밖입니다. ignore에 넣어도 셸·MCP로는 읽을 수 있습니다. “완전 차단”을 보장하지는 않는다고 문서가 명시합니다.

빌드 산출물은?

한 줄 답: dist/, build/, .next/, 캐시·생성 코드처럼 재현 가능하고 컨텍스트 가치가 낮은 산출물을 먼저 빼십시오. 많은 항목은 이미 기본 무시 목록에 있으므로, 팀에 특화된 산출물 경로만 .cursorignore(또는 필요하면 .gitignore)에 보강합니다.

우선순위 예:

# 앱/프레임워크 산출물 (프로젝트에 맞게)
dist/
build/
out/
.turbo/
coverage/

# 언어·툴체인 캐시
__pycache__/
*.egg-info/
.gradle/
target/          # 예: Java/Rust 빌드 출력 (레포 관례에 맞게)

# 대용량·노이즈
*.min.js
**/generated/
**/fixtures/large/

정리 포인트:

이미 기본 무시되는 것 — node_modules/, .next/, .nuxt/, .cache/, .venv/, lockfile, 이미지·압축·바이너리 확장자 등은 문서의 Default ignore list에 있습니다. 같은 줄을 다시 적어도 해롭지는 않지만, 의도 문서화 용도로만 두면 됩니다.
Git에는 커밋하는 생성물 — 예: 체크인한 dist/나 벤더 스냅샷. 인덱스를 줄이려면 .cursorignore에만 넣고 Git 추적은 유지합니다.
시크릿과 산출물을 섞지 말 것 — 빌드 출력을 막으면서 .env.example처럼 형태만 알려야 하는 파일은 !로 재포함하되, 부모 디렉터리 전체를 *로 막지 않았는지 확인합니다.
모노레포 — 패키지별 packages/*/dist/처럼 관련 없는 패키지 산출물을 넓게 막고, 지금 손대는 패키지 소스만 남기는 식으로 인덱스를 좁힙니다.

도움말의 “왜 ignore 하나”도 같은 방향입니다. 큰 생성물·바이너리·서드파티 트리는 인덱스와 컨텍스트를 느리게 만들고 노이즈만 늘립니다.

에이전트가 못 읽는 증상은?

한 줄 답: ignore된 경로는 에디터 쪽 AI 도구(파일 읽기·@·Tab/Inline 컨텍스트) 에서 빠집니다. “파일을 못 찾는다”, “내용이 비어 있다”, “해당 경로를 열 수 없다” 식으로 답하거나, 그 파일을 전제로 한 수정이 어긋나면 ignore 여부를 먼저 의심합니다.

관찰 체크리스트:

@ 멘션·코드베이스 참조 — ignore된 파일은 @로 끌어오기 어렵거나 컨텍스트에 안 잡힙니다. 문서상 .cursorignore는 @ 멘션 접근도 막습니다.
Agent / Tab / Inline Edit — 동일하게 해당 코드에 대한 접근이 차단됩니다. 에이전트가 “권한이 없다”, “읽을 수 없다”, 또는 추측으로 코드를 지어내는 패턴이 보이면 경로가 ignore인지 확인합니다.
터미널·MCP는 예외 — Agent가 cat/rg 같은 셸이나 MCP로 같은 파일을 읽어 오는 경우는 ignore와 모순이 아닙니다. 문서가 이 우회를 명시합니다. 시크릿을 막으려면 ignore만으로 충분하지 않고, 환경·권한·시크릿 관리를 따로 둡니다.
과잉 ignore — 소스 src/나 설정 스키마까지 막아 두면, 에이전트가 구현을 못 읽고 동떨어진 패치를 제안합니다. 증상은 “못 읽음”과 “엉뚱한 수정”이 같이 옵니다. 필요한 소스·예제(.env.example 등)는 남겨 두십시오.
패턴 디버그 — git check-ignore -v path/to/file로 어떤 규칙에 걸렸는지 확인합니다. Hierarchical ignore를 켠 경우 상위 폴더 .cursorignore 도 함께 봅니다.

원인 분리 순서: (1) 경로가 .gitignore / 기본 목록 / .cursorignore / 전역 ignore 중 어디에 있는지 → (2) 부정(!) 패턴이 부모 제외와 충돌하지 않는지 → (3) 터미널로만 읽히는지(파일 도구 차단 vs 실제 부재).

마무리

인덱스를 줄이려면 .gitignore+기본 목록으로 이미 빠진 것을 알고, Git에는 두되 AI에서만 뺄 경로와 팀 전용 빌드·대용량 산출물을 .cursorignore에 명시하면 됩니다. 에이전트가 특정 파일을 못 읽으면 먼저 ignore를 의심하고, 터미널·MCP 우회와 과잉 차단을 구분하십시오. 보안은 ignore만으로 끝나지 않습니다.

.cursorignore로 인덱스를 어떻게 줄이나

gitignore와 차이는?

빌드 산출물은?

에이전트가 못 읽는 증상은?

마무리

출처