Cursor Agent 모드 활용법: 3개월 동안 익힌 10가지 팁

화면에는 Agent가 방금 만든 다섯 번째 잘못된 파일이 떠 있었습니다. 오늘 밤만 벌써 세 번째 리팩터링이었습니다. ‘복잡한 작업을 자동으로 끝낸다’는 Agent 모드가 정말 도움을 주는 도구인지, 아니면 사람을 괴롭히는 도구인지 의심하기 시작했습니다.

3개월 전 Cursor에서 Agent 모드 스위치를 처음 발견했을 때는 신대륙을 찾은 듯 신이 났습니다. AI에게 요구 사항만 말하면 파일을 만들고, 의존성을 설치하고, 코드를 작성하고, 버그까지 고쳐 주는 동안 커피를 마시며 결과만 기다리면 된다고 상상했습니다. 현실은 달랐습니다. Agent가 실제로 일을 자동화해 주기는 하지만, 종종 일을 자동으로 망쳐 놓기도 했습니다.

3개월 동안 시행착오를 겪은 끝에 Agent와의 관계는 애증에서 호흡이 맞는 협업으로 바뀌었습니다. 이제 Agent는 가장 든든한 조력자입니다. 단, 다루는 방법을 알고 있을 때만 그렇습니다. 이 글에서는 그동안 겪은 실수와 정리한 경험을 공유합니다.

Agent 모드란 무엇인가: 일반 Chat과의 차이부터 이해하기

Cursor의 Composer를 열면 오른쪽 위에 ‘Agent’ 스위치가 보입니다. 이 작은 스위치를 켜는 것은 AI에 손발을 달아 주는 것과 비슷합니다.

일반 모드에서 AI는 ‘여기에 함수를 추가해야 합니다’, ‘이 버그의 원인은 이것일 수 있습니다’처럼 조언만 하고 사용자가 직접 작업하기를 기다립니다. 반면 Agent 모드는 직접 움직입니다. 파일 생성, 코드 수정, npm 패키지 설치, 명령 실행을 한 흐름으로 처리합니다.

아주 편리하게 들리지만, 바로 그 점이 문제이기도 합니다. 인턴에게 코드를 수정해 달라고 했다고 생각해 보세요. 실제로 수정은 했지만 결과를 확인해 보니 다른 파일까지 바뀌고 핵심 로직도 달라져 있을 수 있습니다. Agent는 부지런하지만 아직 완전히 믿기 어려운 인턴과 비슷합니다.

그래서 저는 작은 작업에는 Chat을 사용합니다. 예를 들어 ‘이 코드를 설명해 줘’ 같은 요청입니다. 여러 파일을 다루는 작업에는 Agent를 사용합니다. 예를 들면 ‘모든 컴포넌트에 TypeScript 타입을 추가해 줘’ 같은 요청입니다. 중요한 것은 언제 맡기고 언제 세밀하게 지켜봐야 하는지 판단하는 일입니다.

팁 1: 작업 분할의 기술 — Agent에게 한꺼번에 너무 많이 맡기지 않기

제가 저지른 가장 큰 실수는 Agent에게 지나치게 큰 작업을 한 번에 던진 것이었습니다.

한번은 오래된 프로젝트를 리팩터링하면서 Agent에게 ‘이 프로젝트를 JavaScript에서 TypeScript로 마이그레이션하고 성능도 최적화한 다음 로그인 기능까지 추가해 줘’라고 말했습니다. Agent는 파일을 쉴 새 없이 만들고 한참을 수정했지만, 결국 프로젝트가 아예 실행되지 않았습니다. 코드를 되돌리는 데 하루를 꼬박 썼습니다.

그 뒤로는 작업을 다음과 같이 나눕니다.

1. 첫 번째: ‘먼저 src/components 디렉터리의 파일에 TypeScript 타입을 추가해 줘.’
2. 두 번째: ‘src/utils의 타입 정의를 처리해 줘.’
3. 세 번째: ‘tsconfig.json을 설정하고 정상적으로 컴파일되는지 확인해 줘.’

