Cursor AI 가이드 — 프로젝트 규칙부터 Agent까지

Cursor AI — Copilot을 넘어선 에이전트급 코드 에디터

지금 어떤 코드 에디터를 쓰고 계신가요? VS Code에 GitHub Copilot을 붙여서 쓰시는 분이 많을 것입니다. 자동완성은 편리하지만, 예전 방식은 커서를 올린 그 줄 위주로 도와줄 뿐 프로젝트 전체를 보지 못하는 한계가 있었습니다. 지금은 Copilot 도 Agent 모드를 제공하므로(GitHub Docs 요금제 표 기준) 선택 기준은 “누가 더 똑똑한가”보다 “어떤 작업 방식이 내게 편한가”에 가깝습니다.

Cursor AI 가이드 — 프로젝트 규칙부터 Agent까지 (2026) — 사진: Unknown / rawpixel (CC0)

Cursor AI는 이 문제를 겨냥한 에이전트형 코드 에디터입니다. Agent 가 코드베이스를 검색하고 여러 파일을 수정하며 터미널 명령까지 실행할 수 있습니다(Cursor 공식 문서). 이 글에서는 프로젝트 규칙(.cursor/rules) 설정부터 Agent로 여러 파일을 한 번에 수정하는 방법까지, Cursor AI의 핵심 기능을 처음부터 끝까지 다룹니다.

1. Cursor vs Copilot — 3가지 작업 방식 차이

“Cursor가 Copilot보다 뭐가 좋은데?” 가장 많이 받는 질문부터 시작하겠습니다. 세 가지로 정리합니다.

첫째, Codebase-Aware

Cursor는 프로젝트 전체 파일을 읽고 이해합니다. Cursor의 Agent는 파일·폴더 이름과 키워드로 코드베이스를 검색해 관련 파일을 찾아 읽습니다(공식 문서의 파일·폴더 검색 도구). “이 프로젝트에서 이 함수는 어떻게 쓰이고 있어?”라고 물으면 관련 파일을 찾아 답합니다. 다른 파일에서 import하는 함수의 시그니처나 테스트 코드도 찾아 읽어 답에 반영할 수 있습니다. Copilot 도 Agent 모드를 제공하므로 이 차이는 예전보다 줄었습니다.

둘째, Multi-File Edit

자동완성은 한 줄, 한 함수 단위로 제안하지만, Cursor의 Agent는 여러 파일을 동시에 수정합니다(Copilot의 Agent 모드로도 비슷한 작업을 할 수 있습니다). “이 API 엔드포인트 추가하고, 프론트엔드에서 호출하는 코드도 만들어줘”라고 하면, 백엔드 파일과 프론트엔드 파일을 동시에 편집합니다. 수동으로 파일을 오가며 반복 작업할 필요가 없습니다.

셋째, @ Mentions

채팅창에서 @ 기호를 쳐서 특정 파일·폴더, 터미널 출력(@Terminals), 이전 대화(@Chats), Git 변경분(@Commit, @Branch), 내장 브라우저(@Browser)를 참조시킬 수 있습니다. @package.json 지금 쓰는 버전에 맞게 코드 수정해줘 같은 작업이 가능합니다. 웹 검색은 Agent가 도구로 직접 수행합니다(공식 문서 기준).

2. 설치와 초기 설정

설치는 간단합니다. cursor.com에서 다운로드하면 됩니다. Cursor는 VS Code를 포크한 에디터이므로, 기존 VS Code 확장 프로그램과 설정을 그대로 가져올 수 있습니다. 처음 실행하면 VS Code 설정 가져오기 버튼이 나오는데, 클릭 한 번이면 마이그레이션이 끝납니다.

여기서 중요한 것은 모델 선택입니다. Cursor는 여러 AI 모델을 지원합니다:

Anthropic Claude — 공식 모델 목록에 Claude Sonnet 5.5·Opus 5.5 등이 있습니다
OpenAI GPT — GPT-5.6 Sol·Terra·Luna 등이 있습니다
Google Gemini·Cursor 자체 모델 — Gemini 3.1 Pro 등과 Cursor 자체 모델 Composer 2.5, Grok 계열(Cursor Models 풀)이 있습니다

Cursor Settings > Models 에서 기본 모델을 정하고 작업 중에도 바꿀 수 있습니다. 공식 문서는 빠른 모델은 간단한 수정에, 성능이 높은 모델은 복잡한 추론과 여러 파일 리팩토링에 알맞다고 안내합니다. 2026년 10월 개편 이후 신규 가입은 Free(Agent·Chat 요청 제한)와 유료 Plus 월 $8(Cursor 자체 모델만)·Premium 월 $30(Plus의 4배 사용량, Claude·GPT 같은 외부 모델은 API 정가로 따로 결제)·Super 월 $100·Ultra 월 $200 중에서 고릅니다. 개편 전에 가입한 Hobby·Pro($20) 이용자는 기존 요금제를 유지합니다(Cursor 요금 페이지·도움말 기준, 2026-11-06).

