트러블슈팅: 자주 만나는 오류와 해결법

문제가 생겼을 때의 기본 원칙

Cursor를 쓰다 보면 어느 날 갑자기 모든 것이 느려진 것처럼 느껴질 때가 있다. 어제까지는 Tab이 다음 코드를 척척 제안했는데 오늘은 조용하다. Agent는 같은 파일을 계속 고치다 되돌리고, MCP 서버는 연결된 것처럼 보이는데 도구가 나타나지 않는다. 사용량 페이지를 열어보니 생각보다 많은 크레딧이 사라져 있다.

이럴 때 가장 위험한 행동은 바로 검색창을 열고, 보이는 해결책을 닥치는 대로 따라 하는 것이다. 특히 AI 개발 도구의 문제는 원인이 하나처럼 보여도 실제로는 인덱싱, 네트워크, 권한, 규칙, 컨텍스트, 비용 설정이 얽혀 있는 경우가 많다. 그러므로 트러블슈팅은 "고치는 일"이 아니라 "좁혀 가는 일"이다.

이 부록의 목표는 명확하다. 문제가 생겼을 때 검색에 빠지지 않고, 원인별 체크리스트를 따라 빠르게 복구하는 것이다. Cursor는 Agent, Rules, MCP, Skills, Cloud Agents처럼 여러 기능이 연결된 작업 환경이므로, 공식 문서에서도 Agent와 Rules, MCP, Skills를 별도의 핵심 구성요소로 다룬다.¹ 기능이 강력해진 만큼 고장도 여러 층에서 난다. 그래서 우리는 증상보다 먼저 층을 나눈다.

대부분의 문제는 다음 순서로 확인하면 된다.

• 앱 상태: Cursor 재시작, 업데이트, 캐시, 확장 충돌

• 프로젝트 상태: 인덱싱, 제외 파일, 저장되지 않은 변경, Git 상태

• AI 상태: 모델, 사용량 한도, 네트워크, 인증, Privacy Mode

• 지시 상태: Rules, Skills, 대화 컨텍스트, Plan Mode

• 외부 연결 상태: MCP 서버, 토큰, 권한, 실행 명령, 방화벽

중요한 것은 한 번에 하나씩 바꾸는 것이다. .cursorignore를 수정하고, 캐시를 지우고, Rules를 고치고, MCP 설정까지 동시에 바꾸면 무엇이 문제였는지 알 수 없다. 솔로 메이커에게 가장 비싼 비용은 월 구독료가 아니라 "원인을 모르는 상태로 다시 같은 문제를 만나는 시간"이다.

0단계: 5분 안에 끝내는 응급 처치

Cursor가 이상해졌다면 먼저 깊게 파지 말고 가장 값싼 조치부터 한다. 실제로 많은 문제는 임시 상태, 오래된 캐시, 서버 장애, 네트워크 지연에서 시작된다. Cursor 커뮤니티 트러블슈팅 자료에서도 문제 재현 단계, 시스템 정보, VPN 여부, 개발자 도구 콘솔, 로그를 기본 확인 항목으로 제시한다.²

첫 번째는 완전 종료 후 재시작이다. 창의 닫기 버튼만 누르지 말고 앱을 완전히 종료한다. macOS라면 Cmd+Q, Windows라면 트레이에 남은 Cursor 프로세스까지 종료한 뒤 다시 연다. Agent가 중간에 물고 있던 상태, 멈춘 터미널, 깨진 임시 세션이 이 단계에서 풀리는 경우가 많다.

두 번째는 서비스 장애 확인이다. Chat, Agent, 로그인, 모델 호출이 전부 실패한다면 내 프로젝트 문제가 아닐 수 있다. 특히 인덱싱이 0%에서 멈추고 로그에 timeout이나 서버 연결 실패가 반복된다면, 로컬 설정을 과하게 뜯기 전에 Cursor 쪽 상태나 커뮤니티 이슈를 확인한다. 실제로 일부 인덱싱 장애는 로컬 문제가 아니라 서버 측 업데이트 문제로 발생했고, 롤백 후 정상화된 사례가 보고되었다.³

세 번째는 업데이트 확인이다. Cursor 3는 에이전트를 중심으로 워크스페이스와 로컬·클라우드 Agent 전환 경험을 크게 바꾼 버전이다.⁴ 이런 큰 변화 이후에는 특정 버전에서만 생기는 버그가 있을 수 있다. 반대로 업데이트 직후 문제가 시작됐다면, 릴리스 노트나 커뮤니티에서 동일 증상이 보고되었는지 확인한다.