한 단계를 마칠 때마다 테스트를 실행하고 문제가 없는지 확인한 뒤 다음 단계로 넘어갑니다. 오류가 생겨도 어느 단계가 문제인지 빠르게 찾을 수 있습니다.

작은 요령이 하나 있습니다. 작업을 나눌 때 각 작업이 영향을 주는 파일을 3~5개 이내로 제한하세요. 이 수를 넘기면 Agent가 한쪽을 챙기다가 다른 쪽을 놓치기 쉽습니다. 인턴에게 파일 20개를 한꺼번에 수정하라고 하지 않는 것과 같은 이유입니다.

팁 2: 컨텍스트 관리 — Agent가 무엇을 봐야 하는지 알려 주기

Agent는 어떤 파일이 중요하고 어떤 파일을 무시해야 하는지 스스로 알지 못합니다. 프로젝트에는 파일이 수천 개 있을 수 있고, 그중 절반 이상이 node_modules일 수도 있습니다. Agent가 이 모든 파일을 훑으면 매우 느려질 뿐 아니라 관련 없는 내용에 방해받기도 쉽습니다.

저는 Agent 작업을 시작하기 전에 항상 두 가지를 먼저 합니다.

1단계: .cursorignore 설정

이 파일은 Cursor에 인덱싱하지 않아도 되는 디렉터리를 알려 줍니다. 제가 쓰는 템플릿은 다음과 같습니다.

node_modules/
dist/
build/
.next/
.git/
*.log
coverage/

이 설정을 추가하면 Agent의 응답 속도가 30% 이상 빨라집니다. 작은 차이처럼 보여도 하루 동안 쌓이면 적지 않은 시간을 아낄 수 있습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

2단계: @ 기호로 정확히 참조

Agent가 특정 파일을 수정해야 할 때는 @파일명으로 컨텍스트를 명확히 지정합니다. 예를 들어 ‘@api.ts의 방식을 참고해 @user.ts에도 오류 처리를 추가해 줘’라고 합니다. 그러면 Agent가 온 프로젝트를 헤매며 파일을 찾지 않습니다.

한번은 @를 쓰지 않고 ‘API 파일의 방식을 참고해 줘’라고만 했습니다. Agent는 2년 전에 만든 오래된 파일을 찾아 그 낡은 패턴대로 코드를 수정했습니다. 결과를 수습하기가 꽤 고통스러웠습니다.

팁 3: 버전 관리는 생명줄이다

이 팁은 뼈아픈 경험을 통해 배웠습니다.

어느 금요일 오후, Agent에게 모듈 리팩터링을 맡기고 회의에 갔습니다. 돌아와 보니 Agent가 파일을 30개 넘게 수정해 두었습니다. 처음에는 효율이 정말 높다고 생각했습니다. 하지만 저녁에 테스트해 보니 로그인 기능이 망가져 있었습니다.

문제는 Agent가 어떤 파일을 수정했는지 제가 기억하지 못했다는 점입니다.

그날 밤 파일을 하나씩 비교하며 문제를 찾는 데 3시간이 걸렸습니다. 그 뒤로는 스스로 철칙을 정했습니다. Agent를 사용하기 전에 반드시 commit합니다.

지금은 다음과 같은 흐름으로 작업합니다.

# 시작하기 전에 먼저 커밋
git add .
git commit -m "Agent 사용 전 백업"

# 그다음 안심하고 Agent에게 작업을 맡김

# 작업이 끝나면 변경 내용 확인
git diff

Agent가 잘못 수정했다면 git reset --hard로 바로 되돌리고 다시 시작합니다. 이 방법 덕분에 여러 번 위기를 피했습니다.

작은 팁을 하나 더 보태면, Agent가 한 번에 하나의 기능 모듈만 수정하게 하고 끝나는 즉시 commit하세요. 문제가 생겨도 되돌리는 비용이 작습니다. 게임에서 자주 저장하는 것과 같습니다. 저장은 여러 번 해도 손해가 없습니다.

팁 4: 중단하는 법 익히기 — Agent가 오류를 냈다면 계속 파고들게 두지 않기

