3년 묵은 리액트 프로젝트 리팩토링하다가 코파일럿을 버린 사연
최근 사내에서 3년이나 방치된 레거시 리액트(React) 프로젝트를 최신 Next.js로 마이그레이션하는 업무를 맡았습니다. 기존에 쓰던 GitHub Copilot에 돈을 내고 있었지만, 이 녀석은 현재 열려있는 파일 하나만 보고 코드를 뱉어낼 뿐, 수십 개의 컴포넌트가 얽힌 전체 폴더 구조를 전혀 이해하지 못했습니다. 결국 컴포넌트 하나를 옮기는 데만 3시간 넘게 삽질을 했죠. “프로젝트 전체 맥락을 이해하는 AI는 없을까?”라며 해외 포럼을 뒤지다 VS Code를 하드 포크(Fork)해서 만들었다는 ‘Cursor(커서) AI’를 발견했습니다. 속는 셈 치고 설치한 첫날, 제 3시간짜리 삽질을 단 10분 만에 해결해 버리는 것을 보고 충격을 받았습니다. 기존 VS Code와의 차이점부터 실무에 즉시 투입하기 위한 최적화 세팅까지, 제 피눈물 나는 마이그레이션 경험을 바탕으로 Cursor AI 완벽 정복 가이드를 공유합니다.
목차
- 1. 내 손가락을 쉬게 해줄 새로운 에디터 구동 환경 지표
- 2. 실전 가이드: Cursor 설치부터 VS Code와의 결정적 차이 활용법까지
- 3. 에디터 이주 중 직접 맞닥뜨린 치명적 오류 2가지와 탈출구
- 4. Cursor 도입 후 뼈저리게 체감한 코딩 속도와 수치 변화
- 5. 핵심 3줄 요약 및 여러분의 퇴근을 앞당겨 줄 최종 추천
1. 내 손가락을 쉬게 해줄 새로운 에디터 구동 환경 지표
Cursor는 별도의 확장 프로그램이 아니라 에디터 프로그램 자체를 통째로 교체하는 방식입니다. 하지만 VS Code의 코어 엔진을 그대로 사용하기 때문에, 기존에 쓰던 단축키와 확장 프로그램들을 단 1초 만에 100% 그대로 옮겨올 수 있습니다. 제가 이 녀석을 쾌적하게 굴리고 있는 실무 환경은 다음과 같습니다.
- 운영체제: macOS Sonoma (M2 칩셋) 및 Windows 11 Pro (크로스 플랫폼 완벽 지원)
- 사용 툴: Cursor IDE (공식 홈페이지에서 다운로드한 최신 버전)
- 구독 플랜: Pro 플랜 (월 20달러. 처음 가입 시 주어지는 14일 무료 트라이얼로 테스트를 진행했습니다.)
- 비교 대상: 기존에 사용하던 VS Code + GitHub Copilot 조합
- 주력 테스트 언어: TypeScript, React, Python
2. 실전 가이드: Cursor 설치부터 VS Code와의 결정적 차이 활용법까지
설치는 허무할 정도로 쉽습니다. Cursor 공식 홈페이지(https://www.google.com/search?q=cursor.com)에서 설치 파일을 받아 실행하면 끝입니다. 하지만 이 에디터가 VS Code와 어떻게 다른지, 그 맹점을 파악해야 진짜 뽕을 뽑을 수 있습니다.
1단계: 클릭 한 번으로 기존 VS Code 영혼까지 끌어오기
Cursor를 처음 실행하면 “Import Extensions and Settings from VS Code”라는 마법의 버튼이 나타납니다. 이 버튼을 누르면 기존 VS Code에 깔아두었던 테마, 단축키, Prettier, ESLint 같은 확장 프로그램들이 토씨 하나 틀리지 않고 그대로 복사됩니다. 새로운 에디터에 적응해야 한다는 심리적 장벽이 이 버튼 하나로 완전히 무너집니다.
2단계: VS Code 코파일럿과 Cursor의 결정적 차이 파악하기
VS Code에서 쓰던 Copilot은 주로 내가 타자를 칠 때 다음 줄을 회색 글씨로 보여주는 ‘자동 완성’ 위주였습니다. 하지만 Cursor는 코드를 ‘직접 수정(Inline Edit)’하고 ‘프로젝트 전체를 훑는(Codebase)’ 능력이 핵심입니다.
| 기능 비교 | VS Code + Copilot | Cursor AI |
|---|---|---|
| 단축키 및 주 기능 | 주로 Tab 키 (수동적인 자동완성) | Cmd+K (직접 코드 생성/수정), Cmd+L (채팅) |
| 멀티 파일 인식 | 현재 열린 탭에 크게 의존함 | @Codebase 로 전체 프로젝트 구조 파악 가능 |
| 에러 해결 방식 | 에러 복사 후 챗봇에 붙여넣기 | 터미널 에러 옆 ‘Add to Chat’ 클릭 한 번에 디버깅 |
3단계: Cmd+K 와 @Files 를 활용한 실무 리팩토링 실습 (전체 코드)
이제 기존 방식과 완전히 다른 Cursor만의 실무 코딩을 시연해 보겠습니다. auth.ts 파일에 있는 레거시 로그인 로직을 Zustand를 활용한 상태 관리 코드로 변경하는 상황을 가정해 보겠습니다. 해당 파일에서 코드를 드래그한 뒤, Cmd+K (윈도우는 Ctrl+K)를 누르면 코드 바로 위에 조그만 프롬프트 입력창이 뜹니다. 여기에 단순히 “이거 Zustand로 바꿔줘”라고 치는 것이 아니라, 명확한 맥락(Context)을 주입해야 합니다.
// 기존 레거시 auth.ts 코드 (드래그하여 선택)
let currentUser = null;
function login(user) {
currentUser = user;
}
/* 💡 프롬프트 입력창(Cmd+K)에 아래와 같이 입력합니다:
"이 코드를 Zustand 스토어로 마이그레이션 할 거야.
@store/userStore.ts 파일의 컨벤션을 참고해서 작성해주고,
타입스크립트 인터페이스를 명확히 선언해줘."
*/
// Cursor가 @store/userStore.ts 를 훑어보고 실시간으로 타이핑(Diff)해 준 결과:
import { create } from 'zustand';
interface User {
id: string;
name: string;
email: string;
}
interface AuthState {
currentUser: User | null;
login: (user: User) => void;
logout: () => void;
}
export const useAuthStore = create<AuthState>((set) => ({
currentUser: null,
login: (user) => set({ currentUser: user }),
logout: () => set({ currentUser: null }),
}));
코드가 완성되면 기존 코드(빨간색)와 새 코드(초록색)가 겹쳐서 Diff 형태로 보입니다. 마음에 들면 Cmd+Enter (Accept)를 눌러 즉시 반영합니다. 복사해서 붙여넣는 과정조차 생략되는 이 경험은 정말 경이롭습니다.
💡 여기서 주의할 점: .cursorignore 파일 세팅의 중요성
Cursor의 @Codebase 기능은 프로젝트 폴더 전체를 훑어서 AI에게 힌트를 줍니다. 하지만 node_modules나 build, .env 같은 방대한 라이브러리 파일이나 민감한 보안 키까지 AI가 읽어버리면, 토큰 제한에 걸리거나 엉뚱한 라이브러리 내부 코드를 수정하려 드는 대참사가 일어납니다. 반드시 프로젝트 루트 폴더에 .cursorignore 파일을 만들고, gitignore처럼 불필요한 폴더들을 명시해 두어야 AI가 핵심 소스코드에만 집중하여 속도와 정확도를 유지할 수 있습니다.
3. 에디터 이주 중 직접 맞닥뜨린 치명적 오류 2가지와 탈출구
“기존 VS Code랑 똑같네!” 하고 신나서 세팅하다가, 예상치 못한 벽에 부딪혀 오후 업무를 통째로 날릴 뻔했던 두 가지 장애물을 공유합니다.
첫 번째 멘붕: Python 가상환경(venv) 인식 증발 현상
VS Code의 세팅을 완벽히 불러왔다고 믿고 파이썬 프로젝트를 열었는데, 모든 import 문에 빨간 줄이 그어지며 ModuleNotFoundError가 터졌습니다. Cursor가 VS Code의 껍데기는 가져왔지만, 폴더 내부에 숨겨져 있던 파이썬 로컬 가상환경(.venv) 경로 매핑값은 잃어버린 것이었습니다. 당황하지 않고 Cmd + Shift + P를 눌러 커맨드 팔레트를 켠 뒤, Python: Select Interpreter를 검색해 내 프로젝트 안의 .venv/Scripts/python.exe 경로를 수동으로 다시 지정해 주니 그제야 빨간 줄이 씻은 듯이 사라졌습니다.
두 번째 위기: 터미널 명령어(Command Line) code . 먹통 현상
저는 평소 터미널에서 특정 폴더를 열 때 code . 명령어를 습관적으로 사용했습니다. 그런데 Cursor를 깔고 나니 이 명령어가 여전히 구버전 VS Code를 실행시켜 버렸습니다. 두 에디터가 충돌한 것이죠. 이를 해결하기 위해 기존 VS Code를 완전히 삭제하거나, Cursor 안에서 Cmd + Shift + P를 누르고 Install 'cursor' command in PATH를 실행했습니다. 이후부터는 터미널에서 cursor . 이라고 입력해야 Cursor 에디터로 해당 폴더가 짠 하고 열리게끔 완전히 환경을 분리하여 충돌 문제를 완벽히 해결했습니다.
4. Cursor 도입 후 뼈저리게 체감한 코딩 속도와 수치 변화
20달러라는 결제 금액이 전혀 아깝지 않을 정도로, 제 한 달간의 업무 지표는 비약적으로 상승했습니다.
- 개발 및 리팩토링 시간 70% 단축: 10개의 파일에 흩어져 있는 변수명을 바꾸고 인터페이스를 수정하는 작업은 기존에 수동으로 1시간이 넘게 걸렸습니다. 하지만 Cursor 채팅창에
@Codebase 전체 파일에서 기존 User 모델을 NewUser 모델 기준으로 업데이트해줘라고 치면, 단 3분 만에 수정이 필요한 모든 파일의 Diff를 띄워줍니다. - 에러 트러블슈팅 속도: 터미널에 시뻘건 빌드 에러가 났을 때 구글링하던 시간 하루 평균 40분이 0분으로 증발했습니다. 에러 로그 옆의 ‘Add to Chat’ 버튼을 누르면, Cursor가 내 코드를 이미 다 알고 있는 상태에서 “아, 34번째 줄에서 타입 캐스팅이 잘못됐네요. 이렇게 고치세요”라며 정답 코드를 즉시 꽂아주기 때문입니다.
- 초기 보일러플레이트 세팅: 새로운 토이 프로젝트를 팔 때,
Cmd+K로 “Next.js 14 버전에 TailwindCSS 적용해서 기본 랜딩 페이지 뼈대 잡아줘” 한 줄이면 단 10초 만에 완벽한 초기 세팅 코드가 쏟아져 나옵니다.
5. 핵심 3줄 요약 및 여러분의 퇴근을 앞당겨 줄 최종 추천
제 피눈물 나는 에디터 마이그레이션 경험을 세 줄로 요약해 드립니다.
- Cursor는 VS Code의 확장 프로그램이 아니라 에디터 자체이며, 기존 세팅과 확장 프로그램을 1초 만에 100% 복사해 올 수 있습니다.
- 단순 자동완성을 넘어
Cmd+K와@Codebase를 활용해 프로젝트 전체 맥락을 짚어주는 인라인 코드 수정(Diff)이 핵심 무기입니다. .cursorignore파일로 AI가 읽지 말아야 할 무거운 폴더나 환경 변수를 반드시 차단해야 환각(Hallucination) 에러를 막을 수 있습니다.
이 에디터는 기존 레거시 코드를 대대적으로 리팩토링해야 하는 프론트엔드/백엔드 개발자, 남이 짠 코드를 인수인계받아 폴더 구조 파악에 애를 먹는 실무자, 그리고 저처럼 복사-붙여넣기 노동에 지쳐 관절이 아픈 모든 코더분들께 제 경험을 걸고 강력하게 추천합니다. 첫 14일 무료 트라이얼만 써보셔도 절대 VS Code로 돌아갈 수 없을 것입니다. 반면, 코딩의 기초 원리와 문법을 처음부터 한 땀 한 땀 공부해야 하는 쌩초보 입문자라면, AI가 너무 많은 것을 순식간에 짜버리기 때문에 본인의 진짜 실력을 기르기 어려울 수 있으니 당분간은 기본 에디터 사용을 권합니다.