네 번째는 로그를 본다. 추측을 멈추고 증거를 보는 단계다. 명령 팔레트에서 Developer: Open Logs Folder를 실행하거나, View 또는 Terminal의 Output 패널에서 Cursor 관련 로그를 확인한다. 인덱싱 문제라면 Cursor Indexing 또는 Indexing & Retrieval류의 출력이 단서가 된다.²

응급 처치 후에도 문제가 남아 있다면 이제 증상별로 들어간다.

Cursor가 코드를 제안하지 않거나 너무 느릴 때

Tab 자동완성이 조용해졌거나, @codebase가 엉뚱한 파일을 찾거나, Agent가 "이 프로젝트 구조를 모르는 사람"처럼 행동한다면 가장 먼저 의심할 것은 인덱싱이다. Cursor의 코드베이스 이해는 프로젝트 파일을 읽고 검색 가능한 형태로 준비하는 과정에 크게 의존한다. 이 과정이 깨지면 AI는 현재 열린 파일과 대화에 들어온 일부 정보만 붙잡고 답하게 된다.

빠른 진단표

인덱싱 문제의 흔한 원인은 불필요하게 큰 폴더가 포함되는 것이다. node_modules, .git, dist, build, .next, 로그 파일, 생성된 번들 파일은 AI가 이해해야 할 "제품의 의도"가 아니라 결과물 또는 외부 의존성이다. 이런 파일까지 읽으려 하면 인덱싱은 느려지고, 검색 결과도 지저분해진다. 여러 인덱싱 트러블슈팅 자료가 .cursorignore를 통한 범위 축소와 재동기화를 첫 단계로 권장한다.⁵

프로젝트 루트에 다음 파일을 만든다.

# .cursorignore

# dependencies
node_modules/
vendor/
.venv/
venv/

# git and build outputs
.git/
dist/
build/
.next/
out/
target/

# generated or noisy files
*.log
*.tmp
*.map
*.min.js
*.min.css
*.bundle.js

# large data and media
*.csv
*.sql
*.sqlite
*.parquet
*.json.gz
*.png
*.jpg
*.gif
*.mp4
*.woff2

이후 Cursor를 재시작하거나 명령 팔레트에서 Cursor: Resync Index를 실행한다. 설정 화면의 Codebase Indexing 영역에 Resync Index, Delete Index, Compute Index 같은 버튼이 보인다면 순서대로 재동기화부터 시도한다. 삭제는 재동기화가 실패할 때만 사용한다. 삭제 후에는 프로젝트를 처음 여는 것처럼 다시 인덱싱하므로 시간이 걸릴 수 있다.

모노레포는 루트가 아니라 작업 단위로 연다

솔로 메이커라고 해서 프로젝트가 작다는 뜻은 아니다. 웹, API, 모바일, 관리자, 패키지, 문서가 한 저장소에 들어 있는 모노레포라면 Cursor가 루트 전체를 읽으려다 버벅일 수 있다. 이때는 저장소 루트를 여는 대신 지금 작업하는 하위 폴더만 연다.

cursor apps/web
# 또는
cursor packages/api

전체 루트를 꼭 열어야 한다면 .cursorignore에서 당장 작업하지 않는 패키지를 제외한다.

# .cursorignore
apps/admin/
apps/mobile/
packages/legacy-*/
docs/archive/

이 방식은 단순히 성능을 위한 꼼수가 아니다. AI에게 "지금 중요한 세계"를 좁혀 주는 일이다. 사람이 책 한 권을 읽을 때도 목차가 필요하듯, Agent에게도 적절한 범위가 필요하다.

캐시와 로컬 인덱스를 지울 때

재동기화로도 해결되지 않으면 캐시를 의심한다. 캐시는 성능을 높이기 위해 만들어진 임시 데이터지만, 비정상 종료나 업데이트 충돌 후 깨질 수 있다. 캐시를 지우기 전에는 Cursor를 완전히 종료한다.

운영체제별로 자주 확인하는 위치는 다음과 같다. 버전에 따라 경로가 달라질 수 있으므로, 가능하면 Cursor의 Developer: Open Logs Folder 또는 설정 화면에서 열린 경로를 기준으로 삼는다.

