Cursor Composer 완벽 가이드: 멀티 파일 편집, 인라인 Diff, 에이전트 모드

Cursor Composer 완벽 가이드: 멀티 파일 편집, 인라인 Diff, 에이전트 모드

Cursor Composer란 무엇이고 멀티 파일 편집이 왜 중요한가

Cursor Composer는 Cursor 에디터에 내장된 AI 기반 멀티 파일 편집 도구다. 일반적인 AI 코드 어시스턴트가 하나의 파일 단위로 동작하는 것과 달리, Composer는 프로젝트 전체를 가로지르며 여러 파일을 동시에 생성하고 수정할 수 있다.

실제 개발에서 하나의 기능은 단일 파일로 완결되지 않는다. React 컴포넌트를 만들면 타입 정의 파일, API 라우트, 테스트 파일, 스타일 파일이 함께 변경되어야 한다. 데이터베이스 스키마를 수정하면 마이그레이션, 모델 코드, API 핸들러, 프론트엔드 호출부가 연쇄적으로 바뀌어야 한다. Composer는 이런 연쇄 변경을 하나의 대화 안에서 처리한다.

Composer가 기존 Chat 기능과 근본적으로 다른 점은 세 가지다.

첫째, 변경 사항을 직접 파일에 반영한다. Chat은 코드 블록을 보여주고 개발자가 직접 복사해서 붙여넣어야 하지만, Composer는 인라인 Diff 형태로 변경 사항을 해당 파일에 직접 표시한다.

둘째, 여러 파일을 한 번에 다룬다. 하나의 프롬프트로 5개, 10개 파일을 동시에 수정하거나 새로 생성할 수 있다.

셋째, 에이전트 모드에서는 터미널 명령까지 실행한다. 패키지 설치, 빌드 확인, 린트 오류 수정까지 자율적으로 수행한다.

Composer 열기와 인터페이스 구성

Composer를 여는 방법은 간단하다.

• Mac: Cmd + I
• Windows/Linux: Ctrl + I

단축키를 누르면 에디터 하단 또는 사이드바에 Composer 패널이 나타난다. 패널은 크게 네 영역으로 구성된다.

프롬프트 입력 영역: 상단의 텍스트 입력창이다. 여기에 원하는 변경 사항을 자연어로 작성한다. @ 기호를 입력하면 파일, 폴더, 심볼을 멘션할 수 있는 자동완성 메뉴가 나타난다.

모드 선택기: 입력창 옆에 Normal과 Agent 모드를 전환하는 토글이 있다. Normal 모드는 코드 변경만 제안하고, Agent 모드는 터미널 명령 실행까지 포함한 자율 작업을 수행한다.

컨텍스트 표시 영역: 현재 Composer가 참조하고 있는 파일 목록이 표시된다. 여기서 불필요한 파일을 제거하거나 새 파일을 추가할 수 있다.

Diff 미리보기: Composer가 제안한 변경 사항이 파일별로 인라인 Diff 형태로 나타난다. 각 변경 사항을 개별적으로 수락하거나 거부할 수 있다.

전체 화면으로 Composer를 사용하고 싶다면 Cmd + Shift + I (Mac) 또는 Ctrl + Shift + I (Windows/Linux)를 누르면 된다. 넓은 화면에서 여러 파일의 Diff를 한눈에 확인할 때 유용하다.

@ 멘션으로 컨텍스트 추가하기

Composer의 출력 품질은 제공하는 컨텍스트에 비례한다. @ 멘션 시스템으로 AI에게 정확한 맥락을 전달하는 것이 핵심이다.

@File - 특정 파일 참조

가장 기본적인 멘션이다. @filename.ts처럼 입력하면 해당 파일의 전체 내용이 컨텍스트에 포함된다.

@src/components/UserProfile.tsx 이 컴포넌트에 프로필 이미지 업로드 기능을 추가해줘.
업로드 API는 @src/api/upload.ts 에 있어.

@Folder - 폴더 전체 참조

폴더를 멘션하면 해당 폴더 내 파일들의 구조와 내용이 컨텍스트에 포함된다. 새 기능을 추가할 때 기존 패턴을 파악하는 데 효과적이다.

