설치는 개발의 시작이 아니라 마찰 제거다
새로운 개발 도구를 설치할 때 가장 위험한 순간은 다운로드가 끝난 뒤가 아닙니다. 첫 실행 후 10분입니다. 화면은 익숙한데 설정이 미묘하게 다르고, 확장은 일부만 동작하고, 터미널은 열리는데 프로젝트 명령은 실패하고, AI는 대답하지만 내 코드베이스를 제대로 아는지 확신이 없습니다. 이 상태에서 바로 큰 기능을 맡기면 Cursor가 좋은 도구인지 나쁜 도구인지 판단하기도 전에 불안감부터 생깁니다.
이 장의 목표는 단순합니다. Cursor를 설치하고, 기존 VS Code 환경을 옮기고, 실제 프로젝트 폴더를 열어 첫 30분 안에 "이제 여기서 일해도 되겠다"는 상태를 만드는 것입니다. 아직 거대한 리팩터링을 하지 않습니다. 아직 결제 기능을 만들지도 않습니다. 오늘은 Cursor와 내 개발 환경 사이의 배관이 제대로 연결되어 있는지 확인하는 날입니다.
Cursor 3.0 이후의 핵심은 에이전트이지만, 에이전트가 잘 일하려면 먼저 작업장이 정리되어 있어야 합니다. Git이 연결되어 있고, 터미널 명령이 실행되고, 패키지 매니저가 인식되고, 코드베이스 인덱싱이 끝나고, AI가 어디까지 코드를 볼 수 있는지 결정되어 있어야 합니다. 설치는 그래서 의외로 전략적인 작업입니다. 한 번만 제대로 해두면 이후의 모든 위임이 편해집니다.
공식 다운로드 페이지에서 시작하기
Cursor는 공식 다운로드 페이지에서 macOS, Windows, Linux용 설치 파일을 제공합니다.1 검색엔진에서 아무 링크나 눌러 받기보다, 반드시 공식 사이트에서 시작하는 습관을 들이세요. AI 코드 에디터는 단순한 메모장이 아닙니다. 여러분의 소스코드, 터미널, Git 정보와 연결됩니다. 설치 파일의 출처를 확인하는 것은 귀찮은 보안 절차가 아니라 제품을 지키는 첫 번째 습관입니다.
macOS 사용자는 보통 다운로드 페이지에서 자신의 칩에 맞는 파일을 선택합니다. 최근 맥북이라면 대부분 Apple Silicon, 즉 M1, M2, M3, M4 계열입니다. 오래된 인텔 맥이라면 Intel 버전을 선택합니다. 잘 모르겠다면 macOS의 "이 Mac에 관하여"에서 칩 정보를 확인하면 됩니다. Universal 빌드가 제공될 때는 두 아키텍처를 모두 지원하므로 선택이 어렵지 않지만, 용량과 최적화를 생각하면 자신의 칩에 맞는 버전을 고르는 편이 깔끔합니다. 설치는 일반적인 맥 앱과 같습니다. .dmg 파일을 열고 Cursor를 Applications 폴더로 끌어다 놓으면 됩니다.
Windows 사용자는 설치 파일 선택에서 두 가지를 자주 만납니다. User Installer와 System Installer입니다. 개인 노트북에서 혼자 쓴다면 대개 User Installer가 편합니다. 관리자 권한 없이 현재 사용자 계정에 설치되기 때문입니다. 회사 공용 장비나 여러 사용자가 같은 PC에서 Cursor를 써야 한다면 System Installer가 적합할 수 있습니다. 일반적인 솔로 메이커라면 "내 계정에 설치되는 기본 설치 파일"을 고르면 충분합니다.
Linux 사용자는 배포판에 따라 AppImage나 패키지 파일을 사용합니다. AppImage를 받았다면 실행 권한을 부여한 뒤 실행합니다. 예를 들어 터미널에서 다음처럼 처리할 수 있습니다.
chmod +x Cursor-*.AppImage
./Cursor-*.AppImageLinux에서는 데스크톱 통합, 파일 연결, 터미널에서 cursor .로 여는 설정이 배포판마다 조금 다를 수 있습니다. 처음에는 완벽한 통합보다 "프로젝트 폴더를 열고 터미널이 실행되는지"부터 확인하는 편이 좋습니다.
업데이트가 꼬였을 때 복구하는 순서
Cursor는 빠르게 업데이트되는 도구입니다. 새 기능이 자주 들어오는 만큼, 가끔 자동 업데이트가 꼬이거나 설치 후 실행이 이상해질 수 있습니다. 이때 무작정 설정 폴더를 지우기보다 순서대로 확인해야 합니다.
먼저 현재 버전을 확인합니다. Cursor를 열 수 있다면 메뉴의 Help 또는 About Cursor에서 버전을 봅니다. 업데이트가 필요한지 확인할 때는 설정이나 메뉴에서 업데이트 확인 기능을 사용합니다. 일반적인 업데이트 문제 해결 절차는 "업데이트 확인 → 다운로드 → 재시작 → 버전 확인" 순서로 진행하는 것이 가장 안전합니다.2
자동 업데이트가 실패하면 수동 재설치를 합니다. 이때 중요한 것은 기존 앱을 완전히 종료하는 것입니다. 창만 닫는 것이 아니라 프로세스가 남아 있지 않은지 확인합니다. macOS에서는 Cursor를 종료한 뒤 새 .dmg로 Applications 폴더의 앱을 덮어씁니다. Windows에서는 실행 중인 Cursor를 모두 닫고 새 설치 파일을 실행합니다. 그래도 실패하면 재부팅 후 다시 설치합니다. 단순하지만, 잠긴 파일 때문에 설치가 실패하는 경우에는 이 방법이 가장 빠릅니다.
업데이트 직후에는 바로 큰 작업을 시작하지 말고 세 가지를 확인하세요. Cursor가 정상 실행되는지, 기존 설정과 확장이 유지되는지, 프로젝트 하나를 열었을 때 터미널과 Git 표시가 정상인지입니다. 업데이트 후 확장이 깨졌다면 전체 환경을 의심하기보다 해당 확장을 비활성화하거나 재설치해 봅니다.
버전을 되돌려야 할 때도 있습니다. 특정 확장이 새 버전과 충돌하거나, 팀 프로젝트에서 같은 버전을 맞춰야 할 수 있습니다. 이런 경우에도 원칙은 같습니다. 공식 배포 경로를 우선하고, 다운로드 출처와 파일 무결성을 확인합니다. 특히 솔로 메이커는 "빨리 고치려고 아무 설치 파일이나 받는 습관"을 피해야 합니다. 개발 도구가 오염되면 제품 전체가 위험해질 수 있습니다.
VS Code에서 이사하기: 전부 옮기되, 전부 믿지는 않는다
Cursor는 VS Code 코드베이스를 바탕으로 만들어졌습니다. 그래서 기존 VS Code 사용자는 낯선 IDE를 새로 배우는 느낌보다, 익숙한 작업실에 AI 기능이 깊게 붙은 느낌을 받게 됩니다. Cursor 공식 문서도 VS Code 설정을 Cursor로 쉽게 이전할 수 있다고 안내합니다.3
첫 실행 시 Cursor는 보통 VS Code 설정 가져오기를 제안합니다. 여기서 가져올 수 있는 것은 테마, 확장, 키바인딩, 사용자 설정, 스니펫 등입니다. 이 기능 덕분에 폰트 크기, 탭 간격, Prettier 설정, 익숙한 단축키를 처음부터 다시 맞출 필요가 없습니다. 솔로 메이커에게 이건 꽤 중요합니다. 도구를 바꿨다는 이유로 손의 리듬까지 바뀌면 며칠 동안 생산성이 떨어집니다.
하지만 "가져오기"를 "완전 복제"로 착각하면 안 됩니다. Cursor는 VS Code 기반이지만 Cursor입니다. 모든 확장이 같은 방식으로 동작한다고 보장할 수는 없습니다. 특히 Microsoft 전용 API에 깊게 의존하는 일부 확장, 원격 개발 환경에 설치된 확장, 특정 언어 서버 확장은 차이가 날 수 있습니다. 그래서 마이그레이션은 한 번에 끝내는 이벤트가 아니라, 핵심 확장부터 검증하는 과정으로 보는 편이 안전합니다.
추천하는 순서는 이렇습니다.
먼저 테마, 키바인딩, 기본 사용자 설정을 가져와 손의 감각을 맞춥니다.
그다음 현재 프로젝트에 꼭 필요한 언어 확장, 포매터, 린터, 테스트 관련 확장만 확인합니다.
마지막으로 생산성 보조 확장, 아이콘 테마, Git 보조 도구처럼 없어도 당장 개발이 멈추지 않는 확장을 점검합니다.
예를 들어 TypeScript와 React 프로젝트라면 ESLint, Prettier, Tailwind CSS IntelliSense, 테스트 러너 관련 확장부터 봅니다. Python 프로젝트라면 Python 언어 서버, 포매터, 가상환경 인식이 먼저입니다. Flutter 프로젝트라면 Dart와 Flutter 확장이 핵심입니다. 아이콘 테마가 깨지는 것은 불편하지만 개발을 막지는 않습니다. 반면 포매터나 언어 서버가 깨지면 AI가 만든 변경을 검증하기 어려워집니다.
만약 첫 실행 때 가져오기를 건너뛰었다면 나중에 Cursor Settings에서 VS Code 설정 가져오기를 다시 실행할 수 있습니다. Cursor 설정은 톱니바퀴 아이콘, Cmd/Ctrl + Shift + J, 또는 명령 팔레트에서 Cursor Settings를 검색해 열 수 있습니다.4
첫 실행 후 반드시 정해야 할 것들
Cursor를 처음 열면 로그인부터 하게 됩니다. GitHub, Google, 이메일 계정 등으로 로그인할 수 있습니다. 로그인은 AI 기능 사용량, 요금제, 모델 접근 권한과 연결됩니다. 로그인하지 않은 상태에서도 에디터처럼 보일 수는 있지만, Cursor의 핵심 기능을 쓰려면 계정 연결이 필요합니다.
로그인 후에는 요금제와 사용량을 확인합니다. 중요한 것은 "무료냐 유료냐"보다 "내가 지금 어떤 한도 안에서 일하고 있는지"를 아는 것입니다. AI 요청에는 종류가 있습니다. Tab 자동완성처럼 자주 발생하는 요청도 있고, Agent나 고급 모델 호출처럼 비용이 큰 요청도 있습니다. 아무 생각 없이 큰 작업을 여러 번 던지면 사용량이 빠르게 줄어들 수 있습니다. 처음 며칠은 설정의 Account 또는 Billing 관련 화면에서 사용량이 어떻게 줄어드는지 관찰하세요.
그다음 Privacy Mode를 확인합니다. 이 설정은 "AI 기능을 어디까지 쓰고, 무엇을 외부로 보낼 것인가"에 대한 결정입니다. 개인 사이드 프로젝트라면 비교적 넓게 허용해도 괜찮을 수 있습니다. 하지만 고객 데이터, 회사 코드, 비공개 알고리즘, 보안 관련 로직이 포함된 저장소라면 시작 전에 반드시 정책을 정해야 합니다. AI 코딩 도구를 쓰는 순간부터 개발자는 코드 작성자이면서 데이터 반출 관리자이기도 합니다.
여기서 너무 겁먹을 필요는 없습니다. 핵심은 명확성입니다. 어떤 프로젝트는 AI가 코드베이스를 넓게 참고해도 되고, 어떤 프로젝트는 특정 파일이나 디렉터리를 제외해야 하며, 어떤 프로젝트는 민감한 정보가 포함된 .env, 키 파일, 고객 데이터 샘플을 절대 컨텍스트에 넣지 않아야 합니다. Cursor를 쓰기 전에 .gitignore를 점검하듯, AI에게 보여주면 안 되는 파일도 점검해야 합니다.
모델 선택도 초기에 확인합니다. Cursor에서는 작업 유형에 따라 여러 모델을 선택할 수 있습니다. 빠른 질문에는 가벼운 모델이 충분하고, 복잡한 설계나 멀티파일 수정에는 더 강한 모델이 필요할 수 있습니다. 처음부터 "가장 비싼 모델만 쓰자"로 시작하지 마세요. 작은 질문, 코드 설명, 국소 수정은 기본 모델로 충분한지 확인하고, 설계 판단이나 까다로운 버그 분석에 더 강한 모델을 쓰는 식으로 감각을 잡는 편이 좋습니다.
프로젝트 폴더를 열고 개발 환경을 연결하기
이제 실제 프로젝트를 엽니다. 새 예제 프로젝트보다 이미 여러분이 운영 중이거나 곧 만들 제품의 코드베이스가 좋습니다. Cursor의 진짜 가치는 일반적인 코드 조각을 만드는 데서 나오지 않습니다. 내 코드베이스의 패턴, 파일 구조, 타입, 테스트 방식, Git 히스토리와 만날 때 드러납니다.
프로젝트 폴더를 연 뒤 가장 먼저 볼 것은 코드베이스 인덱싱 상태입니다. 인덱싱은 Cursor가 프로젝트를 검색하고 이해하기 위한 준비 작업입니다. 쉽게 말해 "AI가 내 프로젝트의 지도를 만드는 과정"입니다. 작은 프로젝트는 금방 끝나지만, 파일이 많은 프로젝트는 시간이 걸릴 수 있습니다. 인덱싱 중에는 AI 응답이 덜 정확하거나, 특정 파일을 못 찾는 것처럼 보일 수 있습니다. 처음 몇 분은 조급해하지 말고 상태 표시줄이나 관련 패널에서 진행 상황을 확인합니다.
대형 프로젝트라면 불필요한 디렉터리를 제외하는 습관이 필요합니다. node_modules, dist, build, .next, coverage, 대용량 generated 파일은 AI에게 좋은 컨텍스트가 아닙니다. 사람이 읽지 않는 파일을 AI에게 많이 보여줘도 똑똑해지지 않습니다. 오히려 잡음이 늘어납니다. 이후 장에서 컨텍스트 관리를 더 깊게 다루겠지만, 설치 직후에도 "생성물과 의존성 폴더는 되도록 제외한다"는 원칙은 기억해 두세요.
다음은 터미널입니다. Cursor의 통합 터미널을 열고 평소 프로젝트를 실행할 때 쓰는 명령을 입력합니다.
npm install
npm run dev
npm test물론 프로젝트에 따라 pnpm, yarn, bun, uv, poetry, cargo, go, flutter 같은 명령을 쓸 수 있습니다. 중요한 것은 Cursor가 여러분의 런타임과 패키지 매니저를 제대로 만나는지 확인하는 것입니다. VS Code에서는 되는데 Cursor 터미널에서는 안 된다면 PATH, 셸 설정, Node 버전 매니저, Python 가상환경, WSL 연결 등을 확인해야 합니다.
Git 상태도 확인합니다. 왼쪽 Source Control 패널에 현재 브랜치와 변경 사항이 보이는지 봅니다. 터미널에서 다음 명령도 실행해 봅니다.
git status
git branch --show-currentCursor와 AI를 함께 쓸 때 Git은 안전벨트입니다. 변경 전 상태를 알고 있어야 되돌릴 수 있습니다. 설치 직후부터 "수정하기 전에 git status를 본다"는 습관을 들이면 이후 Agent가 여러 파일을 고칠 때 훨씬 침착해집니다.
첫 30분 루틴: 네 가지 핵심 조작을 몸으로 익히기
이제 본격적으로 Cursor를 만져볼 차례입니다. 목표는 멋진 기능을 완성하는 것이 아닙니다. Tab, Cmd+K, Chat, Agent라는 네 가지 조작 흐름을 한 번씩 경험하는 것입니다. Cursor 3.0의 큰 변화는 에이전트 중심이지만, 실제 손의 움직임은 여전히 이 네 가지에서 시작합니다.
처음 5분은 Tab 자동완성입니다. 작은 파일 하나를 엽니다. 테스트 파일, 유틸 함수, UI 컴포넌트처럼 맥락이 분명한 파일이 좋습니다. 함수 이름이나 JSX 구조를 조금 쓰고 잠시 멈춰 보세요. 회색 글씨로 제안이 나타나면 Tab으로 받아들입니다. 마음에 들지 않으면 무시하거나 계속 타이핑합니다. 여기서 배울 것은 "AI 제안은 명령이 아니라 제안"이라는 감각입니다. 좋은 제안은 받아들이고, 애매한 제안은 지나갑니다.
다음 5분은 Cmd+K입니다. Windows와 Linux에서는 보통 Ctrl+K 흐름으로 이해하면 됩니다. 작은 코드 블록을 선택하고 인라인 수정 요청을 해봅니다.
이 함수에 입력값이 비어 있을 때의 처리를 추가해 주세요. 기존 스타일을 유지하세요.또는 UI 코드에서 이렇게 요청할 수 있습니다.
이 버튼 문구를 더 명확하게 바꾸고, 로딩 상태일 때 disabled 처리도 추가해 주세요.Cmd+K의 핵심은 "여기만 고친다"입니다. Agent처럼 프로젝트 전체를 돌아다니게 하지 말고, 선택한 범위 안에서 작은 수정을 맡깁니다. 제안된 diff를 보고 받아들일지 결정하세요. 이 과정에서 Cursor가 어느 정도의 수정은 잘하고, 어느 순간부터 범위를 넘어서려 하는지 감이 생깁니다.
다음 10분은 Chat입니다. Chat은 코드를 바로 바꾸기보다 이해하고 질문하는 공간입니다. 다음과 같은 질문을 해보세요.
@codebase 이 프로젝트에서 사용자 인증 흐름이 어디에서 시작되는지 찾아 설명해 주세요. 코드는 수정하지 마세요.또는 특정 파일을 열고 이렇게 묻습니다.
이 파일의 역할을 단계별로 설명해 주세요. 특히 외부 API를 호출하는 부분과 에러 처리 흐름을 구분해서 알려 주세요.처음부터 "고쳐줘"가 아니라 "설명해줘"로 시작하는 이유가 있습니다. Cursor가 내 코드베이스를 얼마나 잘 찾고 이해하는지 확인할 수 있기 때문입니다. 설명이 엉뚱하다면 아직 인덱싱이 덜 되었거나, 컨텍스트가 부족하거나, 질문이 너무 넓을 수 있습니다.
마지막 10분은 Agent입니다. 단, 아주 제한된 작업만 맡깁니다. 예를 들어 다음 정도가 좋습니다.
목표: README의 개발 실행 명령이 현재 package.json과 맞는지 확인해 주세요.
범위: README.md와 package.json만 확인하세요.
작업: 먼저 차이를 설명하고, 필요한 경우 README만 수정하세요.
완료 조건: 변경 후 git diff 요약을 알려 주세요.또는 테스트가 있는 프로젝트라면 이렇게 시킬 수 있습니다.
목표: 실패하는 테스트가 있는지 확인합니다.
범위: 코드는 수정하지 말고 테스트 명령만 실행하세요.
작업: package.json에서 테스트 명령을 찾고 실행하세요.
완료 조건: 성공/실패 결과와 실패 시 첫 번째 원인 후보만 요약하세요.이런 작은 Agent 작업은 안전합니다. 수정 범위가 좁고, 실패해도 되돌리기 쉽고, Agent가 터미널과 파일을 어떻게 다루는지 볼 수 있습니다. Cursor 3.0에서는 Agents Window를 통해 여러 에이전트 실행을 관리할 수 있고, 명령 팔레트에서 Agents Window를 열어 에이전트 중심 인터페이스로 전환할 수 있습니다.5 하지만 첫날에는 여러 에이전트를 동시에 돌리기보다 하나의 작은 실행을 끝까지 관찰하는 편이 낫습니다.
첫날에는 대규모 리팩터링을 하지 않는다
설치가 끝나고 AI가 그럴듯하게 움직이면 마음이 급해집니다. 오래 미뤄둔 리팩터링을 맡기고 싶어집니다. "이참에 폴더 구조 정리해 줘", "전체 타입 에러 다 고쳐 줘", "클래스 컴포넌트를 전부 함수형으로 바꿔 줘" 같은 요청이 떠오릅니다. 하지만 첫날에는 참는 것이 좋습니다.
설치 직후에 해야 할 가장 좋은 실험은 "테스트 실행 → 작은 수정 → Git diff 확인 → 되돌리기"입니다. 이 루틴은 Cursor가 내 코드베이스에서 안전하게 작동하는지 확인하는 최소 검증입니다.
먼저 테스트나 타입 체크를 실행합니다.
npm run test
npm run typecheck
npm run lint프로젝트에 맞는 명령을 쓰면 됩니다. 여기서 이미 실패한다면 Cursor 문제가 아닙니다. 현재 프로젝트의 기준 상태가 실패인 것입니다. 그 사실을 알고 시작해야 합니다. 기준 상태를 모르면 AI가 만든 문제가 무엇인지 구분할 수 없습니다.
그다음 아주 작은 수정을 합니다. 버튼 문구 하나, 에러 메시지 하나, README 명령 하나, 테스트 케이스 하나가 좋습니다. AI에게 맡겨도 되고 직접 고쳐도 됩니다. 중요한 것은 수정 후 git diff를 보는 것입니다.
git diffCursor의 Source Control 패널에서도 변경 파일과 diff를 확인합니다. 의도한 파일만 바뀌었는지, 불필요한 포매팅이 대량으로 들어가지 않았는지, AI가 관련 없는 코드를 건드리지 않았는지 봅니다.
마지막으로 되돌리기를 해봅니다. Source Control에서 discard를 사용하거나 터미널에서 특정 파일을 되돌릴 수 있습니다.
git checkout -- path/to/file최근 Git에서는 다음 명령을 쓸 수도 있습니다.
git restore path/to/file이 루틴을 한 번 해보면 마음이 편해집니다. "잘못되면 되돌릴 수 있다"는 감각이 생기기 때문입니다. AI 도구를 무서워하지 않으려면, AI를 완전히 믿는 것이 아니라 되돌릴 수 있는 작업 습관을 가져야 합니다.
설치 직후 체크리스트
마지막으로 오늘의 셋업을 점검해 봅시다. 아래 항목에 모두 "예"라고 답할 수 있으면 Cursor는 실제 작업 가능한 상태에 들어온 것입니다.
공식 다운로드 페이지에서 내 운영체제와 칩에 맞는 설치 파일로 설치했다.
VS Code의 테마, 키바인딩, 핵심 확장을 가져왔고, 프로젝트에 꼭 필요한 확장을 우선 검증했다.
로그인, 요금제와 사용량, Privacy Mode, 기본 모델 설정을 확인했다.
기존 프로젝트 폴더를 열고 인덱싱 상태, 터미널, Git 브랜치와 변경 사항 표시를 확인했다.
Tab 자동완성, Cmd/Ctrl+K 인라인 수정, Chat 질문, 제한된 Agent 작업을 각각 한 번씩 실행했다.
테스트 또는 타입 체크를 실행하고, 작은 수정 후 Git diff를 확인하고, 되돌리기까지 해봤다.
이 체크리스트의 목적은 완벽한 설정이 아닙니다. "내가 Cursor를 통제하고 있다"는 감각을 만드는 것입니다. Cursor는 강력하지만, 강력한 도구일수록 시작 의식이 필요합니다. 브라우저 하나 열고 대충 프롬프트를 던지는 방식과, 프로젝트 상태를 확인하고 범위를 정한 뒤 작업을 맡기는 방식은 결과가 다릅니다.
이제 여러분의 Cursor는 설치된 앱이 아니라 작업 가능한 개발 환경입니다. 다음 장에서는 이 환경 안에서 무엇을 어디서 실행할지 더 선명하게 보기 위해 인터페이스 지도를 그려 보겠습니다. Tab은 언제 쓰고, Cmd+K는 어디에 적합하며, Agent와 Agents Window는 어떻게 다른지 하나씩 손에 익힐 차례입니다.
참고
2How to Update Cursor to the Latest Version
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.