# macOS 예시
~/Library/Application Support/Cursor/Cache/
~/Library/Application Support/Cursor/CachedData/

# Linux 예시
~/.config/Cursor/Cache/
~/.config/Cursor/CachedData/

# Windows 예시
%APPDATA%CursorCache
%APPDATA%CursorCachedData

일부 인덱싱 자료는 Windows에서 %LOCALAPPDATA%CursorUserglobalStoragecursor-storage 같은 로컬 저장소 삭제를 안내하기도 한다.⁶ 다만 무작정 전체 설정 폴더를 삭제하지 말고, 먼저 백업을 만든다. Cursor 설정, 로그인 상태, 확장 데이터가 함께 들어 있을 수 있기 때문이다.

Rules를 바꿨는데 반영되지 않을 때

Rules 문제는 묘하다. 파일은 분명히 고쳤는데 Agent는 여전히 예전 습관대로 코드를 쓴다. pages/를 쓰지 말라고 했는데 Next.js App Router 프로젝트에서 pages/api를 만들고, Tailwind를 쓰라고 했는데 인라인 스타일을 넣는다. 이때는 "AI가 말을 안 듣는다"고 생각하기 쉽지만, 실제로는 Rules가 로드되지 않았거나, 로드되었지만 적용 조건에 걸리지 않았거나, 너무 많은 규칙 속에서 묻힌 경우가 많다.

Cursor의 Rules는 프로젝트 안의 .cursor/rules/에 두는 방식이 일반적이며, 규칙 파일은 적용 조건을 가질 수 있다. 핵심은 "항상 적용할 규칙"과 "특정 파일에서만 적용할 규칙"을 분리하는 것이다.

체크 1: 새 대화에서 확인한다

Rules를 수정한 뒤 기존 Agent 대화에서 바로 테스트하면 반영되지 않은 것처럼 보일 수 있다. 긴 대화에는 이미 이전 지시, 이전 코드, 이전 판단이 컨텍스트로 들어가 있다. Rules를 바꿨다면 먼저 새 대화를 열고 간단히 묻는다.

현재 프로젝트에 적용되는 Cursor Rules를 기준으로,
React 컴포넌트를 만들 때 따라야 할 규칙을 요약해줘.

Agent가 새 규칙을 요약하지 못한다면 로드 문제다. 요약은 하는데 구현에서 어긴다면 규칙의 구체성 문제다.

체크 2: glob이 실제 파일과 맞는지 본다

가장 흔한 실수는 globs가 실제 파일 경로와 맞지 않는 것이다.

---
description: React 컴포넌트 작성 규칙
globs: "**/*.tsx"
alwaysApply: false
---

- 컴포넌트는 함수형 컴포넌트로 작성한다.
- props는 interface로 선언한다.
- 스타일은 Tailwind CSS 유틸리티 클래스를 우선 사용한다.

이 규칙은 .tsx 파일에는 잘 붙지만, .jsx, .ts, app/api//*.ts에는 붙지 않는다. 백엔드 규칙을 프론트엔드 glob에 넣으면 Agent가 모른다. 테스트 규칙을 /*.test.ts로만 두면 **/*.spec.ts에는 적용되지 않는다.

규칙이 안 먹는다고 느껴질 때는 "내가 지금 수정하는 파일이 이 glob에 걸리는가?"를 먼저 확인한다.

체크 3: alwaysApply를 남용하지 않는다

alwaysApply: true는 강력하지만 공짜가 아니다. 항상 적용되는 규칙은 모든 대화의 컨텍스트를 차지한다. 프로젝트 철학, 명령어, 보안 원칙처럼 정말 항상 필요한 것만 남긴다. 프론트엔드, 백엔드, 테스트, DB, 디자인 시스템 규칙은 가급적 glob 기반으로 나눈다.

좋은 구성은 다음에 가깝다.

.cursor/rules/
├── core.mdc              # 항상 적용: 프로젝트 개요, 금지사항, 필수 명령
├── frontend.mdc          # /*.tsx, /*.jsx
├── backend.mdc           # app/api//*.ts, server//*.ts
├── testing.mdc           # /*.test.*, /*.spec.*
└── database.mdc          # db/, migrations/

체크 4: description을 "AI가 고를 수 있는 말"로 쓴다