@src/api/ 폴더의 기존 API 라우트 패턴을 따라서 /api/payments 엔드포인트를 만들어줘.

@Docs - 외부 문서 참조

라이브러리 공식 문서나 프레임워크 가이드를 직접 참조할 수 있다. Cursor Settings에서 자주 쓰는 문서를 미리 등록해두면 @Docs로 바로 불러온다.

@Docs(Next.js App Router) 규칙에 맞게 @src/app/ 아래에 대시보드 페이지를 만들어줘.

@Codebase - 코드베이스 검색

전체 코드베이스를 임베딩 기반으로 검색한다. 특정 파일이 어디 있는지 모를 때, 관련 코드를 AI가 직접 찾아서 참조하도록 할 수 있다.

@Codebase 인증 미들웨어가 어디에 구현되어 있는지 찾아서, 같은 패턴으로 권한 확인 미들웨어를 만들어줘.

컨텍스트 관리 원칙

컨텍스트는 많을수록 좋은 것이 아니다. 불필요한 파일을 포함하면 토큰을 낭비하고 AI의 집중도가 떨어진다. 다음 원칙을 따르자.

• 변경 대상 파일은 반드시 포함한다
• 참조해야 하는 타입 정의, 인터페이스 파일을 포함한다
• 기존 패턴을 따라야 할 경우 유사한 파일 한두 개를 포함한다
• 직접 관련 없는 파일은 제외한다

일반 모드: 인라인 Diff와 리뷰 워크플로우

Normal 모드는 Composer의 기본 동작 방식이다. 프롬프트를 입력하면 AI가 변경 사항을 분석하고, 각 파일에 인라인 Diff를 생성한다. 개발자는 이 Diff를 검토한 뒤 수락 또는 거부한다.

인라인 Diff의 동작 방식

Composer가 변경을 제안하면 해당 파일의 에디터 탭이 열리면서 변경 부분이 초록색(추가)과 빨간색(삭제)으로 하이라이트된다. 이것은 Git의 diff와 동일한 형식이다.

예를 들어, 기존 함수에 에러 처리를 추가하라는 요청을 하면 다음과 같은 변경이 인라인으로 표시된다.

// Before
async function fetchUser(id: string) {
  const response = await api.get(`/users/${id}`);
  return response.data;
}

// After (Composer가 제안하는 변경)
async function fetchUser(id: string) {
  try {
    const response = await api.get(`/users/${id}`);
    if (!response.ok) {
      throw new ApiError(`Failed to fetch user: ${response.status}`);
    }
    return response.data;
  } catch (error) {
    if (error instanceof ApiError) throw error;
    throw new NetworkError('Network request failed', { cause: error });
  }
}

변경 수락과 거부

각 파일의 변경 사항에 대해 세 가지 수준으로 결정할 수 있다.

헝크 단위: 한 파일 내에서도 변경된 부분(헝크)별로 개별 수락/거부가 가능하다. 함수 A의 변경은 수락하고 함수 B의 변경은 거부하는 식이다.

파일 단위: 파일 상단의 체크박스로 해당 파일의 모든 변경을 한 번에 수락하거나 거부한다.

전체 수락: Composer 패널의 “Accept All” 버튼으로 모든 파일의 모든 변경을 한 번에 반영한다.

반복 수정 워크플로우

Composer의 가장 강력한 점은 대화형 반복 수정이다. 첫 번째 결과가 완벽하지 않으면 추가 지시를 내리면 된다.

함수는 잘 만들었는데, 에러 메시지에 요청 URL도 포함시켜줘. 그리고 retry 로직을 3회까지 추가해줘.

이전 대화의 맥락이 유지되므로, 처음부터 다시 설명할 필요 없이 점진적으로 다듬어 나갈 수 있다.

에이전트 모드: 자율 멀티스텝 실행

에이전트(Agent) 모드는 Composer를 단순한 코드 제안 도구에서 자율적인 개발 에이전트로 전환한다. 모드 선택기에서 Agent를 선택하거나, 프롬프트 입력 시 자동으로 전환되는 경우도 있다.

에이전트 모드가 수행하는 작업

