Cursor AI 에디터 실전: Tab 자동완성, Chat, Composer와 .cursorrules 설정

작성 0xmote · 2026년 7월 27일 · 16분 읽기 · 수정 2026년 9월 27일 초급 튜토리얼

이 글의 핵심

Cursor는 VS Code 기반의 AI 코딩 에디터입니다. Tab 자동완성, AI Chat, Composer(에이전트 모드)를 통해 전체 기능 코드 작성, 버그 수정, 코드베이스 탐색을 AI와 함께 할 수 있습니다.

Cursor란?

Cursor는 VS Code를 포크(fork)한 AI 중심 코드 에디터입니다. 2024년부터 빠르게 사용자가 늘어 지금은 GitHub Copilot과 함께 가장 널리 쓰이는 AI 코딩 도구 중 하나가 됐습니다.

기존 에디터와 다른 점:

일반 에디터: 코드 작성 → 검색 → 문서 확인 → 다시 코드 작성
Cursor:      "이 기능 추가해줘" → AI가 파일 생성·수정 → 검토 → 적용

플러그인이 아니라 포크라는 점이 중요합니다. 확장 API가 허락하는 범위 안에서만 움직이는 플러그인과 달리, Cursor는 에디터 자체를 고쳐서 diff를 인라인으로 보여 주거나, 코드베이스 전체를 임베딩으로 인덱싱하거나, 에이전트가 터미널 명령을 실행하게 만들 수 있습니다. 대신 VS Code 본체 업데이트를 따라가는 데 시차가 생기고, Microsoft 공식 마켓플레이스 대신 Open VSX 기반 확장 저장소를 쓰기 때문에 일부 Microsoft 전용 확장(예: Pylance, C/C++ 원격 디버깅 관련 일부 기능)은 그대로 설치되지 않거나 대체 확장을 써야 하는 경우가 있습니다. 옮기기 전에 팀에서 꼭 필요한 확장이 동작하는지 먼저 확인해 두는 것이 좋습니다.

이 글은 Tab 자동완성, Chat, Composer(에이전트) 세 기능을 어떤 상황에 써야 하는지, 그리고 결과 품질을 좌우하는 규칙 파일을 어떻게 쓰는지에 초점을 맞춥니다. 메뉴 이름과 단축키는 버전마다 바뀌는 편이라, 개념 위주로 읽고 세부 위치는 현재 버전의 설정 화면에서 확인하는 것을 권합니다.

설치 및 기본 설정

설치

cursor.com에서 다운로드 (macOS, Windows, Linux 지원)

VS Code 확장 프로그램과 설정을 마이그레이션:

처음 실행 시 VS Code 설정 자동 가져오기 제안

모델 설정

Cursor Settings → Models에서 선택:

모델	특징
`claude-sonnet-4-6`	최신, 빠른 응답, 코드 품질 우수
`claude-opus-4-5`	가장 강력, 복잡한 작업
`gpt-4o`	빠른 속도, 일반 작업
`cursor-small`	매우 빠름, 간단한 자동완성

모델 목록은 몇 달 단위로 바뀌므로 위 표는 성격을 비교하기 위한 예시로 보면 됩니다. 실무에서 기준이 되는 것은 “얼마나 긴 작업을 맡기느냐”입니다. 여러 파일을 읽고 계획을 세워야 하는 에이전트 작업에는 상위 모델이 확실히 덜 헤매고, 한 함수 안의 수정이나 설명 요청은 빠른 모델로도 충분합니다. 상위 모델은 요청당 비용이 커서 사용량 기반 요금제에서는 한도가 빨리 소진되므로, 기본값을 빠른 모델로 두고 막힐 때만 올리는 방식이 비용 대비 효율이 좋습니다. Auto 모드를 켜 두면 Cursor가 부하와 작업에 따라 모델을 고르는데, 결과가 들쭉날쭉하다고 느껴지면 모델을 고정해서 비교해 보는 것이 원인을 좁히는 데 도움이 됩니다.

자신의 API 키 사용