3. .cursorrules — 프로젝트 규칙을 AI에게 학습시키기 — 요약

3. 프로젝트 규칙(.cursor/rules) — 프로젝트 규칙을 AI에게 알려주기

프로젝트 규칙(Rules)은 Cursor의 핵심 기능 중 하나입니다. 공식 문서(2026-10-06)는 .cursor/rules 폴더의 .mdc 파일(Project Rules), 모든 프로젝트에 적용되는 User Rules, 팀 규칙(Team Rules), 프로젝트 루트의 AGENTS.md를 안내하며, 예전에 쓰던 .cursorrules는 더 이상 안내되지 않습니다. 규칙은 모델이 학습하는 것이 아니라 프롬프트 맨 앞에 포함되는 지시문입니다.

예시: Python/FastAPI 프로젝트 (.cursor/rules/python-fastapi.mdc)

---
alwaysApply: true
---
You are an expert in Python, FastAPI, and PostgreSQL.

- Always use type hints
- Use async/await for database operations
- Follow PEP 8 strictly
- Prefer dependency injection over global state
- Write docstrings in Google style
- Error handling: use custom exception classes, not bare except

이 파일이 있으면 Agent가 코드를 만들 때 이 규칙을 참고합니다. 예를 들어 async를 쓰도록, 타입 힌트를 붙이도록 유도할 수 있습니다(규칙은 지시문이라 100% 강제되지는 않습니다).

꿀팁: 프로젝트 구조 설명 추가

.cursor/rules 또는 AGENTS.md에 프로젝트 구조를 설명해 주면 더 좋습니다:

# 프로젝트 구조
이 프로젝트는 모놀리스 구조입니다.
src/ 아래에 모듈별로 디렉토리가 나뉘어 있습니다.
공통 유틸리티는 src/shared/에 있습니다.
테스트는 tests/ 디렉토리에 있습니다.

이렇게 적어두면 Agent가 새 파일을 어디에 만들어야 할지 참고합니다. 팀 단위로 쓸 때는 .cursor/rules를 Git에 커밋해서(Project Rules는 버전 관리됩니다), 팀원 전체가 같은 코딩 규칙을 Agent에게 전달할 수 있습니다. 조직 차원의 규칙은 Team 플랜의 Team Rules로도 관리합니다.

4. Agent (Ctrl+I) — 자연어로 멀티 파일 수정

Cursor의 핵심 기능은 Agent입니다. Ctrl+I(macOS는 Cmd+I)를 누르면 사이드 패널에 Agent가 열립니다(공식 문서). 예전에 Composer라고 부르던 자리이며, 지금 Composer는 Cursor 자체 모델 이름(Composer 2.5)으로도 쓰입니다. 자연어로 여러 파일을 동시에 수정할 수 있습니다.

실전 예시

Agent에 다음과 같이 입력합니다:

“사용자 프로필에 avatar URL 필드를 추가해줘. DB 모델, API 엔드포인트, 프론트엔드 컴포넌트 전부 수정해.”

이렇게 입력하면 Agent가 관련 파일을 찾아 여러 개를 수정하고 변경사항을 보여줍니다. 검토한 뒤 적용하거나, 잘못되면 체크포인트로 되돌릴 수 있습니다(공식 문서의 Checkpoints).

자동완성 중심으로 쓰면 모델 파일, API 파일, 프론트엔드 파일을 각각 열고 수정하는 세 번의 작업이 필요합니다. Agent는 이를 한 번의 지시로 처리합니다. Copilot의 Agent 모드를 쓰면 비슷하게 할 수 있습니다.

주의사항

Agent가 여러 파일을 수정하니까, 변경사항을 꼭 Git diff로 확인하세요. AI가 만들었다고 무조건 맞는 것이 아닙니다. 특히 기존 비즈니스 로직을 건드릴 때는 한 줄 한 줄 검토해야 합니다. Agent는 강력한 도구이지만, 최종 결정은 개발자가 내려야 합니다.

5. @ Mentions과 Chat

Cursor의 채팅 기능에서 @ 기호를 쓰면 다양한 것을 참조할 수 있습니다:

명령	기능	활용 예시
`@파일명`	특정 파일의 내용 참조	현재 작업 중인 파일의 의존성 확인
`@폴더명`	폴더 내 모든 파일 참조	모듈 전체 구조 파악
`@Chats`	이전 대화 내용 참조	앞서 논의한 설계 이어가기
`@Commit`, `@Branch`	Git 변경분(작업 중 변경, 메인과의 차이) 참조	리뷰·커밋 메시지 작성
`@Terminals`	터미널 출력 참조	에러 메시지 원인 분석