에이전트 모드에서 Composer는 다음을 자율적으로 수행한다.

• 파일 생성, 수정, 삭제
• 터미널 명령 실행 (패키지 설치, 빌드, 테스트 등)
• 오류 발생 시 원인 분석 후 자동 수정 시도
• 필요한 파일을 코드베이스에서 자동 탐색

예를 들어 다음과 같은 프롬프트를 에이전트 모드로 실행할 수 있다.

NextAuth.js를 사용해서 Google OAuth 로그인을 구현해줘.
필요한 패키지 설치부터 환경 변수 설정, API 라우트, 로그인 버튼 컴포넌트까지 전부 만들어줘.

에이전트는 이 요청을 받으면 다음 단계를 자율적으로 수행한다.

1. npm install next-auth 실행
2. src/app/api/auth/[...nextauth]/route.ts 파일 생성
3. .env.local에 필요한 환경 변수 템플릿 추가
4. src/components/LoginButton.tsx 컴포넌트 생성
5. src/app/layout.tsx에 SessionProvider 래핑
6. 빌드를 실행해서 오류가 없는지 확인

에이전트 모드 사용 시 주의사항

에이전트 모드는 강력하지만 주의가 필요하다.

터미널 명령 확인: 에이전트가 터미널 명령을 실행하기 전에 확인 프롬프트가 뜬다. 특히 rm, git 같은 파괴적 명령은 반드시 내용을 확인한 뒤 승인하자.

단계별 검토: 에이전트가 여러 단계를 수행할 때, 중간 결과를 확인하면서 진행하는 것이 안전하다. 방향이 잘못되었다면 즉시 중단하고 새로운 지시를 내리자.

범위 한정: 에이전트에게 너무 광범위한 작업을 한 번에 맡기면 예상치 못한 변경이 발생할 수 있다. 기능 단위로 끊어서 요청하는 것이 좋다.

Composer를 위한 프롬프트 엔지니어링

Composer에서 좋은 결과를 얻으려면 프롬프트를 체계적으로 작성해야 한다. 다음 네 가지 패턴이 실무에서 검증된 방법이다.

패턴 1: 구조 명시 패턴

파일 구조와 각 파일의 역할을 먼저 선언한 뒤 구현을 요청한다.

다음 구조로 사용자 알림 기능을 만들어줘:

1. src/types/notification.ts - 알림 타입 정의 (NotificationType, Notification 인터페이스)
2. src/api/notifications.ts - GET/POST/PATCH API 핸들러
3. src/hooks/useNotifications.ts - 알림 목록 조회/읽음 처리 커스텀 훅
4. src/components/NotificationBell.tsx - 알림 아이콘과 뱃지
5. src/components/NotificationList.tsx - 알림 드롭다운 목록

기존 @src/api/posts.ts 의 API 패턴과 @src/hooks/usePosts.ts 의 훅 패턴을 따라줘.

패턴 2: 기존 패턴 참조 패턴

프로젝트에 이미 있는 코드를 명시적으로 참조해서 일관성을 유지한다.

@src/features/auth/login.tsx 와 동일한 폼 패턴으로 회원가입 페이지를 만들어줘.
- React Hook Form + Zod 유효성 검사
- 같은 에러 표시 방식
- 같은 토스트 알림 패턴
- 필드: 이름, 이메일, 비밀번호, 비밀번호 확인

패턴 3: 제약 조건 명시 패턴

하지 말아야 할 것과 지켜야 할 기술적 제약을 명확히 선언한다.

결제 페이지를 리팩토링해줘.

반드시 지킬 것:
- 기존 API 응답 형식은 절대 변경하지 마
- 모든 금액은 센트 단위 정수로 처리
- 에러 시 사용자에게 보여줄 메시지와 로깅용 메시지를 분리

하지 말 것:
- 새 라이브러리 추가 금지
- 기존 테스트가 깨지는 변경 금지

패턴 4: 단계적 실행 패턴

복잡한 작업을 명시적으로 단계를 나누어 요청한다.

데이터베이스 마이그레이션을 단계적으로 진행하자.