Cursor Settings → Models → API Key 항목에 OpenAI/Anthropic 등의 키 입력

Cursor 요금제 한도와 별개로 본인 계정 사용량으로 과금
조직에서 이미 API 계약이 있다면 비용 관리를 한곳으로 모을 수 있음
Tab 자동완성처럼 Cursor 자체 모델이 담당하는 기능은 API 키로 대체되지 않고, 일부 에이전트 기능은 자체 키로 제한될 수 있음

자체 키를 쓴다고 해서 코드가 Cursor 서버를 거치지 않는 것은 아닙니다. 프롬프트 구성과 코드베이스 인덱싱은 여전히 Cursor 백엔드에서 처리되므로, 보안 요구사항이 있다면 키 설정보다 Privacy Mode 설정(코드를 학습·보관하지 않는 모드)과 회사 정책을 먼저 확인해야 합니다. 또 긴 에이전트 세션은 컨텍스트가 커질수록 요청 하나당 토큰이 크게 늘어나서, 자체 키로 쓰다가 청구서를 보고 놀라는 경우가 흔합니다. API 콘솔에서 월 사용 한도를 걸어 두는 것을 권합니다.

핵심 기능 1: Tab 자동완성

커서를 두면 AI가 다음 코드를 예측하여 제안합니다. 일반 자동완성과 다른 점은 커서 위치 한 줄만 채우는 게 아니라, 방금 한 편집을 보고 “다음에 고칠 곳”까지 예측한다는 것입니다. 예를 들어 함수 매개변수 이름을 바꾸면 같은 함수 안의 사용처로 커서를 옮기는 제안이 뜨고, Tab을 연달아 누르면 수정이 이어집니다. 이 기능은 Cursor 자체 모델이 담당하기 때문에 Chat에서 고른 모델과는 관계가 없습니다.

아래 예시는 함수 시그니처만 쓰다가 Tab을 눌렀을 때 본문이 채워지는 모습입니다. 주석 부분이 AI가 제안한 코드입니다.

def calculate_fibonacci(n: int) ->  # Tab을 누르면...
# → def calculate_fibonacci(n: int) -> list[int]:
#        if n <= 0:
#            return []
#        elif n == 1:
#            return [0]
#        ...

팁: 주석으로 의도를 먼저 설명하면 더 정확한 코드 생성

# 사용자 인증 미들웨어: JWT 토큰 검증 후 user_id를 request에 추가
def auth_middleware(request):  # Tab → 전체 구현 자동 생성

주석이 효과가 있는 이유는 모델이 보는 컨텍스트가 “현재 파일의 앞뒤 코드와 최근 편집 내역”이기 때문입니다. 함수 이름만으로는 JWT를 쓰는지 세션을 쓰는지 알 수 없지만, 한 줄 주석이 있으면 선택지가 좁혀집니다. 다만 Tab이 만든 전체 구현을 그대로 받아들이는 것은 위험합니다. 인증 코드처럼 보안이 걸린 부분에서 흔히 보는 문제는, 그럴듯해 보이지만 토큰 만료(exp) 검사를 빠뜨리거나 서명 알고리즘을 고정하지 않는 코드가 제안되는 경우입니다. 문법적으로는 맞고 테스트도 통과해서 리뷰에서 놓치기 쉽습니다.

제가 Tab 자동완성을 쓰면서 가장 자주 겪은 불편은 반대로 “너무 공격적인 제안”입니다. 마크다운이나 설정 파일처럼 예측이 어려운 곳에서도 여러 줄짜리 제안이 계속 떠서 입력을 방해하는데, 이럴 때는 상태 표시줄에서 특정 언어나 파일 형식에 대해 Tab을 끄는 것이 낫습니다. 반복적인 리팩토링(같은 패턴의 수정 여러 곳)에서는 Tab이 가장 큰 효과를 내고, 새로운 로직을 처음부터 쓰는 경우는 Chat이나 Composer로 설계를 먼저 정한 뒤 Tab으로 다듬는 편이 결과가 좋았습니다.