실전 팁: 에러 디버깅

에러가 발생했을 때 에러 메시지를 그대로 복사해서 채팅창에 붙여넣고 @Terminals를 참조하면, Cursor가 터미널 출력을 읽고 원인을 분석해 줍니다. 스택 트레이스의 어떤 라인이 문제인지, 어떤 파일의 어떤 함수에서 발생했는지 추적하고 수정 방법을 제안합니다.

6. 실전 워크플로우 — 3가지 핵심 패턴

패턴 1: 새 기능 개발

설계 논의: 채팅창에 “이 기능을 추가하려고 하는데, 어떤 파일들을 수정해야 할까?”라고 물어봅니다. Cursor가 프로젝트 구조를 분석해서 관련 파일 목록을 제시합니다.
Agent 작성: 설계가 확정되면 Agent로 실제 코드를 작성합니다. 여러 파일을 한 번에 수정합니다.
코드 리뷰: 채팅창에서 “방금 수정한 코드에서 보안 문제가 있을까?”라고 물어봅니다. SQL 인젝션, XSS, 인증 누락 등을 점검합니다.

패턴 2: 리팩토링

거대한 함수를 선택하고 Command+K(macOS) / Ctrl+K(Windows)로 인라인 편집을 시작합니다. “이 함수를 3개의 작은 함수로 분리해줘”라고 하면, 즉시 제안이 나옵니다. 단일 책임 원칙을 적용한 분리 방식을 제안하고, 각 함수의 역할을 주석으로 설명해 줍니다.

패턴 3: 테스트 작성

함수를 선택하고 “이 함수에 대한 단위 테스트를 pytest로 만들어줘”라고 합니다. 정상 케이스뿐 아니라 엣지 케이스(빈 입력, 경계값, 예외 상황)까지 자동으로 고려해 줍니다. 테스트 커버리지를 높이는 데 효과적입니다.

이 세 가지 워크플로우만 익숙해져도, 개발 속도가 확연히 올라갑니다.

요약: Cursor AI 시작 가이드

Cursor는 자동완성을 넘어, 코드베이스를 검색하고 여러 파일을 동시에 수정하는 에이전트형 도구입니다. 핵심은 세 가지입니다:

.cursor/rules로 프로젝트 규칙을 알려 주고
Agent로 멀티 파일 편집을 하고
@ mentions으로 파일·터미널·Git 변경분을 참조

처음이시라면 무료 플랜으로 시작해서 .cursor/rules와 Command+K 인라인 편집부터 연습해 보세요. 익숙해지면 Agent로 멀티 파일 수정을 시도하고, 마지막으로 @ mentions으로 터미널·Git 변경분 참조까지 확장하면 됩니다.

더 읽어보기

Cursor 공식 홈페이지 — 다운로드 및 최신 기능 확인
Cursor 공식 문서 — Rules, Agent, 모델 상세 가이드
Anthropic Claude — Cursor에서 사용하는 주력 AI 모델

이 채널에서 매주 AI 개발 도구 실전 가이드를 다루고 있습니다. 구독과 알림 설정 부탁드립니다.

자주 묻는 질문 (FAQ)

Q1. Copilot과 가장 큰 차이가 뭔가요?

작업 방식입니다. Cursor의 Agent는 코드베이스를 검색해 관련 파일을 읽고 여러 파일을 수정하며, Copilot도 Agent 모드를 제공하므로 기능 차이는 예전보다 줄었습니다. 또 하나의 차이는 에디터를 바꾸느냐(Cursor, VS Code 포크) 기존 VS Code에 얹느냐(Copilot)입니다.

Q2. 프로젝트 규칙(.cursor/rules)에는 뭘 적어야 하나요?

프로젝트에서 지켜야 할 코딩 규칙(타입 힌트 필수, async/await 사용, 예외 처리 방식 등)과 프로젝트 구조 설명을 적습니다. 구조를 적어두면 Agent가 새 파일을 어디에 만들어야 할지 참고합니다.

Q3. 팀에서 같이 쓰려면요?

.cursor/rules를 Git에 커밋하세요(Project Rules는 버전 관리됩니다). 팀원 전체가 같은 코딩 규칙을 Agent에게 전달할 수 있고, Team·Enterprise 플랜은 대시보드에서 Team Rules를 관리합니다.

Q4. 어떤 모델을 기본으로 두는 게 좋나요?

공식 문서는 간단한 수정과 반복 작업에는 빠른 모델을, 복잡한 추론과 여러 파일 리팩토링에는 성능이 높은 모델을 권합니다. Cursor Settings > Models 에서 기본 모델을 지정하고 작업 중에도 바꿀 수 있습니다.