1단계: 먼저 새 스키마 타입만 정의해줘. 기존 코드는 건드리지 마.
(여기서 검토 후 다음 단계 진행)

2단계: API 레이어를 새 스키마에 맞게 수정해줘.

3단계: 프론트엔드 호출부를 수정해줘.

이 패턴은 한 번에 모든 것을 요청하지 않고, 각 단계의 결과를 확인하면서 진행할 수 있어 안전하다.

대규모 변경과 토큰 한도 관리

Composer는 LLM 기반이므로 토큰 한도(Context Window)의 제약을 받는다. 대규모 변경 작업에서 이 한도를 효율적으로 관리하는 방법을 알아야 한다.

토큰 소비 줄이기

컨텍스트 최소화: @ 멘션은 꼭 필요한 파일만 포함한다. 500줄짜리 파일 10개를 멘션하면 그것만으로 컨텍스트의 상당 부분을 소모한다.

대화 초기화: 하나의 기능 구현이 끝나면 새 Composer 세션을 시작한다. 이전 대화 내역이 쌓이면 토큰을 불필요하게 점유한다.

파일 분할: 1000줄이 넘는 거대한 파일은 가능하면 먼저 분할한 뒤 Composer를 사용한다.

대규모 리팩토링 전략

20개 이상의 파일을 수정해야 하는 대규모 리팩토링은 한 번에 처리하기 어렵다. 다음 전략을 사용하자.

레이어별 분리: 타입 정의 -> 유틸리티 -> 서비스 레이어 -> API 레이어 -> UI 레이어 순서로 나누어 각 레이어를 별도의 Composer 세션에서 처리한다.

변경 영향 범위 제한: 하나의 Composer 세션에서 수정하는 파일을 5~8개 이내로 제한한다. 그 이상은 품질이 떨어지기 시작한다.

중간 검증: 각 세션이 끝날 때마다 빌드와 테스트를 실행해서 중간 상태가 깨지지 않았는지 확인한다.

Composer vs Chat vs Tab 자동완성: 언제 무엇을 쓸까

Cursor에는 Composer 외에도 Chat과 Tab 자동완성이라는 AI 기능이 있다. 각각의 용도가 다르므로 상황에 맞게 사용해야 한다.

Tab 자동완성

코드를 타이핑하는 중에 자동으로 나타나는 인라인 제안이다.

적합한 상황: 한 줄에서 몇 줄 정도의 코드를 빠르게 완성할 때. 변수명, 함수 호출, 반복 패턴, 보일러플레이트 코드에 효과적이다.

한계: 현재 파일의 맥락만 참조하므로 멀티 파일 작업에는 부적합하다.

Chat (Cmd+L / Ctrl+L)

사이드바에서 AI와 대화하면서 코드에 대해 질문하거나 설명을 듣는다.

적합한 상황: 코드 이해, 디버깅, 설계 상담, “이 코드가 무엇을 하는지 설명해줘” 같은 질문. 코드 블록을 복사해서 수동으로 적용하는 것이 괜찮은 간단한 수정.

한계: 변경 사항을 직접 파일에 반영하지 않는다. 멀티 파일 수정에는 비효율적이다.

Composer (Cmd+I / Ctrl+I)

여러 파일에 걸친 변경을 한 번에 생성하고 인라인 Diff로 검토한다.

적합한 상황: 새 기능 구현, 멀티 파일 리팩토링, 파일 간 일관성이 필요한 변경, 새로운 모듈이나 페이지 생성.

한계: 토큰 한도 내에서만 동작하므로 프로젝트 전체를 한 번에 다룰 수는 없다.

선택 기준 요약

자주 발생하는 문제와 해결법

Composer가 파일을 찾지 못하는 경우

프로젝트 루트가 올바르게 열려 있는지 확인한다. Cursor는 열린 워크스페이스를 기준으로 파일을 탐색한다. 모노레포에서는 하위 패키지가 아닌 루트 디렉토리를 열어야 전체 코드베이스를 참조할 수 있다.

변경 사항이 불완전하게 생성되는 경우

