Cursor AI 개발 2026: AI가 내 코드를 이해하게 만드는 컨텍스트 설정 4가지 (Rules·@심볼·인덱싱)

6월 07, 2026

Cursor AI 개발을 시작했는데 "생각보다 별로네"라고 느낀 적 있으신가요? 같은 도구인데 누군가는 하루 만에 기능 하나를 붙이고, 누군가는 AI가 뱉은 엉뚱한 코드를 고치느라 더 오래 걸립니다. 차이는 모델 성능이 아니라 AI에게 내 프로젝트의 맥락(context)을 얼마나 정확히 주느냐에 있습니다. 이 글에서는 Cursor를 단순 자동완성기가 아니라 내 코드베이스를 이해하는 페어 프로그래머로 바꾸는 4가지 컨텍스트 설정 — 작업 모드 구분, 코드베이스 인덱싱, @ 심볼, 그리고 Rules — 를 단계별로 정리합니다. (본 글의 기능 설명은 작성 시점인 2026년 6월 기준입니다.)

Cursor AI 개발의 출발점: 4가지 작업 모드부터 구분하기

대부분의 시행착오는 "지금 어떤 모드를 써야 하는지" 모르는 데서 옵니다. Cursor는 자동화 정도가 다른 여러 입력 방식을 제공하는데, 공식 문서는 이를 '자율성 슬라이더(autonomy slider)'에 비유합니다. 작업 성격에 맞게 골라야 헛심을 안 씁니다.

방식	호출	작동 범위	언제 쓰나
Tab(자동완성)	입력 중 자동	현재 파일 한 곳	다음 줄·반복 패턴을 빠르게 채울 때
Cmd/Ctrl+K	코드 선택 후	선택한 코드 블록	특정 함수만 콕 집어 수정할 때
Ask	채팅	읽기 전용(코드 수정 안 함)	구조 파악·라이브러리 선택을 물어볼 때
Agent	Cmd/Ctrl+I	여러 파일·터미널 명령까지	기능 하나를 통째로 맡길 때

핵심은 Tab과 Agent의 차이입니다. Tab은 지금 열려 있는 파일 한 개 안에서만 동작하며 새 파일을 만들거나 터미널 명령을 실행하지 못합니다. 반면 Agent는 코드베이스를 읽고 계획을 세운 뒤 여러 디렉터리의 파일을 수정하고, 터미널 명령을 돌리고, 테스트까지 실행합니다. "한 줄 채우기"에 Agent를 부르면 과하고, "기능 추가"에 Tab만 쓰면 답답한 이유가 여기 있습니다. 모드별 동작은 Cursor 공식 문서에서 확인할 수 있습니다.

맥락의 기본기: 코드베이스 인덱싱

Cursor가 "우리 프로젝트"를 이해하는 토대는 코드베이스 인덱싱입니다. 워크스페이스(프로젝트 폴더)를 처음 열면 자동으로 인덱싱이 시작되고, 코드를 의미 단위로 검색 가능한 형태(임베딩)로 변환합니다. 단순 텍스트 일치가 아니라 "결제 로직이 어디 있지?" 같은 의미 기반 검색이 가능해지는 이유입니다.

인덱싱은 워크스페이스를 열 때 자동으로 시작됩니다.
변경된 파일만 주기적으로 다시 반영해 인덱스를 최신으로 유지합니다.
채팅에서 @Codebase를 입력하면 이 인덱스를 활용해 질문과 가장 관련 있는 코드 조각을 자동으로 찾아옵니다.

자세한 동작은 Cursor의 코드베이스 인덱싱 문서에 정리돼 있습니다. 큰 프로젝트라면 인덱싱이 끝났는지 확인한 뒤 작업을 시작하는 습관만으로도 답변 품질이 달라집니다.

민감한 파일은 인덱싱에서 빼두기

인증 키나 환경 설정처럼 AI가 보지 않았으면 하는 파일이 있다면 루트에 .cursorignore 파일을 만들어 제외할 수 있습니다. 작성 문법은 .gitignore와 같고, Cursor는 기본적으로 .gitignore에 적힌 파일도 무시합니다. 인덱싱(검색)에서만 빼고 싶다면 .cursorindexingignore를 쓰면 됩니다. 용량이 큰 생성 파일이나 외부 의존성 폴더를 빼두면 인덱싱이 빨라지고 검색 정확도도 올라갑니다. 자세한 규칙은 공식 Ignore Files 문서에서 확인하세요.

@ 심볼로 '필요한 맥락만' 정확히 주기

AI에게 코드베이스 전체를 통째로 던지면 오히려 핵심을 놓칩니다. Cursor의 @ 심볼은 "이 맥락만 봐"라고 범위를 좁혀주는 도구입니다. 상황별로 골라 쓰면 같은 질문도 훨씬 정확한 답이 돌아옵니다.

@Files / @folder — 특정 파일·폴더에 집중시키기

가장 직관적입니다. @Files를 입력하면 파일 선택창이 떠서 AI가 참고할 파일을 명시적으로 지정할 수 있습니다. "이 컴포넌트와 같은 패턴으로 만들어줘"처럼 기준이 되는 파일이 분명할 때 효과적입니다.

