Cursor의 Agent 모드를 능숙하게 사용했더니 '엉뚱한 제안'이 사라지고 코딩 속도가 3배 빨라진 이야기

• Cursor의 Agent 모드와 Chat 모드의 근본적인 차이
• "엉뚱한 제안만 가득"한 상황을 해소하는 Context 설정 노하우
• Agent에게 긴 작업을 맡기고 방치하기 위한 지시 작성법

.cursor/rules/에서 에이전트의 행동 규칙을 사전에 정의하는 방법 - 실제로 도입하여 코딩 속도가 3배가 된 구체적인 사용법

Cursor를 사용하기 시작했을 때 가장 곤란했던 점은 "엉뚱한 제안"이었습니다.

나: 이 컴포넌트를 리팩터링(Refactoring)해줘
Cursor: (프로젝트와 관계없는 다른 파일을 참조하며)
이런 구현은 어떠신가요?
...

컨텍스트(Context)를 올바르게 전달하지 못했을 뿐이었습니다.

Agent 모드와 Context 설정을 정비한 결과, 엉뚱한 제안이 거의 제로가 되었고, 긴 작업을 통째로 맡길 수 있게 되었습니다.

Chat 모드
↓
코드를 제안함 (직접 적용해야 함)
...

Agent는 "알아서 해줘"가 통한다. Chat은 "어떻게 하면 좋을까?"를 묻는 곳이다.

나: @Button.tsx @types.ts @theme.ts
이 컴포넌트를 다크 모드(dark mode) 대응으로 만들어줘
Cursor: (제안을 내놓음)
...

나: src/components/ 이하의 모든 컴포넌트를
dark mode 대응으로 만들어줘.
Tailwind의 dark: 접두사(prefix)를 사용할 것.
...

1. @Codebase로 전체상을 전달하기

❌ 엉뚱해지기 쉬운 경우
"이 함수를 리팩터링해줘"
✅ 컨텍스트가 통하는 경우
...

@Codebase를 넣으면 Cursor가 인덱스(Index)를 검색하여 관련 파일을 자동으로 참조합니다.

매번 "〇〇 형식으로 작성해줘"라고 말하지 않아도 되도록 규칙 파일을 만듭니다:

.cursor/rules/
├── always.mdc ← 상시 적용 (5개까지)
├── components.mdc ← src/components/** 에 자동 적용
...

---
alwaysApply: true
---
...

---
globs: ["src/components/**/*.tsx"]
---
...

Agent가 잘못된 방향으로 달려나가는 것을 방지하는 지시:

"src/api/user.ts를 리팩터링해 주세요.
시작하기 전에:
1. 변경 대상 파일과 변경 내용의 개요를 알려주세요
...

"다음 변경 사항을 src/components/ 이하의 모든 파일에 적용해 주세요:
변경 내용:
- className 문자열을 cn() 유틸리티 함수로 감싸기
...

"사용자의 프로필 편집 기능을 구현해 주세요.
사양:
- 폼: 이름, 이메일 주소, 아바타 이미지
...

"다음 버그를 조사하고 수정해 주세요:
증상: 사용자가 프로필 이미지를 업로드하면,
두 번째 이후의 업로드가 캐시된 오래된 이미지를 표시함
...

커맨드	사용처
@Codebase	프로젝트 전체를 검색해주길 원할 때
@파일명	특정 파일을 참조시키고 싶을 때
@Docs	라이브러리의 공식 문서를 참조시키고 싶을 때
@Web	최신 정보를 검색하게 하고 싶을 때
@Git	최근의 변경 사항을 참조하고 싶을 때
@Terminal	직전의 터미널 출력을 전달할 때

Agent에게 통째로 맡길 때, 멈춰야 할 시점을 사전에 전달해 두면 폭주하지 않습니다:

"다음 작업을 수행해 주세요:
...
다음의 경우에는 작업을 멈추고 확인을 요청해 주세요:
...

설정	효과
@Codebase를 사용한다	프로젝트 전체를 파악한 후 제안
.cursor/rules/로 사전 정의	매번 지시할 필요가 없음
"확인 후 진행"을 전달한다	잘못된 방향으로의 폭주를 방지
완료 조건과 중단 조건을 명시	긴 작업을 안전하게 통째로 맡김

Agent는 "무엇이든 해주는 편리한 도구"가 아니라 "규칙과 문맥을 정비하면 단번에 똑똑해지는 도구"입니다. 처음 10분을 투자하여 설정을 정비하면, 그다음부터는 멈출 수 없게 됩니다.

Q. Agent 모드는 어디서 사용할 수 있나요?

A. Cursor의 채팅창 왼쪽 상단에 있는 전환 버튼, 또는 Cmd+Shift+I를 통해 Agent 모드로 전환할 수 있습니다.

Q. Agent가 마음대로 커밋(commit)을 해버립니다

A. .cursor/rules/ 디렉토리 내의 alwaysApply: true 설정이 된 규칙에 "git commit은 반드시 사용자의 확인을 거칠 것"이라고 적어두면 방지할 수 있습니다.

Q. @Codebase가 느립니다

A. 인덱싱 (Indexing) 중일 수 있습니다. Cursor Settings → Features → Codebase indexing에서 상태를 확인해 주세요. 규모가 큰 리포지토리 (Repository)는 첫 인덱싱에 몇 분 정도 소요될 수 있습니다.

Q. Chat과 Agent 중 어느 것을 사용해야 하나요?

A. "어떻게 하면 좋을까?"라는 질문에는 Chat이, "이것 좀 해줘"라는 요청에는 Agent가 적합합니다. 여러 파일을 동시에 수정해야 하는 작업은 Agent가 유일한 선택지입니다.