토큰 한도에 가까워지면 Composer가 변경을 중간에 끊는 경우가 있다. 이때는 컨텍스트를 줄이고 작업 범위를 좁혀서 다시 시도한다. “나머지 부분도 이어서 작성해줘”라고 요청하면 이전 맥락을 기반으로 계속 진행하기도 한다.

인라인 Diff가 충돌하는 경우

동일한 파일의 같은 영역에 여러 변경이 겹치면 Diff가 깨질 수 있다. 이 경우 모든 변경을 거부한 뒤, 프롬프트를 더 구체적으로 수정해서 다시 요청한다.

에이전트 모드에서 무한 루프에 빠지는 경우

에이전트가 오류를 수정하려다 다른 오류를 만들고, 그것을 다시 수정하려는 반복에 빠지는 경우가 드물게 발생한다. Esc 키로 즉시 중단하고, 에러 메시지를 직접 분석한 뒤 구체적인 수정 지시를 내리자.

기존 코드 스타일과 맞지 않는 코드가 생성되는 경우

.cursorrules 파일을 프로젝트 루트에 만들어 코딩 컨벤션을 명시한다. 예를 들면 다음과 같다.

- Use functional components with arrow functions
- Use named exports, not default exports
- Error handling: always use custom error classes from src/errors/
- Naming: camelCase for variables, PascalCase for components and types

이 파일이 존재하면 Composer가 자동으로 참조해서 프로젝트 스타일에 맞는 코드를 생성한다.

자주 묻는 질문

Composer는 무료 플랜에서도 사용할 수 있나요?

Cursor Free 플랜에서도 Composer를 사용할 수 있지만, 사용 횟수에 제한이 있다. Pro 플랜부터 충분한 사용량이 제공되며, 에이전트 모드는 Pro 이상에서 원활하게 사용할 수 있다.

Composer가 기존 Git 히스토리를 망가뜨리지는 않나요?

Composer의 변경 사항은 일반적인 파일 편집과 동일하게 처리된다. Composer가 파일을 수정하면 에디터에서 Unsaved 상태가 되고, 개발자가 저장한 뒤 직접 Git에 커밋한다. Composer 자체가 Git 작업을 수행하지는 않는다. 단, 에이전트 모드에서 git 명령을 포함하는 요청을 하면 별개다.

한 번에 몇 개 파일까지 수정할 수 있나요?

기술적으로는 명확한 파일 수 제한이 없지만, 실질적으로는 5~10개 파일이 최적이다. 그 이상이 되면 토큰 한도와 AI의 주의력 분산으로 품질이 저하된다. 20개 이상의 파일을 수정해야 한다면 여러 세션으로 나누는 것을 권장한다.

Composer와 .cursorrules의 관계는 무엇인가요?

.cursorrules 파일은 프로젝트 루트에 위치하는 설정 파일로, Cursor의 모든 AI 기능(Tab, Chat, Composer)이 참조한다. 코딩 컨벤션, 프로젝트 구조 규칙, 선호하는 라이브러리 등을 여기에 명시하면 Composer가 이를 반영한 코드를 생성한다.

에이전트 모드에서 실행한 명령을 되돌릴 수 있나요?

터미널 명령은 실행된 즉시 효력이 발생하므로, Composer의 “거부” 기능으로는 되돌릴 수 없다. 패키지 설치는 package.json에서 제거 후 재설치하면 되고, 파일 변경은 Git으로 복원할 수 있다. 중요한 작업 전에 항상 커밋을 해두는 것이 최선의 방어책이다.

Composer 세션을 저장하거나 공유할 수 있나요?

현재 Composer 세션 자체를 파일로 내보내는 기능은 제공되지 않는다. 다만 Composer의 대화 기록은 History 탭에서 확인할 수 있으며, 이전 세션으로 돌아가 이어서 작업하는 것이 가능하다.

Composer에서 이미지나 디자인 파일을 참조할 수 있나요?

Cursor Composer는 이미지 입력을 지원한다. 디자인 목업 이미지를 드래그 앤 드롭하거나 클립보드에서 붙여넣으면 AI가 이미지를 분석해서 그에 맞는 UI 코드를 생성한다. Figma 디자인을 스크린샷으로 캡처해서 붙여넣는 방식이 실무에서 자주 활용된다.