description은 사람을 위한 제목이기도 하지만, Agent가 어떤 규칙을 참고해야 할지 판단하는 힌트이기도 하다. "규칙", "개발", "중요"처럼 추상적인 설명보다 "Next.js App Router API route conventions", "Vitest unit test style", "Supabase migration rules"처럼 작업 맥락이 드러나는 설명이 좋다.

나쁜 예시는 다음과 같다.

---
description: 중요 규칙
globs: "**/*"
alwaysApply: false
---

좋은 예시는 다음과 같다.

---
description: Next.js App Router에서 서버 컴포넌트와 API route를 작성할 때 따르는 규칙
globs: "app//*.ts,app//*.tsx"
alwaysApply: false
---

Rules는 많이 쓰는 것이 목적이 아니다. Agent가 같은 실수를 반복할 때, 그 실수 하나를 줄이기 위해 추가하는 안전장치다. 규칙 파일이 길어질수록 AI가 더 똑똑해지는 것이 아니라, 오히려 중요한 지시가 흐려질 수 있다.

Agent가 같은 실수를 반복할 때

Agent가 꼬이는 순간에는 특유의 냄새가 난다. 이미 고친 파일을 다시 되돌린다. 테스트 실패 원인을 보지 않고 같은 패치를 반복한다. 사용자에게 확인하지 않고 가정을 쌓는다. "이번에는 됐습니다"라고 말하지만 실제로는 같은 에러가 난다.

이때 더 자세한 지시를 같은 대화에 계속 붙이는 것은 대개 효과가 낮다. 긴 대화는 작업 기억이 아니라 잡음 창고가 되기 쉽다. Agent 운영에서 중요한 원칙은 "한 작업 단위가 끝나면 끊고, 꼬이면 계획으로 돌아간다"이다. Plan Mode를 먼저 쓰고, 결과가 마음에 들지 않으면 변경을 되돌린 뒤 계획을 다듬어 다시 실행하는 방식이 긴 대화 안에서 땜질하는 것보다 안정적이라는 조언도 여러 실전 가이드에서 반복된다.⁷

Agent 복구 절차

Agent가 반복 실수를 시작했다면 다음 순서로 멈춘다.

• 변경 중단: Agent 실행을 멈추고 터미널 명령도 더 이상 허용하지 않는다.

• 현재 상태 확인: git diff, 테스트 결과, 에러 로그를 확인한다.

• 안전한 지점 확보: 쓸 만한 변경이 있으면 커밋하거나 패치로 저장하고, 아니면 되돌린다.

• 새 대화 시작: 기존 대화에서 이어가지 않는다.

• Plan Mode로 전환: "구현하지 말고 원인 분석과 계획만 작성하라"고 지시한다.

• 성공 기준 명시: 어떤 테스트, 어떤 화면, 어떤 로그가 통과해야 완료인지 적는다.

실전 프롬프트는 이렇게 쓸 수 있다.

이전 시도에서 Agent가 같은 수정을 반복하며 실패했다.
지금은 코드를 수정하지 말고 Plan Mode로만 작업해줘.

목표:
- 결제 완료 후 주문 상태가 paid로 바뀌지 않는 문제의 원인을 찾는다.

반드시 할 일:
- 관련 파일을 먼저 찾고, 데이터 흐름을 설명한다.
- 가능한 원인을 3개 이하로 좁힌다.
- 각 원인을 확인할 명령 또는 로그 위치를 제안한다.
- 구현 단계는 파일 경로 단위로 작성한다.

금지:
- 아직 파일을 수정하지 않는다.
- 테스트를 고치지 않는다.
- 임시로 에러를 숨기지 않는다.

Agent가 산만해졌을 때는 "더 열심히 해줘"가 아니라 "작업을 다시 작게 나눠라"가 답이다. 하나의 Agent 세션이 기능 설계, DB 마이그레이션, UI 구현, 테스트 수정, 배포 스크립트 변경까지 한 번에 잡으면 실패 확률이 높아진다. 솔로 메이커의 장점은 회의가 없다는 것이지만, 그렇다고 작업 단위를 무한히 크게 잡아도 된다는 뜻은 아니다.

MCP 연결이 실패할 때

MCP는 Cursor를 외부 세계와 연결하는 문이다. GitHub, Figma, Notion, Supabase, PostgreSQL, Playwright 같은 도구를 Agent가 직접 읽거나 실행할 수 있게 한다. 하지만 바로 그 이유 때문에 문제가 생기면 원인도 다양하다. JSON 설정이 틀렸을 수도 있고, Node.js가 없을 수도 있고, 토큰이 만료됐을 수도 있고, 회사 네트워크가 막았을 수도 있고, Cursor가 보안상 명령 실행을 차단했을 수도 있다.