Agent는 작업을 시작하면 끝까지 내달리는 경향이 있습니다. 도중에 오류가 나더라도 억지로 계속 진행하다가 문제가 더 심해질 수 있습니다.

제가 본 가장 심한 사례에서는 Agent가 특정 의존성을 찾지 못하자 가짜 의존성을 직접 만들고, 그것을 기반으로 코드를 계속 작성했습니다. 제가 알아챘을 때는 잘못된 전제를 바탕으로 이미 파일을 열 개 넘게 수정한 뒤였습니다.

이제 저는 감독하는 법을 배웠습니다. Agent가 작업을 시작하면 출력 로그를 지켜봅니다.

• 빨간색 오류가 보이면 즉시 ESC를 눌러 중단합니다.
• 이상한 파일을 만드는 것이 보이면 바로 멈춥니다.
• 건드리면 안 되는 핵심 로직을 수정하면 단호하게 중단합니다.

중단한 뒤에는 먼저 Agent가 이미 한 일을 확인하고 평가합니다.

• 수정한 내용이 괜찮으면 그 부분을 유지하고 지시를 조정해 계속합니다.
• 이미 방향이 틀렸다면 바로 git reset을 하고 지시를 다시 내립니다.

Agent를 중간에 멈추는 것을 미안해할 필요는 없습니다. Agent는 사람이 아니므로 작업을 중단시켰다고 기분 나빠하지 않습니다. 잘못된 로직을 모두 구현할 때까지 기다리면 나중에 수습할 일이 훨씬 많아집니다.

팁 5: Agent가 작성한 코드를 무조건 믿지 않기

솔직히 말해 Agent가 생성한 코드의 품질은 복불복에 가깝습니다. 때로는 놀라운 결과를 주지만, 때로는 놀랄 만큼 나쁜 결과를 내놓습니다.

처음 Agent를 사용할 때는 ‘AI가 이렇게 똑똑한데 작성한 코드도 문제가 없겠지’라고 생각했습니다. 하지만 테스트 환경이 두 번 망가진 뒤에야 코드 리뷰를 한 단계도 생략해서는 안 된다는 사실을 깨달았습니다.

이제 Agent가 작업을 끝낼 때마다 다음을 수행합니다.

1단계: 테스트 실행

npm test

기본적인 작업이지만 많은 사람이 잊습니다. Agent는 알아서 테스트까지 실행해 주지 않습니다. 코드를 작성하면 자기 일이 끝났다고 여길 수 있습니다.

2단계: 코드 리뷰 체크리스트
저는 다음과 같은 검사표를 사용합니다.

• ✓ 로직 정확성: 기능이 예상대로 작동하는가
• ✓ 경계 조건: 빈 값과 예외 상황을 처리했는가
• ✓ 성능 문제: 뚜렷한 병목이 있는가
• ✓ 코드 스타일: 프로젝트 규칙을 따르는가
• ✓ 보안 위험: SQL 인젝션이나 XSS 같은 위험이 있는가

3단계: 작업을 건너뛴 부분 확인
Agent는 지름길을 택하는 경향이 있습니다. 예를 들어 ‘데이터베이스 쿼리를 최적화해 줘’라고 하면 SQL 자체를 최적화하는 대신 캐시만 추가할 수도 있습니다. 무엇을 바꿨는지, 실제로 문제가 해결됐는지 자세히 확인해야 합니다.

한번은 Agent가 복잡한 비즈니스 로직을 // TODO: 구현 필요라고 적어 두고 건너뛴 것을 발견했습니다. 빈자리를 제가 채우도록 남겨 두는 영리한 방법이었습니다.

팁 6: 대규모 프로젝트에서 Agent를 올바르게 사용하는 법

작은 프로젝트에서 Agent는 압도적인 효율을 보여 줍니다. 하지만 파일이 수백 개이고 의존 관계가 복잡하며 여러 사람이 서로 다른 코드 스타일로 협업하는 대규모 프로젝트에서는 Agent가 쉽게 혼란에 빠집니다.