핵심 기능 2: AI Chat (Ctrl+L / Cmd+L)

코드에 대해 질문하거나 수정을 요청합니다. Chat의 답변 품질은 거의 전적으로 “무엇을 컨텍스트로 넣었느냐”에 달려 있습니다. 모델은 열려 있는 파일을 자동으로 전부 읽지 않고, 현재 파일과 선택 영역 정도만 기본으로 받습니다. 그래서 다른 파일에 정의된 타입이나 함수에 대해 물으면 존재하지 않는 API를 지어내는 답이 나오기 쉽습니다. 이를 막는 수단이 @ 참조입니다.

@ 참조 활용

Chat 입력창에서 @를 입력하면 아래 항목을 고를 수 있습니다.

@파일명        특정 파일을 컨텍스트에 추가
@폴더명        폴더 전체를 컨텍스트에 추가
@Codebase      전체 코드베이스에서 관련 코드 검색
@Web           웹 검색으로 최신 정보 참조
@Docs          지정한 공식 문서 참조
#파일명        현재 파일의 특정 부분 지정

@파일은 해당 파일 내용을 그대로 넣는 방식이라 정확하지만, 큰 파일이나 폴더를 여러 개 넣으면 컨텍스트 창이 금방 차고 요청 비용도 늘어납니다. @Codebase는 반대로 미리 만들어 둔 임베딩 인덱스에서 질문과 비슷한 코드 조각을 검색해 넣는 방식입니다. 어디에 있는지 모르는 코드를 찾을 때 유용하지만, 검색이 놓친 파일은 답변에 반영되지 않습니다. 그래서 “인증은 어디서 처리하나요?”처럼 위치를 찾는 질문은 @Codebase로, 찾은 뒤 실제 수정 요청은 해당 파일을 @파일로 명시해서 하는 두 단계가 가장 안정적입니다. 인덱스는 .gitignore와 .cursorignore를 따르므로, 빌드 산출물이나 대용량 데이터 폴더를 제외해 두면 검색 품질이 좋아지고 비밀 파일이 인덱싱되는 것도 막을 수 있습니다.

실전 사용 예시:

# 에러 디버깅
이 에러가 왜 발생하는지 설명해줘:
TypeError: Cannot read property 'map' of undefined
  at @src/components/PostList.tsx:23

# 코드 리뷰
@src/api/auth.ts 이 인증 코드의 보안 취약점을 찾아줘

# 코드베이스 탐색
@Codebase 사용자 인증은 어디서 처리되나요?

# 공식 문서 참조
@Docs[React 18] Suspense와 함께 데이터 패칭하는 best practice 알려줘

에러 디버깅에서는 에러 메시지만 붙이는 것보다 스택 트레이스 전체와 에러가 난 파일을 함께 넣는 것이 훨씬 낫습니다. Cannot read property 'map' of undefined는 증상일 뿐이고 원인은 대개 데이터를 넘겨주는 상위 컴포넌트나 API 응답 형태에 있는데, 해당 파일만 넣으면 AI는 data?.map()처럼 증상만 가리는 수정을 제안하기 쉽습니다. @Docs는 공식 문서를 인덱싱해 두고 참조하는 기능이라, 모델의 학습 시점 이후에 바뀐 라이브러리 API를 다룰 때 특히 쓸모가 있습니다.

핵심 기능 3: Composer / Agent (Ctrl+I / Cmd+I)

에이전트 모드 — 여러 파일을 자동으로 생성하고 수정합니다. 최근 버전에서는 Chat과 Composer가 하나의 패널로 합쳐져 Ask(질문만), Agent(파일 수정·터미널 실행) 같은 모드로 전환하는 방식이 되었지만, 개념은 같습니다.