MCP 설정은 보통 프로젝트 단위 .cursor/mcp.json 또는 전역 ~/.cursor/mcp.json에 둔다. Cursor의 MCP 설정 화면에서 서버 상태와 노출된 도구를 확인할 수 있으며, stdio 방식은 Cursor가 로컬 명령을 실행해 서버를 띄우고, 원격 방식은 HTTP 엔드포인트에 연결한다.⁸

빠른 진단표

가장 먼저 볼 것은 JSON 구조다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

mcpServers 루트 키가 빠지면 Cursor가 설정을 읽지 못한다. 쉼표 하나가 잘못되어도 전체 파일이 무시될 수 있다. 서버 이름을 바꿨다면 Agent에게 보이는 도구 이름도 달라질 수 있으므로, 설정 화면에서 실제 로드된 이름을 확인한다.

다음은 명령을 터미널에서 직접 실행하는 것이다. MCP 서버가 "Cursor 안에서만" 실패한다고 느껴져도 실제로는 로컬 환경에서 실행 자체가 안 되는 경우가 많다.

npx -y @modelcontextprotocol/server-github

여기서 패키지 없음, 권한 없음, Node.js 없음, 환경변수 없음 같은 에러가 드러난다. 특히 npx를 쓸 때 -y가 없으면 패키지 설치 확인을 기다리며 멈출 수 있다. Cursor가 띄운 백그라운드 프로세스에는 사용자가 y를 입력할 창이 없기 때문에 "무한 로딩"처럼 보인다.

토큰 만료와 권한 오류

MCP 연결이 되지만 특정 작업에서 실패한다면 인증과 권한을 본다. GitHub MCP가 issue는 읽는데 PR 생성은 못 한다면 토큰 scope가 부족할 수 있다. Notion MCP가 페이지를 못 읽는다면 해당 integration이 데이터베이스에 초대되지 않았을 수 있다. Supabase나 PostgreSQL MCP가 쿼리를 못 날린다면 네트워크 접근 또는 DB 권한 문제일 수 있다.

이때 원칙은 최소 권한이다. 데이터베이스 MCP는 가능하면 읽기 전용으로 시작한다. 프로덕션 DB를 바로 연결하지 않는다. 개인 토큰을 전역 설정에 넣기보다 프로젝트별 설정에 두고, 저장소에 커밋되지 않도록 주의한다. MCP 서버는 결국 내 권한으로 실행되는 프로그램이다. MCP 보안 가이드들은 자동 실행을 줄이고, 승인 프롬프트를 유지하며, 데이터베이스나 외부 서비스 권한을 최소화하라고 강조한다.⁸

실행 차단과 승인 프롬프트

Agent가 MCP 도구를 써야 하는데 "권한이 없어 실행할 수 없다"거나 매번 멈춘다면, Cursor의 도구 승인 설정을 확인한다. 단, 모든 도구를 자동 승인으로 풀어버리는 것은 권장하지 않는다. Playwright로 브라우저를 여는 것과 프로덕션 DB에 쓰기 쿼리를 날리는 것은 위험도가 다르다.

솔로 메이커에게 추천하는 설정은 다음과 같다.

• 읽기 도구는 비교적 낮은 마찰로 허용한다.

• 쓰기 도구는 승인 프롬프트를 유지한다.

• 결제, 사용자 데이터, 운영 DB 관련 도구는 자동 실행하지 않는다.

• 프로젝트별 MCP를 우선 사용하고, 전역 MCP는 꼭 필요한 것만 둔다.

• 사용하지 않는 MCP 서버는 꺼 둔다.

MCP는 연결되었을 때 엄청난 생산성을 주지만, 잘못 연결되었을 때도 엄청난 속도로 사고를 낼 수 있다. "안 되는 MCP"보다 위험한 것은 "너무 쉽게 되는 MCP"다.

설치와 실행 문제

Cursor 설치 자체가 꼬인 경우는 비교적 단순하게 접근한다. 먼저 운영체제 요구사항을 확인한다. Windows는 64비트 환경, macOS는 지원 버전, Linux는 배포판과 AppImage 실행 권한을 확인한다. 설치 후 실행이 안 되면 보안 소프트웨어, Gatekeeper, 실행 권한, 회사 장비의 앱 차단 정책을 의심한다.

