Cursor @멘션 총정리 (2026년 기준): 뭐가 남았고 뭐가 사라졌나

핵심 요약: @멘션은 Cursor에게 "이걸 보고 답해"라고 컨텍스트를 지목하는 문법입니다. 2026년 기준 실전 핵심은 넷 — @파일/@폴더(정확히 아는 대상), @codebase(시맨틱 검색, 뭘 봐야 할지 모를 때), @Docs(색인해 둔 외부 문서), @definitions(선택 코드의 심볼 정의). 주의: 구버전 튜토리얼에 나오는 @Web·@Git은 축소·정리되는 추세입니다 — 최근 버전은 웹 검색과 git 조회를 에이전트가 알아서 수행하므로, 화면이 튜토리얼과 다르다면 그 때문입니다.

이 글에서 다루는 내용: 멘션별 용도와 선택 기준, @codebase를 잘 쓰는 법, @Docs 색인, 사라진 멘션들.

선택 기준: "내가 아는가, 모르는가"

멘션 선택은 한 가지 질문으로 정리됩니다. 어느 파일을 봐야 하는지 내가 아는가? 안다면 @파일/@폴더로 정확히 지목하는 것이 가장 싸고 정확합니다. 모른다면 @codebase — Cursor가 프로젝트 전체의 시맨틱 인덱스에서 관련 코드를 찾아 넣어줍니다. "인증이 어디서 처리되지?" 같은 탐색 질문에 파일을 20개 때려 넣는 것보다 @codebase 한 번이 낫습니다. 관련 파일을 과하게 넣으면 오히려 집중이 흐려진다는 것, 컨텍스트 원리 그대로입니다.

멘션별 정리 (2026년 기준)

멘션	용도	이럴 때
@파일 / @폴더	특정 파일·디렉터리 지목	볼 곳을 정확히 알 때
@codebase	전체 코드베이스 시맨틱 검색	어디 있는지 모를 때, 구조 질문
@Docs	색인된 외부 문서 참조	프레임워크 최신 문법, 사내 위키
@definitions	선택 영역의 심볼 정의 포함	타입·함수 정의까지 봐야 할 때
이미지 첨부	스크린샷·디자인 전달	UI 버그, 시안 구현

@Docs: 과소평가된 기능

설정(Settings → Docs)에서 문서 URL을 추가하면 Cursor가 크롤링·색인하고, 이후 @Docs로 참조할 수 있습니다. 가치가 큰 지점은 모델의 학습 데이터보다 새로운 라이브러리입니다 — 신버전 프레임워크 문법을 옛날 방식으로 짜는 문제가 @Docs 색인 하나로 크게 줄어듭니다. 사내 API 문서를 색인해 두면 팀 온보딩 도구도 됩니다.

사라지는 것들: @Web, @Git

구버전 가이드에 흔히 나오는 @Web(웹 검색)과 @Git(커밋·diff 참조)은 최근 버전에서 정리되는 추세입니다. 방향은 일관됩니다 — 에이전트가 필요하면 알아서 웹을 검색하고 git을 조회하므로, 사용자가 소스를 지목하는 대신 그냥 "최근 커밋에서 이 버그가 들어온 지점 찾아줘"라고 말하면 됩니다. 멘션은 "무엇을 볼지"에서 "정확히 지목할 가치가 있는 것"으로 역할이 좁아지는 중이고, 이는 다른 도구들도 같은 방향입니다. 내 버전에서 뭐가 되는지는 입력창에 @를 쳐보는 게 가장 빠릅니다.

실전에서 정착한 조합

제 기본 패턴은 세 가지입니다. 새 기능: @폴더(작업 영역) + @Docs(프레임워크) — 명세를 쓰고 시작. 버그 추적: @codebase로 "이 동작 어디서 처리되나" 먼저 찾고, 나온 파일들을 @파일로 고정해 좁혀가기. 레거시 이해: @codebase 질문 몇 번으로 지도를 그린 뒤에 수정 시작. 멘션을 안 쓰고 맡기는 것도 에이전트 모드에선 꽤 통하지만, 멘션으로 시작점을 좁혀주면 같은 결과가 더 적은 사용량으로 나옵니다.

자주 묻는 질문 (FAQ)

Q. @codebase가 이상한 파일을 가져와요.

A. 인덱스 문제일 수 있습니다. 첫 실행 시 인덱싱이 끝나길 기다렸는지, 대규모 브랜치 머지 후 재인덱싱을 했는지 확인하세요. 인덱싱 상태는 상태 표시줄에서 볼 수 있습니다.

Q. 튜토리얼에 나오는 @Web이 저는 안 보여요.

A. 최근 버전에서 정리됐기 때문입니다. 웹 검색이 필요하면 멘션 없이 에이전트에게 검색해 달라고 지시하면 됩니다.

Q. 파일을 많이 멘션할수록 좋은 것 아닌가요?

A. 아닙니다. 무관한 파일은 집중을 흐리고 사용량만 늘립니다. 직접 관련된 파일만 지목하고, 애매하면 @codebase에 맡기세요.

한눈에 보는 요약

아는 곳은 @파일, 모르는 곳은 @codebase, 바깥 지식은 @Docs. @Web·@Git은 에이전트 자동화로 흡수되는 중. 멘션의 목적은 많이 넣기가 아니라 정확히 좁히기입니다.

함께 보면 좋은 글

Cursor Rules(.mdc) 설정 방법
Cursor Agent 모드는 언제 쓰는 게 좋을까?
AI에게 좋은 작업 명세 쓰는 법

참고 자료

Prompting agents (Cursor Docs)
Cursor 체인지로그