제가 작업한 Next.js 프로젝트에는 컴포넌트가 200개 넘게 있었습니다. 처음에는 Agent를 켜고 ‘모든 컴포넌트의 성능을 최적화해 줘’라고 지시했습니다. Agent는 파일을 찾는 데만 10분을 쓰더니 중요하지 않은 부분 몇 곳만 수정했고, 핵심 컴포넌트는 하나도 건드리지 않았습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

그 뒤로 대규모 프로젝트에 맞는 사용법을 정리했습니다.

전략 1: 모듈별 처리
Agent가 전체 프로젝트를 한꺼번에 보게 하지 말고 범위를 지정하세요. 예를 들면 다음과 같습니다.

• ‘src/components/auth 디렉터리의 파일만 처리해 줘.’
• ‘사용자 로그인과 관련된 코드만 수정해 줘.’

이렇게 하면 Agent의 주의가 한곳에 집중되어 다른 관련 없는 코드에 방해받지 않습니다.

전략 2: .cursorrules로 경계 설정
프로젝트 루트에 .cursorrules 파일을 만들고 프로젝트 규칙을 알려 줍니다.

# 프로젝트 규칙
- 모든 컴포넌트는 TypeScript를 사용해야 합니다
- API 호출에는 모두 @/lib/api를 사용합니다
- @/lib/core 디렉터리의 핵심 로직은 수정하지 않습니다
- 새 파일에는 JSDoc 주석이 있어야 합니다

이런 규칙이 있으면 Agent가 제멋대로 작업할 가능성이 줄어듭니다. 인턴에게 개발 규칙 문서를 건네는 것과 비슷합니다. 전부 지킨다고 보장할 수는 없지만 적어도 참고할 기준은 생깁니다.

전략 3: 독립 모듈 우선 처리
대규모 프로젝트에도 도구 함수나 공용 컴포넌트처럼 비교적 독립적인 모듈이 있습니다. 이런 곳이 Agent가 능력을 발휘하기 좋은 영역입니다. 잘못 수정해도 영향 범위가 작고, 잘 수정하면 프로젝트 전체가 이점을 얻습니다.

팁 7: Agent와 Composer의 이상적인 조합

많은 사람이 Agent와 Composer의 관계를 혼동합니다. 둘 중 하나를 선택하는 것이 아니라 함께 사용하는 도구입니다.

간단히 말하면 Composer는 작업대이고 Agent는 자동화 스위치입니다.

저는 다음과 같이 사용합니다.

상황 1: 여러 파일 리팩터링 = Composer + Agent ON
관련 파일 여러 개를 동시에 수정해야 할 때는 Composer에서 Agent 모드를 켭니다. 예를 들어 ‘모든 API 호출에 오류 처리와 재시도 메커니즘을 추가해 줘’처럼 여러 파일에 걸친 일괄 작업에서는 Agent 모드가 생산성을 크게 높여 줍니다.

상황 2: 한 파일의 심층 수정 = Composer + Agent OFF
한 컴포넌트의 복잡한 로직만 수정한다면 Agent를 끄고 일반 Composer를 사용합니다. AI가 코드를 제안하고 제가 직접 적용하므로 각 단계를 더 잘 통제할 수 있습니다.

상황 3: 빠른 질문 = Chat
‘이 오류는 무슨 뜻이야?’ 또는 ‘이 코드를 어떻게 최적화하지?’ 같은 질문만 하려면 Chat을 바로 사용합니다. Composer를 여는 것조차 번거로운 상황입니다.

Composer에서는 언제든 Agent 스위치를 전환할 수 있습니다. 처음에는 켜 두고 일을 맡기다가 도중에 방향이 잘못됐다고 느끼면 끄고 직접 제어권을 넘겨받을 수 있습니다. 한 가지 방식만 고집하지 말고 유연하게 전환하세요.

팁 8: 반드시 피해야 할 함정

Agent를 오래 사용하면서 자주 마주치는 함정을 몇 가지 정리했습니다. 절대 하면 안 된다는 뜻은 아니지만, 실행하기 전에 신중하게 생각해야 합니다.