Chat과의 결정적인 차이는 에이전트가 스스로 도구를 쓴다는 점입니다. 필요한 파일을 직접 검색해 읽고, 수정한 뒤 린터 오류를 확인하고, 허용하면 테스트나 빌드 명령까지 실행해 결과를 보고 다시 고칩니다. 그만큼 한 번의 요청으로 할 수 있는 일이 크지만, 요청 범위가 모호하면 관계없는 파일까지 “개선”해 버리는 부작용도 커집니다. 터미널 명령 자동 실행은 기본적으로 확인을 받도록 두고, rm이나 DB 마이그레이션처럼 되돌리기 어려운 명령은 허용 목록에 넣지 않는 것이 안전합니다.

사용 예시

Composer 입력창에 다음처럼 요청합니다.

프롬프트: "사용자 프로필 수정 기능을 추가해줘.
- PUT /api/users/:id 엔드포인트
- 닉네임, 프로필 이미지 URL 수정 가능
- 유효성 검사 포함
- 기존 auth 미들웨어 사용"

→ Cursor가 자동으로:
  ✅ src/routes/users.ts 수정
  ✅ src/validators/userValidator.ts 생성
  ✅ src/types/user.ts 업데이트
  ✅ tests/users.test.ts 생성

요청에 “기존 auth 미들웨어 사용”처럼 제약을 적어 두는 것이 핵심입니다. 제약이 없으면 에이전트는 기존 코드를 찾기보다 새 미들웨어를 하나 더 만드는 쪽을 택하는 경우가 많고, 그러면 비슷한 코드가 두 벌 생깁니다. 생성된 테스트도 주의해서 봐야 합니다. 에이전트가 구현과 테스트를 같이 만들면 테스트가 구현의 동작을 그대로 따라 적은 형태가 되기 쉬워서, 요구사항이 잘못 이해됐을 때 테스트도 같이 틀립니다.

Composer 실전 팁

실제로 효과가 있었던 요청 방식은 다음과 같습니다.

# 1. 명확한 컨텍스트 제공
@src/models/User.ts @src/routes/ 를 참고해서 
새로운 Comment 모델과 CRUD API를 추가해줘

# 2. 단계적 접근
먼저 Comment 모델만 만들어줘 (마이그레이션 포함)
→ 검토 후 →
이제 Comment API 라우터를 추가해줘

# 3. 체크포인트 활용
각 단계에서 Composer가 만든 변경사항을 검토하고
문제가 있으면 "이 파일은 그대로 두고 나머지만 수정해줘"

제가 에이전트 모드를 쓰면서 가장 많이 겪은 문제는 대화가 길어질수록 품질이 떨어지는 현상입니다. 수정-확인-재수정을 여러 번 반복하면 앞부분의 지시와 이미 되돌린 코드가 컨텍스트에 섞여, 에이전트가 예전 버전을 기준으로 다시 고치거나 방금 합의한 규칙을 잊어버립니다. 이럴 때 같은 대화에서 계속 설명을 보태는 것보다, 지금까지 결정된 사항을 몇 줄로 정리해 새 대화를 여는 편이 훨씬 빨리 끝났습니다. 단계를 나누는 두 번째 팁도 같은 이유에서 효과가 있습니다. 한 단계가 끝날 때마다 Git 커밋을 해 두면 Cursor의 체크포인트 복원이 꼬였을 때도 확실하게 되돌릴 수 있습니다.

.cursorrules 설정

프로젝트 루트에 .cursorrules 파일을 만들어 AI의 동작을 정의합니다. 규칙 파일의 내용은 Chat과 에이전트 요청마다 시스템 프롬프트에 붙어 전달되므로, 매번 “타입 힌트 넣어줘”, “logging 써줘”라고 반복할 필요가 없어집니다.

현재 Cursor는 루트의 .cursorrules 한 파일 대신 .cursor/rules/ 폴더에 .mdc 파일을 여러 개 두는 Project Rules를 권장합니다. 각 규칙 파일 상단에 globs: src/api/**/*.ts 같은 적용 범위를 지정할 수 있어서, 백엔드 규칙이 프런트엔드 파일 작업에 끼어드는 일을 줄일 수 있습니다. 기존 .cursorrules도 계속 읽히므로 아래 예시는 어느 방식에든 그대로 옮겨 쓸 수 있습니다.

