Cursor가 코드베이스를 찾는 방식과 .cursorignore로 접근 범위 제한하기

대형 저장소에서 Cursor 에이전트가 엉뚱한 파일을 참고하거나, 생성 파일·빌드 산출물까지 읽어 답변이 흐려지는 경우가 있다. 반대로 비밀값이 든 설정 파일을 에이전트가 읽지 않게 막고 싶을 때도 있다. 두 문제 모두 "Cursor가 무엇을 어떻게 읽는가"를 알아야 다룰 수 있다. 이 글은 Cursor의 코드베이스 검색 문서와 ignore 파일 문서를 기준으로 검색 방식과 .cursorignore 설정을 정리한다.

에이전트가 코드베이스를 찾는 방식

현재 문서는 에이전트의 코드 검색 수단으로 Instant Grep을 설명한다. 함수 이름, 변수, 에러 문자열, 정규식을 정확히 일치시켜 찾는 방식이며 별도 설정 없이 동작한다. 문서는 Cursor가 검색 색인을 만들기 위해 파일 경로나 코드를 업로드하지 않고, 검색용 임베딩도 저장하지 않으며, 색인은 사용자의 컴퓨터에서 만들어지고 조회된다고 밝힌다. 다만 에이전트가 검색 결과 파일을 열면 그 내용은 모델 요청에 포함될 수 있다.

수단	동작	활용 포인트
Instant Grep	정확 일치·정규식 검색, 로컬 색인	고유한 함수명·에러 문자열을 요청에 넣으면 정확도가 올라간다
Explore 서브에이전트	더 빠른 모델로 여러 검색을 병렬 실행하고 요약만 돌려줌	본 대화 컨텍스트를 아끼며 넓은 범위를 조사
@ 멘션	사용자가 파일·폴더를 직접 지정	검색에 맡기지 않고 범위를 확정

검색이 정확 일치 기반이라는 점은 요청 문장에도 영향을 준다. "결제 관련 코드"보다 PaymentService, import.*PaymentService처럼 실제 식별자를 넣으면 에이전트가 관련 파일을 더 빨리 찾는다. 멀티 루트 워크스페이스도 지원되지만, worktree처럼 단일 git 루트에 의존하는 일부 기능은 비활성화된다고 문서에 적혀 있다.

.cursorignore가 막는 범위와 막지 못하는 범위

.cursorignore는 Cursor가 접근할 수 있는 파일과 폴더를 제한한다. 문서에 따르면 무시된 파일은 Agent, Tab, Inline Edit이 접근하는 코드와 @ 멘션 참조에서 제외된다. 그러나 중요한 한계가 있다. 에이전트가 사용하는 터미널과 MCP 서버 도구는 .cursorignore의 적용을 받지 않는다. 에이전트가 cat .env 같은 명령을 실행하면 파일 내용을 읽을 수 있다는 뜻이다.

경로	.cursorignore 적용
Agent의 파일 읽기, Tab, Inline Edit	적용
@ 멘션으로 파일 참조	적용
에이전트가 실행하는 터미널 명령	적용되지 않음
MCP 서버 도구 호출	적용되지 않음

따라서 비밀값 보호는 .cursorignore만으로 끝나지 않는다. 운영 비밀값은 애초에 로컬 저장소에 두지 않고, 터미널 명령 실행 전 승인 설정을 유지하는 것이 함께 필요하다. 사내 도구 보안 전반의 점검 항목은 바이브 코딩 사내 도구 보안 점검 글에 정리했다.

1단계: .cursorignore 작성하기

문법은 .gitignore와 같다. *는 /를 제외한 문자, **는 /를 포함한 모든 문자, ?는 한 글자, !는 부정(다시 포함), #은 주석이다.

# .cursorignore

# 생성 파일과 대용량 데이터
generated/
coverage/
data/fixtures/large/**
*.min.js

# 인증 정보가 들어갈 수 있는 파일
config/credentials/
*.pem

# 문서 폴더는 제외하되 API 문서는 남김
docs/*
!docs/api/

Cursor는 .gitignore에 있는 파일과 기본 목록(잠금 파일, 실행 파일, 미디어 파일, node_modules/, .next/ 같은 빌드 폴더, 점으로 시작하는 환경 파일 등)을 자동으로 무시한다. 그래서 .cursorignore에는 git에는 커밋되지만 AI가 읽을 필요가 없는 파일을 주로 적는다.

2단계: 부정 패턴의 함정 피하기

문서는 부모 디렉터리가 *로 제외되면 그 아래 파일을 !로 다시 포함할 수 없다고 설명한다. 예를 들어 public/*을 제외한 뒤 !public/assets/style.css를 쓰면 동작하지 않는다. 중첩 폴더를 명시적으로 처리해야 한다.

# 동작하지 않는 예
public/*
!public/assets/style.css

# 동작하는 예: 중간 폴더를 다시 포함한 뒤 그 안을 제외하고 필요한 파일만 포함
public/*
!public/assets/
public/assets/*
!public/assets/style.css

3단계: 적용 결과 확인하기

1. 무시한 파일을 @ 멘션으로 참조해 목록에 나타나지 않는지 확인한다.
2. 에이전트에게 무시한 폴더의 내용을 요약해 달라고 요청해 파일 읽기 도구로 접근하지 못하는지 본다.
3. 터미널 명령은 막히지 않으므로, 명령 실행 승인 설정이 켜져 있는지 함께 확인한다.
4. 모든 프로젝트에 공통인 패턴은 사용자 설정의 전역 ignore 목록(기본값은 비어 있음)에 넣는다.

규칙 파일로 에이전트에게 "생성 폴더는 수정하지 않는다"를 함께 적어 두면 검색 범위와 행동 규칙이 맞물린다. 규칙 파일 작성은 Cursor Rules 작성법 글을, 모델 선택은 Cursor Router 글을 참고한다.

대형 저장소에서 검색 품질을 높이는 요청 방식

접근 범위를 줄이는 것과 함께 요청 문장을 검색 친화적으로 쓰면 에이전트가 관련 파일에 더 빨리 도달한다.

약한 요청	검색에 유리한 요청
결제 실패 처리 고쳐 줘	PaymentFailedError를 던지는 곳과 이를 잡는 핸들러를 찾아 재시도 로직을 확인해 줘
로그인 쪽 코드 봐 줘	src/auth 폴더에서 createSession 호출 경로를 정리해 줘
이 에러 왜 나?	에러 문자열 "token expired"가 나오는 위치와 만료 시간 설정을 찾아 줘

넓은 범위를 조사해야 할 때는 Explore 서브에이전트에 맡기면 여러 검색을 병렬로 수행한 뒤 요약만 돌려주므로 본 대화의 컨텍스트가 덜 소모된다. 반대로 수정할 파일이 이미 정해져 있다면 @ 멘션으로 직접 지정하는 것이 가장 확실하다.