함정 1: Agent가 데이터베이스를 직접 조작하게 하기
한번은 편하게 처리하려고 Agent에게 ‘테스트 데이터베이스의 중복 레코드를 정리해 줘’라고 했습니다. 중복 데이터는 정리됐지만 운영 환경의 데이터까지 함께 삭제됐습니다. .env에 운영 데이터베이스 연결이 설정되어 있었고, Agent는 환경을 대신 전환해 주지 않았기 때문입니다.

교훈은 데이터베이스 작업은 직접 처리하거나 적어도 먼저 백업해야 한다는 것입니다.

함정 2: 모든 파일의 특정 패턴을 한꺼번에 수정하기
‘모든 파일의 var를 let으로 바꿔 줘’는 간단하게 들립니다. 하지만 Agent는 주석, 문자열, 심지어 서드파티 라이브러리에 있는 var까지 바꿀 수 있습니다. 코드는 실행되더라도 이해하기 어려운 변경이 잔뜩 생길 수 있습니다.

더 안전한 방법은 먼저 한 디렉터리만 수정하게 하고, 결과를 확인한 뒤 범위를 넓히는 것입니다.

함정 3: 테스트가 없는 프로젝트에서 Agent를 마음껏 실행하기
저도 직접 겪었습니다. 테스트가 없는 오래된 프로젝트를 Agent에게 맡겨 리팩터링했습니다. 결과는 그럴듯해 보였지만 배포 후 기능 세 개가 망가진 것을 발견했습니다. 테스트라는 안전망이 없으면 Agent가 어떤 문제를 만들었는지 알기 어렵습니다.

따라서 먼저 테스트를 작성하거나, 작은 단위로 작업하면서 직접 검증해야 합니다. 한 번에 모든 것을 맡기지 마세요.

함정 4: Agent에 지나치게 의존하기
가장 큰 함정은 마음가짐입니다. Agent를 오래 쓰면 문제가 생길 때마다 가장 먼저 ‘Agent에게 맡겨야지’라고 생각하게 됩니다. 하지만 직접 고민해야 하는 문제도 있습니다. 변수 이름까지 Agent에게 물어보는 사람도 봤는데, 그 정도면 지나친 의존입니다.

Agent는 도구이지 보호자가 아닙니다. 생산성을 높여 주지만 사고를 대신할 수는 없습니다.

팁 9: Agent를 더 빠르게 실행하는 방법

Agent는 가끔 답답할 정도로 느립니다. 파일 몇 개만 수정하면 되는데도 한참 기다려야 할 때가 있습니다. 몇 가지 최적화 방법을 사용하면 속도를 상당히 높일 수 있습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

팁 1: 인덱싱 범위 줄이기
앞에서 설명한 .cursorignore는 기본입니다. 그 밖에도 설정에서 Codebase 인덱싱 범위를 조정할 수 있습니다. 저는 보통 src/와 lib/ 같은 핵심 디렉터리만 인덱싱하고 문서나 설정 파일 등은 제외합니다.

팁 2: 대화 기록 정리하기
Agent는 이전 대화의 컨텍스트를 참고합니다. 대화 기록이 너무 길면 매번 내용을 되짚느라 느려집니다. 저는 큰 작업을 하나 끝낼 때마다 새 대화를 시작합니다. 장바구니를 비우고 가볍게 출발하는 것과 비슷합니다.

팁 3: 더 빠른 모델 사용하기
Cursor의 기본 모델은 GPT-4로 품질은 높지만 느립니다. 일괄 이름 변경이나 코드 포매팅 같은 간단한 작업에는 Claude Sonnet이나 GPT-3.5로 전환하면 속도가 두 배 가까이 빨라질 수 있습니다.

제 원칙은 복잡한 로직에는 안정적인 GPT-4를 쓰고, 간단한 작업에는 빠른 모델을 쓰는 것입니다.

팁 4: 한꺼번에 수정하지 말고 나누어 처리하기
파일 100개에 주석을 추가해야 한다면 한 번에 모두 맡기지 마세요. 20개씩 5번으로 나누고 중간마다 확인합니다. 문제를 일찍 발견할 수 있을 뿐 아니라 Agent가 한 번에 다루는 컨텍스트도 작아져 속도가 빨라집니다.