규칙을 쓸 때 주의할 점은 길이입니다. 규칙 전체가 매 요청의 토큰으로 들어가기 때문에, 수백 줄짜리 스타일 가이드를 통째로 붙이면 비용이 늘고 정작 중요한 규칙이 묻힙니다. 린터나 포매터(Ruff, ESLint, Prettier)가 강제할 수 있는 규칙은 도구에 맡기고, 규칙 파일에는 “우리 프로젝트는 이 라이브러리를 쓴다”, “이 패턴은 금지한다”처럼 도구가 알 수 없는 결정만 남기는 것이 효과적입니다.

Python 프로젝트 예시

# .cursorrules
You are an expert Python developer working on a FastAPI project.

## 코드 스타일
- Python 3.12+ 기능 적극 활용 (match/case, type hints 등)
- 함수는 반드시 타입 힌트 포함
- 변수명은 snake_case, 클래스명은 PascalCase
- 줄 길이 최대 100자

## 프레임워크 규칙
- FastAPI의 의존성 주입 시스템 사용 (Depends)
- Pydantic v2 모델 사용
- 비동기 처리: async/await 우선
- 에러 처리: HTTPException 사용

## 금지 사항
- global 변수 사용 금지
- print() 대신 logging 사용
- 하드코딩된 값은 환경변수로 분리

## 테스트
- pytest 사용
- 각 함수마다 단위 테스트 작성
- given/when/then 패턴 사용

TypeScript 프로젝트 예시

# .cursorrules
You are an expert TypeScript developer working on a Next.js 15 project.

## 기술 스택
- Next.js 15 (App Router)
- TypeScript strict mode
- Tailwind CSS + shadcn/ui
- Zustand (상태 관리)
- React Query (서버 상태)

## 코드 규칙
- Server Components 우선 사용
- 클라이언트 컴포넌트는 'use client' 명시 최소화
- 타입 any 사용 금지
- interface 대신 type 사용

## 파일 구조
- 컴포넌트: src/components/[기능]/[컴포넌트명].tsx
- 서버 액션: src/actions/[기능].ts
- API 라우트: src/app/api/[기능]/route.ts

TypeScript 예시의 “Server Components 우선 사용” 같은 규칙이 특히 쓸모 있습니다. 모델이 학습한 코드 중에는 Pages Router 시절 코드가 압도적으로 많아서, 규칙 없이 요청하면 getServerSideProps나 불필요한 'use client'가 섞인 코드가 자주 나옵니다. 프레임워크 버전과 라우팅 방식을 규칙에 명시해 두면 이런 “과거 버전 코드”가 눈에 띄게 줄어듭니다.

Cursor vs VS Code + Copilot 비교

기능	Cursor	VS Code + Copilot
Tab 자동완성	다음 편집 위치 예측까지	인라인 제안 + Next Edit Suggestions
멀티파일 편집	✅ Composer/Agent	✅ Copilot Edits
코드베이스 검색	✅ @Codebase	✅ @workspace
에이전트 모드	✅	✅ (2025년 도입)
모델 선택	✅ 다양	✅ GPT/Claude/Gemini 선택
VS Code 확장	대부분 호환 (Open VSX)	✅ 네이티브
가격	Pro 월 $20 수준	Pro 월 $10 수준
프라이버시	코드 서버 전송 (Privacy Mode 선택)	코드 서버 전송 (조직 정책 설정)

한때는 멀티파일 편집과 에이전트 모드가 Cursor만의 기능이었지만, 2025년 이후 Copilot도 같은 기능을 갖추면서 기능표만으로는 차이가 크지 않게 됐습니다. 실제 차이는 완성도와 통합 방식에서 납니다. Cursor는 에디터를 직접 고칠 수 있어 diff 표시, 체크포인트, 인덱싱이 한 흐름으로 묶여 있고 새 기능이 빨리 들어옵니다. Copilot은 GitHub 이슈·PR과 연결되고, 기업 입장에서는 기존 Microsoft/GitHub 계약과 관리 정책 안에서 쓸 수 있다는 점이 큽니다. 이미 GitHub Enterprise를 쓰는 조직이라면 Copilot을, 개인이나 작은 팀이 에이전트 기능을 적극적으로 쓰고 싶다면 Cursor를 먼저 시험해 보는 것이 현실적인 선택입니다. 두 도구 모두 무료 한도가 있으니 같은 작업을 양쪽에서 해 보고 결정하는 것이 가장 정확합니다.

