API 키가 담긴 .env 파일을 열어둔 채 작업하다가 문득 이런 생각이 들 때가 있습니다. "이 파일도 AI가 읽고 있나?" 대부분은 ".gitignore에 넣어놨으니 괜찮겠지"라고 넘어갑니다. 하지만 git이 무시하는 것과 AI 에디터가 무시하는 것은 같은 규칙이 아니고, 무엇보다 차단 설정을 해도 뚫리는 경로가 따로 있습니다. 이 글은 Cursor AI 개발 환경에서 내 코드가 AI에게 전달되는 경로를 나눠 보고, 무엇을 설정하면 막을 수 있는지, 설정해도 막히지 않는 지점은 어디인지를 공식 문서 기준으로 정리합니다. (본 글은 작성 시점인 2026년 8월 기준이며, 세부 설정 위치는 버전에 따라 달라질 수 있습니다.)
Cursor가 내 코드를 보는 경로는 하나가 아니다
"AI가 코드를 본다"를 한 덩어리로 생각하면 대책도 뭉뚱그려집니다. 실제로는 성격이 다른 세 가지 경로가 있습니다.
- 인덱싱(검색용 색인) — 프로젝트 파일을 임베딩으로 변환해 "이 기능 어디에 있지?" 같은 검색에 쓰는 색인을 만듭니다. Cursor의 공식 데이터 사용 안내에 따르면 이 과정에서 서버에 남는 것은 임베딩과 난독화된 경로·행 번호 같은 메타데이터이고, 원본 소스 코드 자체가 영구 저장되는 구조는 아닙니다.
- 직접 참조 —
@파일명으로 첨부하거나, 열려 있는 파일이 컨텍스트로 들어가는 경우입니다. 인덱싱과 무관하게 내용이 그대로 전달됩니다. - 에이전트의 도구 실행 — 에이전트가 터미널 명령을 돌리거나 MCP 서버 도구를 호출해 파일을 읽는 경로입니다. 뒤에서 다루겠지만, 여기가 가장 놓치기 쉬운 구멍입니다.
세 경로를 구분해야 하는 이유는 간단합니다. 설정 파일마다 막는 경로가 다르기 때문입니다. 색인에서 뺐다고 접근이 막힌 것도 아니고, 접근을 막았다고 모든 실행 경로가 닫힌 것도 아닙니다.
.cursorignore와 .cursorindexingignore, 이름은 비슷한데 역할이 다르다
Cursor는 이름이 헷갈리는 두 개의 무시 파일을 제공합니다. 반대로 알고 쓰는 경우가 꽤 많습니다.
| 구분 | .cursorignore | .cursorindexingignore |
|---|---|---|
| 검색 인덱싱 | 제외 | 제외 |
| @로 직접 첨부 | 차단 시도 | 여전히 가능 |
| 주 용도 | 비밀키·자격증명 등 접근 자체를 막고 싶은 파일 | 덩치만 크고 검색 가치가 낮은 파일(빌드 산출물, 대용량 로그) |
정리하면 .cursorindexingignore는 보안 장치가 아니라 색인 다이어트 도구입니다. 모노레포가 너무 커서 검색 결과가 지저분해질 때 쓰는 것이지, 비밀을 숨기는 용도가 아닙니다. 반대로 접근 자체를 막고 싶다면 .cursorignore를 써야 합니다.
.gitignore는 어떨까요. Cursor는 .gitignore 패턴을 자동으로 존중해 해당 파일들을 인덱싱에서 빼줍니다. 그래서 "이미 gitignore에 있으니 끝"이라고 느끼기 쉽습니다. 다만 git 추적 여부와 AI 접근 통제는 원래 목적이 다른 규칙입니다. 예를 들어 저장소에 커밋해야 하는 설정 파일인데 AI에게는 보이고 싶지 않은 경우, .gitignore로는 표현할 수 없습니다. 두 목적이 갈리는 지점에서 .cursorignore가 필요해집니다.
중요한 단서: .cursorignore는 "보장"이 아니라 "최선의 노력"
여기가 이 글에서 가장 중요한 부분입니다. Cursor 공식 Ignore File 문서는 .cursorignore가 best-effort(최선의 노력)임을 명시합니다. 즉 목록에 넣은 파일이 절대 전송되지 않는다고 보장하지 않으며, 버그로 인해 전송될 가능성이 남아 있다는 뜻입니다.
더 명확한 한계도 문서화되어 있습니다. 에이전트가 사용하는 터미널과 MCP 서버 도구는 .cursorignore의 통제를 받지 않습니다. 에디터의 파일 접근 제어 바깥에서 도는 실행 경로이기 때문입니다.
어떤 상황인지 그려보면 이해가 빠릅니다. .env를 무시 목록에 넣어두고 에이전트에게 "서버가 왜 안 뜨는지 확인해줘"라고 시킵니다. 에이전트는 원인을 찾으려고 환경변수나 설정을 출력하는 명령을 실행하고, 그 출력에 키가 섞여 나옵니다. 무시 파일 규칙을 위반한 것은 없지만, 값은 이미 대화에 남았습니다. 파일 접근을 막는 층과 명령 실행 결과가 흐르는 층이 서로 다르기 때문입니다.
그래서 결론은 이렇습니다. 무시 파일은 실수를 줄이는 장치이지, 비밀을 지키는 최후의 방어선이 아닙니다. 진짜 민감한 값은 애초에 저장소 안에 평문으로 두지 않는 쪽이 근본적인 해법입니다. 비밀 관리 도구나 OS 키체인에 두고 코드에는 참조만 남기면, 무시 파일이 뚫리든 말든 새어 나갈 원본 자체가 없습니다.
Cursor AI 개발에서 민감 파일 정리하는 4단계
1단계 — 숨길 대상 목록부터 만든다
보통 네 부류로 나뉩니다. ① .env 계열 환경변수 파일 ② 인증서·개인키·서비스 계정 JSON ③ 고객 데이터가 들어간 샘플이나 덤프 파일 ④ 계약서·내부 기획 문서처럼 코드가 아닌 첨부물. 이 중 ①과 ②는 무시 파일에 적기 전에 비밀 관리 도구로 옮기는 것이 먼저이고, 무시 파일은 그 위에 덧대는 2차 방어선으로 생각하는 편이 맞습니다.
2단계 — .cursorignore를 프로젝트 루트에 만든다
문법은 .gitignore와 동일해서 새로 배울 것이 없습니다. 다만 한 가지 함정이 있습니다. 제외된 디렉터리는 아예 순회하지 않기 때문에, 그 안의 특정 파일만 다시 포함시키는 패턴은 동작하지 않습니다. 폴더째 제외해놓고 예외 규칙으로 일부를 되살리려는 시도가 먹히지 않는 이유가 이것입니다. 되살려야 할 파일이 있다면 폴더 단위로 크게 막지 말고, 파일 단위로 패턴을 좁혀서 적으세요.
3단계 — 프로젝트마다 반복하지 않는다
매번 같은 패턴을 복사해 붙여넣고 있다면 사용자 설정의 전역 무시 패턴을 활용할 수 있습니다. 프로젝트별로 파일을 만들지 않아도 모든 작업 공간에 공통 규칙이 적용되므로, "새로 클론한 저장소에서 깜빡했다"는 유형의 사고를 줄여줍니다. 개인 공통 규칙은 전역에, 팀이 공유해야 하는 규칙은 저장소의 .cursorignore에 두는 식으로 나누면 관리가 단순해집니다.
4단계 — 설정했다고 믿지 말고 확인한다
설정 후 확인하는 절차를 한 번만 거치면 됩니다. 대상 파일을 @로 불러봐서 첨부가 막히는지, 코드베이스 검색 결과에 그 경로가 튀어나오지 않는지 보면 됩니다. 여기서 "어? 그대로 붙네" 싶으면 십중팔구 두 파일을 반대로 썼거나 패턴이 디렉터리 단위로 잘못 걸린 경우입니다. 팀 저장소라면 .cursorignore 자체를 커밋해 모든 팀원에게 같은 규칙이 적용되도록 하는 편이 안전합니다.
자주 하는 실수 세 가지
- 두 파일을 반대로 쓴다 — 비밀키를
.cursorindexingignore에 넣어두고 안심하는 경우입니다. 그 파일은 색인에서만 빠질 뿐 여전히 @로 첨부됩니다. - 이미 커밋된 비밀을 무시 파일로 덮으려 한다 — 저장소 히스토리에 올라간 키는 무시 목록과 아무 상관이 없습니다. 해당 키를 폐기하고 새로 발급하는 것이 유일한 해결책입니다.
- 무시 파일 하나로 끝났다고 생각한다 — 앞서 본 것처럼 터미널과 MCP 경로는 통제 밖입니다. 에이전트에게 자동 실행 권한을 넓게 열어둔 상태라면, 무시 파일의 실효성은 그만큼 줄어듭니다.
회사 코드라면 한 단계 더: 데이터 사용 설정 확인
개인 토이 프로젝트가 아니라 업무 코드라면 파일 단위 차단보다 계정 단위 설정이 먼저입니다. Cursor는 Privacy Mode를 제공하며, 공식 안내에 따르면 이 모드에서는 사용자의 데이터가 학습에 사용되지 않고, 모델 제공사와도 데이터를 보관하지 않는 계약(zero data retention)을 유지한다고 설명합니다. 조직 계정이라면 관리자가 정책을 강제할 수 있는지도 함께 확인해두면 좋습니다. 도구 설정과 별개로, 사내 규정상 외부 AI 도구에 코드를 올려도 되는지는 회사 정책에 따라 다르므로 미리 확인이 필요합니다.
자주 묻는 질문
.gitignore만 잘 써두면 충분한가요?
인덱싱 측면에서는 상당 부분 커버됩니다. 하지만 "커밋은 해야 하지만 AI에게는 안 보이고 싶은 파일"은 .gitignore로 표현할 수 없습니다. 그 경우가 있다면 .cursorignore를 따로 두세요.
인덱싱을 아예 끄면 더 안전한가요?
검색 색인 경로는 사라지지만, @로 첨부하거나 에이전트가 파일을 읽는 경로는 그대로 남습니다. 대신 코드베이스 전체 검색 품질은 떨어집니다. 안전성과 편의를 맞바꾸는 선택이라, 저장소 성격에 따라 판단하는 것이 좋습니다.
무시 파일을 고치면 바로 반영되나요?
반영 시점이나 색인 재구축 동작은 버전에 따라 달라질 수 있으므로, 수정 후에는 4단계처럼 실제로 첨부를 시도해 확인하는 편이 확실합니다.
결론
.cursorignore는 접근 자체를 막으려는 파일에, .cursorindexingignore는 색인만 줄이려는 파일에 씁니다. 그리고 어느 쪽도 완전한 차단을 보장하지 않으며, 에이전트의 터미널·MCP 실행 경로는 애초에 통제 밖입니다. 오늘 작업 중인 저장소 루트에 .cursorignore를 하나 만들고, .env가 정말 @로 첨부되지 않는지 딱 한 번만 확인해보세요. 그 1분이 나중에 키를 전부 재발급하는 반나절을 아껴줍니다.
본 글은 일반 정보 제공 목적이며, 개별 상황에 따라 다를 수 있으니 전문가 상담을 권장합니다.
댓글 없음:
댓글 쓰기