결국 Agent도 최적화가 필요합니다. 쿼리가 테이블 전체를 스캔하도록 두지 않는 것처럼 Agent의 부담을 줄이면 훨씬 원활하게 작동합니다.

팁 10: 나의 Agent 사용 체크리스트

오랫동안 사용하면서 Agent 체크리스트를 만들었습니다. Agent를 켜기 전에 매번 한 번씩 훑어봅니다.

작업 시작 전:

• ✓ Git에 commit했고 작업 트리가 깨끗함
• ✓ .cursorignore 설정 완료
• ✓ 작업 범위 명확화(영향받는 파일 확인)
• ✓ 현재 브랜치 확인(main에서 직접 수정하지 않기)
• ✓ 테스트 환경 준비(즉시 검증 가능)

Agent 실행 중:

• ✓ 출력 로그를 모니터링하고 이상이 보이면 즉시 중단
• ✓ 파일 변경을 살펴 핵심 로직 오수정 방지
• ✓ 방향이 어긋나면 단호하게 ESC로 중단
• ✓ 복잡한 작업은 욕심내지 말고 단계별로 실행

작업 완료 후:

• ✓ git diff로 모든 변경 확인
• ✓ 테스트 실행(npm test)
• ✓ 코드 리뷰(로직, 성능, 보안)
• ✓ 로컬 테스트 통과 후 commit
• ✓ 불필요한 대화 기록 정리

번거로운 체크리스트처럼 보이지만 실제로 위기에서 구해 줍니다. 조종사가 이륙 전에 검사표를 확인하는 것처럼, 매번 점검하면 대부분의 사고를 피할 수 있습니다.

가장 중요한 항목은 금요일 오후에는 절대 Agent에게 큰 변경을 맡기지 않는 것입니다. 뼈아픈 경험에서 얻은 교훈입니다. 주말 내내 버그를 고치는 일은 정말 괴롭습니다.

결론

글 첫머리의 새벽 2시 상황으로 돌아가 보겠습니다. 지금의 저는 Agent가 통제 불능 상태로 잘못된 파일 다섯 개를 만들도록 두지 않습니다. 언제 맡기고 언제 중단해야 하는지, 작업을 어떻게 나누고 경계를 어떻게 설정해야 하는지 알기 때문입니다. 무엇보다 Agent는 마법이 아니라 다루는 법을 배워야 하는 도구라는 점을 이해했습니다.

3개월 동안 시행착오를 거쳐 이 10가지 팁을 얻었습니다. 솔직히 Agent 모드는 개발 생산성을 두 배로 높여 줄 수 있습니다. 다만 함께 일하는 법을 알아야 합니다. 활력이 넘치지만 경험이 부족한 인턴처럼, 방향을 제대로 제시하면 많은 일을 도와주지만 방치하면 프로젝트를 엉망으로 만들 수도 있습니다.

제 조언은 실패를 두려워하지 말되 언제든 되돌릴 준비를 하라는 것입니다. 작은 작업부터 연습하며 서서히 신뢰를 쌓으세요. Agent와 호흡이 맞기 시작하면 정말 든든한 조력자가 될 수 있습니다.

마지막으로 마음가짐 하나를 공유하겠습니다. Agent는 능력을 강화하는 도구이지 생각을 대신하는 도구가 아닙니다. 문제가 생기면 먼저 직접 해결 방법을 생각한 뒤 Agent의 도움이 필요한지 판단하세요. 이 원칙을 지키면 도구에 끌려다니지 않을 수 있습니다.

Cursor Agent를 막 사용하기 시작했다면 먼저 Git부터 설정하세요. 농담이 아닙니다. 언제든 되돌릴 수 있다는 안정감이 있어야 더 과감하게 시도할 수 있습니다.

Agent와 즐겁게 협업하시길 바랍니다. 여러분에게도 활용 팁이나 시행착오 경험이 있다면 댓글로 공유해 주세요. 각자 따로 헤매는 것보다 함께 실수를 피하는 편이 낫습니다.