VS Code 확장이 이상할 때

Cursor는 VS Code 기반이지만 VS Code 그 자체는 아니다. 많은 확장이 그대로 동작하지만, 일부 확장은 Cursor 환경에서 별도 설치가 필요하거나 충돌을 일으킬 수 있다. Cursor가 저장할 때마다 멈추거나 특정 언어 서버가 CPU를 과도하게 쓴다면 확장을 모두 끄고 하나씩 켜 본다.

확장 충돌을 찾는 절차는 단순하다. 모든 비필수 확장을 비활성화하고, 문제가 사라지는지 본다. 사라졌다면 하나씩 다시 켠다. 다시 느려지는 순간 마지막으로 켠 확장이 범인일 가능성이 높다. 이 작업은 지루하지만 가장 확실하다.

로그인과 인증 문제

로그인이 풀리거나 AI 기능만 실패한다면 계정 인증을 확인한다. 브라우저에서 Cursor 계정에 로그인되는지, 회사 VPN이나 프록시가 인증 흐름을 막는지, 결제 상태에 문제가 없는지 본다. 모델 호출만 실패한다면 모델 제공자나 Cursor 서비스 장애일 수도 있다.

비공식 구독 판매, 체험판 리셋 도구, 기기 식별자 변경 스크립트는 사용하지 않는 것이 좋다. 이런 도구는 계정 정지나 보안 문제를 만들 수 있고, 일부는 시스템 식별자나 레지스트리를 수정한다. 비용 문제는 우회가 아니라 사용량 관리와 공식 플랜 확인으로 풀어야 한다.

비용이 예상보다 빨리 늘어날 때

비용 문제는 버그처럼 보이지만 대부분 사용 패턴의 문제다. Cursor의 개인 플랜은 Hobby, Pro, Pro+, Ultra처럼 제공 범위가 다르며, Pro는 월 $20, Pro+는 월 $60, Ultra는 월 $200로 안내된다. 각 플랜은 Agent 한도, 모델 접근, MCP·Skills·Hooks, Cloud Agent 사용량 등에서 차이가 있다.⁹

비용이 빠르게 늘어나는 대표 원인은 다음과 같다.

• 긴 Agent 대화에서 같은 작업을 반복한다.

• 큰 파일이나 불필요한 폴더를 계속 컨텍스트에 넣는다.

• 고비용 모델을 모든 작업에 사용한다.

• Cloud Agents, Automations, Bugbot이 예상보다 자주 실행된다.

• MCP 도구가 많은 데이터를 읽어 와 컨텍스트를 키운다.

• 실패한 테스트 루프를 제한 없이 반복하게 둔다.

Cursor의 최근 업데이트에는 관리자용 모델 제어, 지출 관리, 사용량 분석, 소프트·하드 한도, 제품 영역별 사용량 필터링 같은 기능이 포함되어 있다.¹⁰ 개인 사용자라도 같은 사고방식을 적용할 수 있다. "무엇이 돈을 쓰는지"를 나눠 보는 것이다. Tab인지, Agent인지, Cloud Agent인지, Automation인지, Bugbot인지 분리해서 본다.

비용 절감 체크리스트

첫째, 작업 시작 전에 모델을 고른다. 간단한 리팩토링, 타입 수정, 테스트 이름 변경에 최고급 모델을 쓸 필요는 없다. 반대로 아키텍처 변경이나 복잡한 버그 분석에는 좋은 모델을 쓰는 편이 오히려 싸다. 낮은 품질의 답을 여러 번 반복하는 것이 한 번의 정확한 답보다 비쌀 수 있다.

둘째, 한 대화에 모든 일을 넣지 않는다. 긴 대화는 비용과 품질을 동시에 악화시킨다. 기능 하나, 버그 하나, 리팩토링 하나를 단위로 세션을 나눈다.

셋째, @codebase를 남발하지 않는다. 전체 검색이 필요할 때는 좋지만, 파일을 알고 있다면 @file이나 @folder가 더 낫다. "결제 API를 고쳐줘"보다 "@app/api/payments/route.ts와 @lib/stripe.ts를 기준으로 고쳐줘"가 싸고 정확하다.

넷째, 반복 루프에 제한을 둔다. "테스트가 통과할 때까지 계속해"라고 시키더라도 최대 반복 횟수와 중단 조건을 적는다.