실전 워크플로우

새 기능 추가 (Composer 활용)

1. Cmd+I 로 Composer 열기
2. 컨텍스트 추가: @관련파일들
3. 요청 작성:
   "결제 처리 기능 추가. 
    Stripe SDK 사용. 
    @src/models/Order.ts 의 Order 모델 참고.
    실패 시 재시도 로직 포함."
4. 생성된 파일 검토 (diff 뷰어)
5. Accept All 또는 개별 Accept

Accept 단계에서 파일 목록만 보고 전체 적용하지 말고, 특히 package.json이나 설정 파일 변경이 섞여 있는지 확인하는 습관이 중요합니다. 에이전트가 문제를 우회하려고 의존성을 추가하거나 TypeScript strict 옵션을 끄는 식의 “해결”을 하는 경우가 있기 때문입니다.

버그 수정 (Chat 활용)

1. 에러 메시지 복사
2. Cmd+L 로 Chat 열기
3. 에러 붙여넣기 + @현재파일
4. "이 에러 원인과 수정 방법 알려줘"
5. 제안 코드를 Apply 버튼으로 적용

코드 리뷰 자동화

# Git diff를 Chat에 붙여넣고:
"이 변경사항에서:
1. 잠재적 버그
2. 성능 문제
3. 보안 취약점
을 찾아줘"

diff를 직접 붙여넣는 대신 Chat에서 Git 변경사항을 참조하는 @Git 계열 항목을 쓰면 복사 과정이 줄어듭니다. AI 리뷰는 널 체크 누락이나 명백한 SQL 문자열 조합 같은 국소적인 문제는 잘 찾지만, “이 변경이 다른 서비스의 캐시 무효화를 깨뜨린다” 같은 시스템 수준의 문제는 컨텍스트에 없으면 찾지 못합니다. 사람 리뷰를 대체하기보다 리뷰 전에 사소한 지적을 걸러 내는 용도로 쓰는 것이 맞습니다.

유용한 단축키

단축키 (Mac)	기능
`Tab`	AI 제안 수락
`Esc`	AI 제안 거부
`Cmd+L`	AI Chat 열기
`Cmd+I`	Composer 열기
`Cmd+K`	인라인 편집
`Cmd+Shift+L`	Chat에 선택 코드 추가
`Cmd+Enter`	Chat에서 코드베이스 검색을 포함해 전송 (버전에 따라 다름)

Windows/Linux에서는 Cmd를 Ctrl로 바꾸면 됩니다. Cmd+K 인라인 편집은 선택한 몇 줄만 고치는 가장 가벼운 방법이라, 파일 전체를 다시 쓰는 Composer보다 결과를 검토하기 쉽습니다. 단축키가 VS Code 기본 단축키(Cmd+K 조합 등)와 겹치므로, 기존 키 바인딩에 익숙하다면 설정에서 충돌하는 항목을 먼저 정리해 두는 것이 좋습니다.

자주 묻는 질문 (FAQ)

Q. Composer가 여러 파일을 한 번에 수정했을 때 Accept All을 눌러도 되나요?

A. Composer는 여러 파일에 걸친 변경을 한 번에 제안하기 때문에, 요청과 무관한 파일까지 건드리거나 기존 동작을 바꾸는 수정이 섞여 있을 수 있습니다. 적용하기 전에 diff 뷰어에서 파일별 변경을 확인하고 필요한 부분만 개별로 Accept하는 편이 안전합니다. 작업 전에 Git으로 커밋해 두면 결과가 마음에 들지 않을 때 쉽게 되돌릴 수 있습니다.