@Codebase — 어디 있는지 모를 때

관련 코드가 어느 파일에 흩어져 있는지 모를 때 씁니다. 인덱스를 기반으로 질문과 관련된 조각을 알아서 모아오므로, 리팩터링이나 버그 추적의 출발점으로 좋습니다.

@Docs — 프레임워크 공식 문서 끌어오기

@Docs는 문서 URL을 직접 넣거나 Cursor에 내장된 주요 프레임워크 문서를 선택해 맥락에 더합니다. 라이브러리 사용법을 추측이 아니라 공식 문서에 근거해 작성하도록 유도할 수 있습니다.

@Web — 최신 정보가 필요할 때

모델이 학습하지 못한 최신 라이브러리나 변경 사항이 필요하면 @Web으로 웹 검색 결과를 끌어옵니다. 막 나온 버전의 API를 다룰 때 특히 유용합니다.

Rules로 AI 행동을 '영구 고정'하기

매번 "세미콜론 빼줘", "우리는 함수형으로 써"라고 반복하고 있다면 Rules를 쓸 차례입니다. Rules는 Cursor의 AI에게 코딩 컨벤션과 동작 방식을 지속적으로 알려주는 설정 파일입니다.

어디에 두나 — .cursor/rules 디렉터리와 .mdc 파일

현재 권장되는 방식은 프로젝트 루트의 .cursor/rules/ 디렉터리 안에 규칙별로 .mdc 파일을 두는 것입니다. Cursor는 이 폴더의 .mdc 파일들을 재귀적으로 읽습니다. 과거 방식인 루트의 단일 .cursorrules 파일도 여전히 읽히지만, 새로 시작한다면 디렉터리 방식이 관리하기 편합니다. 파일은 명령 팔레트(Cmd/Ctrl+Shift+P)에서 "New Cursor Rule"을 실행해 손쉽게 만들 수 있습니다.

4가지 적용 모드 — 언제 발동할지 정하기

각 .mdc 파일은 상단의 YAML 프런트매터로 발동 조건을 정합니다. 모드를 잘못 고르면 규칙이 엉뚱한 때 적용되거나 아예 무시되니 중요합니다.

Always Apply: 모든 대화에 항상 포함
Auto Attached: 지정한 glob 패턴(예: *.tsx)의 파일을 만질 때 자동 적용
Agent Requested: 설명(description)을 보고 AI가 필요하다 판단하면 적용
Manual: @규칙이름으로 직접 호출할 때만 적용

실전 팁과 흔한 실수

'항상 적용' 규칙은 짧게. Always Apply 규칙은 모든 요청에 매번 실려 컨텍스트 예산을 갉아먹습니다. 핵심만 간결하게 유지하는 편이 좋습니다.
팀이라면 커밋하라. .cursor/rules/ 디렉터리를 저장소에 함께 커밋하면 팀원 모두가 같은 컨벤션과 일관된 결과물을 공유하게 됩니다.
한 파일에 다 넣지 말기. 목적별로 파일을 나누면(예: 아키텍처 / 코딩 스타일) 어떤 규칙이 언제 적용되는지 추적하기 쉽습니다.

자주 묻는 질문 (FAQ)

Q. Cursor는 VS Code와 무엇이 다른가요?

Cursor는 VS Code를 기반으로 만들어진 에디터입니다. 그래서 기존 단축키와 확장 환경을 거의 그대로 쓰면서, 위에서 설명한 인덱싱·@ 심볼·Rules 같은 AI 기능이 에디터에 깊게 통합돼 있다는 점이 가장 큰 차이입니다.

Q. Rules를 만들었는데 적용이 안 돼요.

적용 모드를 먼저 확인하세요. Manual 모드는 채팅에서 @규칙이름으로 직접 불러야 하고, Auto Attached 모드는 프런트매터의 glob 패턴에 맞는 파일을 열거나 편집할 때만 발동합니다. "항상 적용"이 필요하면 Always Apply로 지정해야 합니다.

Q. @Codebase와 @Files 중 무엇을 써야 하나요?

참고할 파일이 명확하면 @Files로 콕 집어 주는 편이 정확합니다. 반대로 "이 기능이 어디서 처리되는지조차 모르겠다" 싶을 때는 @Codebase로 인덱스 검색을 맡기는 것이 출발점으로 좋습니다.

결론

Cursor AI 개발의 성패는 모델이 아니라 맥락 설계에서 갈립니다. 작업 성격에 맞는 모드를 고르고, 코드베이스 인덱싱을 켜두고, @ 심볼로 필요한 맥락만 주고, Rules로 반복 지시를 고정하는 것 — 이 네 가지만 익혀도 AI의 결과물 품질이 눈에 띄게 올라갑니다. 오늘은 우선 자주 쓰는 프로젝트에 .cursor/rules 규칙 파일 하나를 만들어보는 것부터 시작해보세요.

이 블로그 검색

돈이되는AI