테스트를 실행하고 실패하면 수정해줘.
단, 최대 3회까지만 반복해.
3회 후에도 실패하면 더 수정하지 말고,
실패 원인과 다음 선택지를 요약해줘.

다섯째, 자동화는 알림과 함께 켠다. Automations, Bugbot, Cloud Agents는 훌륭하지만, 켜 두고 잊으면 비용을 만든다. 솔로 메이커에게 자동화는 "내가 잠든 동안 일하는 직원"이지만, 직원에게 업무 범위와 예산을 알려주지 않으면 안 된다.

자주 만나는 에러별 해결법

"Cursor가 내 코드를 모르는 것 같아요"

먼저 인덱싱 상태를 본다. 완료되지 않았다면 기다린다. 대형 프로젝트의 첫 인덱싱은 시간이 걸릴 수 있다. 완료됐는데도 이상하면 .cursorignore를 정리하고 Resync Index를 실행한다. 특정 파일만 못 찾는다면 .gitignore, .cursorignore, .cursorindexingignore에 제외되어 있는지 확인한다.

그다음 프롬프트에서 파일을 명시한다.

@src/lib/auth.ts @src/app/api/login/route.ts
이 두 파일을 기준으로 로그인 흐름을 설명해줘.

AI가 전체 프로젝트를 "알아서" 찾을 수 있다고 해도, 내가 아는 핵심 파일을 알려주는 편이 빠르고 정확하다.

"Rules를 만들었는데 계속 무시해요"

새 대화에서 테스트한다. glob을 확인한다. alwaysApply가 꺼져 있다면 해당 파일 패턴에서만 적용되는지 본다. description이 너무 추상적이면 구체화한다. 규칙이 너무 길면 핵심만 남긴다.

그리고 규칙에는 금지보다 기준을 쓴다. "이상한 코드 쓰지 마"는 규칙이 아니다. "API route는 app/api/**/route.ts에 만들고, 응답은 NextResponse.json()을 사용한다"가 규칙이다.

"Agent가 계속 같은 버그를 못 고쳐요"

즉시 멈춘다. 기존 대화에서 더 설득하지 않는다. 변경을 확인하고, 필요하면 되돌린다. 새 대화에서 Plan Mode로 원인 분석만 시킨다. 테스트 실패 로그를 붙이고, "코드 수정 금지"를 명시한다. 계획을 검토한 뒤 구현을 시작한다.

반복 실패는 모델의 성의 문제가 아니라 피드백 구조의 문제일 때가 많다. Agent에게는 명확한 관찰값과 성공 기준이 필요하다.

"MCP 서버가 연결됐는데 도구가 안 보여요"

mcp.json에 mcpServers가 있는지 확인한다. 설정 파일 위치가 프로젝트용인지 전역용인지 본다. command와 args를 그대로 터미널에서 실행한다. npx라면 -y를 넣는다. Node.js나 Python이 PATH에 잡혀 있는지 확인한다. 토큰이 필요한 서버라면 환경변수가 실제로 전달되는지 본다.

도구가 너무 많다면 일부가 보이지 않을 수 있으므로 사용하지 않는 서버와 도구를 끈다. MCP는 많이 연결할수록 좋은 것이 아니라, 지금 작업에 필요한 도구만 선명하게 연결할수록 좋다.

"비용이 갑자기 늘었어요"

먼저 사용량 페이지에서 어떤 영역이 많이 썼는지 본다. Agent인지 Cloud Agent인지 Automations인지 나눠 본다. 최근에 켠 자동화, Bugbot, 장시간 Agent 세션이 있는지 확인한다. 모델을 Auto 또는 고급 모델로 고정해 놓고 단순 작업까지 처리하고 있지 않은지 본다.

그다음 작업 방식을 바꾼다. 긴 대화를 끊고, 파일을 명시하고, 반복 횟수를 제한하고, 자동화에는 예산과 중단 조건을 둔다.

로그를 읽는 최소한의 방법

로그는 겁먹을 필요가 없다. 모든 줄을 이해하려고 하지 말고, 세 가지 단어를 찾는다.

• error: 실제 실패 지점일 가능성이 높다.

• timeout: 네트워크, 서버, 긴 작업, 방화벽 문제일 수 있다.

• permission 또는 unauthorized: 토큰, 권한, 인증 문제일 수 있다.

인덱싱 로그에 timeout이 반복되면 네트워크나 서버 상태를 의심한다. MCP 로그에 command not found가 나오면 Node.js, Python, Docker 같은 실행 환경 문제다. 401이나 403은 인증 또는 권한 문제다. ENOENT는 파일이나 명령을 찾지 못했다는 뜻인 경우가 많다.

지원 요청을 해야 한다면 다음 정보를 준비한다.

• 문제가 보이는 화면 캡처

• 재현 단계

• Cursor 버전과 운영체제

• VPN, 프록시, 회사 보안 도구 사용 여부

• 관련 로그 일부

• 문제가 생기기 직전에 바꾼 설정, 확장, Rules, MCP

이 정도만 정리해도 "안 돼요"에서 "이 조건에서 이 에러가 납니다"로 바뀐다. 후자는 해결 가능한 문제다.

마지막 복구 카드: 깨끗한 작업 공간 만들기

모든 것을 해도 이상하면 새 작업 공간을 만든다. 이것은 패배가 아니라 격리 실험이다.

새 폴더에 저장소를 다시 클론한다. Cursor를 열기 전에 .cursorignore를 먼저 준비한다. 확장은 최소만 켠다. Rules는 core.mdc 하나만 둔다. MCP는 전부 끈다. 이 상태에서 인덱싱과 Tab, Agent가 정상인지 본다.

정상이라면 원래 환경의 확장, Rules, MCP, 캐시 중 하나가 문제다. 하나씩 다시 추가한다. 비정상이라면 프로젝트 자체, 네트워크, 계정, Cursor 버전 문제일 가능성이 크다.

이 방법은 시간이 걸리는 것처럼 보이지만, 사실 가장 빠른 길일 때가 많다. 복잡한 환경에서 원인을 찾는 것보다, 깨끗한 환경에서 하나씩 더하는 편이 훨씬 선명하다.

솔로 메이커를 위한 트러블슈팅 습관

트러블슈팅은 문제가 생긴 날만 하는 일이 아니다. 좋은 작업 시스템은 문제가 커지기 전에 작은 신호를 남긴다.

작업 전에는 커밋한다. Agent에게 큰 변경을 맡기기 전에 git status를 확인하고, 안전한 체크포인트를 만든다. 작업 중에는 계획을 남긴다. .cursor/plans/에 계획을 저장하면 같은 문제를 다시 시작할 때 훨씬 빠르다. 작업 후에는 실패 원인을 짧게 기록한다. docs/troubleshooting.md나 HISTORY.md에 "MCP GitHub 토큰 scope 부족으로 PR 생성 실패"처럼 한 줄만 남겨도 다음번 시간을 아낀다.

Cursor를 잘 쓴다는 것은 문제가 전혀 없는 상태를 뜻하지 않는다. 오히려 문제가 생겼을 때 빠르게 멈추고, 좁히고, 되돌리고, 다시 맡길 수 있는 상태를 뜻한다. Agent 시대의 생산성은 "AI가 한 번에 맞히는 능력"보다 "틀렸을 때 안전하게 다시 시도하는 시스템"에서 나온다.

마지막으로 기억하자. Cursor가 느려졌다면 먼저 인덱스를 본다. Rules가 안 먹는다면 새 대화와 glob을 본다. Agent가 산만해졌다면 세션을 끊고 Plan Mode로 돌아간다. MCP가 안 된다면 JSON과 명령 실행, 토큰과 권한을 순서대로 본다. 비용이 늘었다면 사용량의 출처를 나누고 반복을 제한한다.

이 다섯 가지만 지켜도 대부분의 문제는 검색창을 열기 전에 해결된다.

참고

¹Cursor Docs — Agent, Rules, MCP, Skills & CLI

²Troubleshooting Guide | Cursor Cursor.fan

³Why My Cursor IDE Indexing Was Stuck at 0% and How the Devs Fixed It

⁴새로운 Cursor를 만나보세요

⁵Cursor Indexing Issues - AI Agent skill

⁶커서(Cursor) AI 에디터 Indexing Status Error 해결법

⁷Working with Cursor: Rules, Commands, MCP servers, Modes, Hooks, Skills

⁸MCP Servers in Cursor: Setup, Configuration, and Security (2026 Guide)

⁹Cursor 요금제

¹⁰Cursor의 새로운 소식 — 최신 업데이트와 릴리스 노트