Cursor Composer 완벽 가이드: 여러 파일 편집 팁과 실전 사례

Cursor를 3개월이나 쓰고 나서야 줄곧 제대로 활용하지 못하고 있었다는 사실을 깨달았습니다.

예전에는 기능 하나를 수정하려면 컴포넌트, API, 타입 정의, 테스트, 설정까지 파일 5개를 건드려야 했습니다. 저는 Chat에 파일별로 하나씩 묻고 코드를 하나씩 복사해 붙여 넣었습니다. 마우스는 파일 사이를 오가고 손가락은 Cmd+C와 Cmd+V 사이를 쉴 새 없이 움직였습니다. 지치는 일이었습니다.

어느 날 지나가던 동료가 제가 작업하는 모습을 보고 화면을 3초쯤 바라보더니 물었습니다. “왜 Composer를 안 써요?”

“네?”

“Cmd+I를 누르면 뜨는 창이요. 요구 사항을 한 문장으로 설명하면 AI가 수정할 파일을 자동으로 찾아서 전부 바꿔 줘요.”

저는 그 자리에서 멍해졌습니다.

동료가 직접 보여 줬습니다. Composer를 열고 관련 파일 몇 개를 @로 참조한 뒤 “이 사용자 로그인 로직이 이메일 인증을 지원하도록 바꿔 줘”라고 입력하고 Enter를 눌렀습니다. AI는 몇 초 동안 생각하더니 컴포넌트, API, 타입 정의를 한 번에 모두 수정했습니다. 10분 만에 끝났습니다.

저라면 1시간이 걸렸을 일입니다.

그 순간 저는 지난 3개월 동안 Cursor 기능의 20%만 쓰고 있었다는 사실을 깨달았습니다. 페라리를 몰면서 1단 기어만 쓰고 있었던 셈입니다.

Composer란 무엇이며 왜 필요한가요?

Composer와 Chat의 본질적인 차이

먼저 비유로 설명하겠습니다.

Chat은 옆에 앉아 질문에 답해 주는 AI 컨설턴트와 같습니다. “이 코드를 어떻게 개선할 수 있나요?”라고 물으면 조언을 해 주고, 실제 수정은 직접 해야 합니다.

Composer는 AI 작업팀입니다. “이 건물의 모든 창문을 통유리창으로 바꿔 주세요”라고 말하면 직접 작업한 뒤 “완료했습니다. 확인해 주세요”라고 합니다.

이것이 본질적인 차이입니다. 하나는 컨설턴트이고 다른 하나는 작업팀입니다.

구체적인 차이는 다음 표와 같습니다.

“대화 기록이 저장되지 않음”이 보이시나요? 제가 겪은 가장 큰 문제였으며 뒤에서 피하는 방법을 자세히 설명하겠습니다.

Composer의 3가지 핵심 기능

기능 1: 여러 파일에 걸친 이해

Chat은 현재 열어 둔 파일만 볼 수 있습니다. Composer는 프로젝트 전체를 볼 수 있습니다.

예를 들어 “사용자 로그인 기능을 추가해 줘”라고 말해 보겠습니다. Chat은 “구체적으로 어떤 파일을 수정해야 하나요?”라고 묻지만, Composer는 “Login.tsx, auth.ts, user.types.ts, api/auth.ts, App.tsx, 이 5개 파일을 수정해야 합니다”라고 바로 알려 줍니다.

컴포넌트, 타입 정의, API, 라우트가 어디에 있는지 알고 모두 수정해 줍니다.

기능 2: 프로젝트 단위 수정

Chat이 코드를 수정하면 수동으로 복사해 붙여 넣어야 합니다. Composer는 수정 내용을 파일에 바로 적용하므로 Accept나 Reject만 누르면 됩니다.

이 차이는 Chat이 인테리어 도면을 건네주는 것과 Composer가 인테리어 공사를 끝낸 뒤 검수를 요청하는 것의 차이와 같습니다.

기능 3: 지능형 추론(Agent 모드)

Agent 모드를 켜면 Composer는 다음 작업을 할 수 있습니다.

• shell 명령 실행(예: npm install, git status)
• 코드베이스 전체 검색(특정 함수를 사용하는 모든 위치 찾기)
• 의존 관계 자율 분석
• 파일 생성 또는 삭제

Agent 모드는 작업팀에 현장 책임자를 붙이는 것과 같습니다. 스스로 판단하고 도구도 찾을 수 있습니다. 하지만 “과도한 공사”를 할 가능성도 커지므로 뒤에서 제어 방법을 설명하겠습니다.

반드시 Composer를 사용해야 하는 3가지 상황

상황 1: 새 기능 개발(여러 파일 관련)

요구 사항: 댓글 기능 추가.

Chat 방식:

1. Chat에 어떤 파일을 수정해야 하는지 묻기
2. Chat이 파일 5개를 제시
3. 파일을 하나씩 열기
4. Chat에 “Comments 컴포넌트를 작성해 줘”라고 요청
5. 코드를 복사해 파일에 붙여 넣기
6. 다시 “댓글 API를 작성해 줘”라고 요청
7. 복사 후 붙여 넣기
8. 5번 반복

정말 지칩니다.

Composer 방식:

1. Composer 열기(Cmd+I)
2. “사용자가 댓글을 작성하고 삭제하고 볼 수 있는 댓글 기능을 추가해 줘”라고 입력
3. Enter 누르기
4. AI가 수정할 파일을 자동으로 찾고 모두 수정
5. diff를 확인하고 Accept 클릭

10분이면 끝납니다.

상황 2: 코드 리팩터링

요구 사항: 상태 관리를 Redux에서 Zustand로 마이그레이션.

Chat 방식: 사실상 완료하기 어렵습니다. 20개가 넘는 파일을 하나씩 수동으로 수정해야 하므로 빠뜨리거나 잘못 수정하기 쉽습니다.

Composer 방식:

@src/store
@src/components

Redux store를 Zustand로 마이그레이션하세요.
1. 기존 state 구조 유지
2. API 유지
3. redux 의존성 제거

Agent 모드를 켜면 AI가 의존 관계를 분석하고, 파일을 수정하고, 실행 가능 여부까지 테스트합니다. 20분이면 끝납니다.

상황 3: 일괄 수정

요구 사항: 오류 처리 방식을 통일하고 모든 API 호출에 try-catch 추가.

Chat 방식: 파일을 하나씩 수정해야 하므로 빠뜨리기 쉽습니다. 무엇을 수정했고 무엇을 수정하지 않았는지 직접 기억해야 합니다.

Composer 방식:

@src/api

모든 API 호출에 통일된 오류 처리를 추가하세요.
- try-catch로 감싸기
- 오류 메시지 형식 통일
- 오류 로그 기록

파일 15개를 한 번에 처리할 수 있습니다.

Composer와 Chat: 5초 선택법

이제 Composer와 Chat의 차이를 알았습니다. 하지만 실제로 코드를 작성할 때는 여전히 “Cmd+L을 눌러야 할까, Cmd+I를 눌러야 할까?” 고민할 수 있습니다.

3단계로 판단해 5초 만에 결정하는 방법을 소개합니다.

선택 과정

1단계: 관련 파일이 몇 개인가요?

• 파일 1개 → 계속 판단
• 파일 2개 이상 → Composer

정말 간단합니다. 여러 파일에 걸친 작업이면 Composer를 사용합니다.

2단계: 질문인가요, 코드를 수정하려는 것인가요?

• 질문(학습, 이해, 디버깅) → Chat
• 코드 수정(생성, 변경, 리팩터링) → Composer

Chat은 컨설턴트이고 Composer는 작업팀입니다. 기억하셨나요?

3단계: 변경 범위가 큰가요?

• 작은 변경(코드 몇 줄) → Chat + Cmd+K
• 큰 변경(모듈 전체) → Composer

변수 이름을 바꾸거나 주석을 추가하는 정도라면 Cmd+K면 충분합니다. Composer까지 사용할 필요는 없습니다.

Chat에 적합한 4가지 상황

상황 1: 빠른 질의응답

나: “이 코드에 bug가 있나요?”
Chat: “네, 12번째 줄에서 배열 인덱스가 범위를 벗어납니다.”

즉시 답을 받을 수 있습니다. 코드를 수정할 필요 없이 확인만 하고 싶을 때 Chat이 완벽합니다.

상황 2: 학습과 이해

나: “이 알고리즘의 원리를 설명해 주세요.”
Chat: “이것은 퀵 정렬이며 핵심 아이디어는...”

새로운 지식을 배우는 것은 Chat의 강점입니다. 차근차근 설명하고 예시도 들어 줍니다.

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

지금 시작 →광고

상황 3: 단일 파일 디버깅

나: “이 함수를 최적화해 주세요.”
Chat: “memoization으로 결과를 캐시할 수 있습니다...”

직접 수정하면 되므로 Composer의 완전 자동화는 필요하지 않습니다.

상황 4: 코드 리뷰

나: “여기에 어떤 잠재적인 문제가 있나요?”
Chat: “15번째 줄은 null을 처리하지 않고, 28번째 줄에는 메모리 누수 위험이 있습니다...”

코드를 검토할 때 Chat은 많은 문제를 찾아낼 수 있습니다.

Composer에 적합한 4가지 상황

상황 1: 새 기능 개발

여러 파일에 걸친 기능 구현입니다. 앞에서 설명했으므로 반복하지 않겠습니다.

상황 2: 코드 리팩터링

광범위한 구조 조정입니다. 예를 들면 다음과 같습니다.

• 큰 파일 분리
• 작은 파일 병합
• 디렉터리 구조 재구성
• 명명 규칙 통일

이런 작업은 Chat으로 처리하기 어렵습니다.

상황 3: 의존성 마이그레이션

라이브러리나 프레임워크 교체입니다. 예를 들면 다음과 같습니다.

• axios → fetch
• moment.js → dayjs
• styled-components → Tailwind CSS
• Redux → Zustand

수십 개의 파일이 관련되므로 Composer가 활약할 무대입니다.

상황 4: 일괄 수정

여러 곳의 비슷한 코드를 통일해 수정합니다. 예를 들면 다음과 같습니다.

• 모든 console.log를 logger로 변경
• 모든 var를 const로 변경
• 모든 클래스 컴포넌트를 함수 컴포넌트로 변경

비교 사례 3가지

사례 1: API 호출 방식 변경

작업: 모든 axios를 fetch로 변경.
관련 파일: 15개.

Chat: 파일을 하나씩 다뤄야 하므로 빠뜨리기 쉽습니다. 무엇을 수정했고 무엇을 수정하지 않았는지 직접 기억해야 합니다. 피곤합니다.

Composer: @src/api 모든 axios를 fetch로 변경이라는 지시 하나로 AI가 일괄 수정하고 사용자는 diff만 검토하면 됩니다.

결론: Composer

사례 2: 함수 하나 디버깅

작업: 총액 계산 함수의 bug 찾기.
관련 파일: 1개.

Chat: 코드를 붙여 넣으면 바로 답합니다. “12번째 줄의 세율 계산이 잘못됐으며 total * 0.1이어야 합니다.”

Composer: Composer를 열고 분석, 수정, 적용을 기다리는 것은 지나치게 무거워 시간 낭비입니다.

결론: Chat

사례 3: 사용자 권한 시스템 추가

작업: RBAC 권한 제어 구현.
관련 파일: 10개 이상(컴포넌트, 미들웨어, 데이터베이스, API).

Chat: 사실상 완료하기 어렵습니다. Chat에 하나씩 묻고 하나씩 수정하면서 로직의 일관성도 직접 보장해야 합니다.

Composer(Agent 모드): AI가 전체 아키텍처를 이해한 뒤 미들웨어 생성, API 수정, 컴포넌트 업데이트, 권한 검사를 자동으로 수행합니다. “역할 기반 권한 시스템을 구현해 주세요. 관리자는 생성·삭제·수정·조회가 가능하고 일반 사용자는 조회만 할 수 있어야 합니다”라고 말하면 됩니다.

결론: Composer(Agent)

Composer를 올바르게 시작하는 방법

초기 설정(3단계)

Cursor를 설치했다고 바로 Composer를 사용하지 말고 먼저 설정해 보세요.

1단계: 모델 선택

Composer에는 Claude 3.7 Sonnet을 권장합니다.

그 이유는 다음과 같습니다.

• 강력한 추론 능력: 복잡한 여러 파일의 관계를 이해함
• 낮은 오류율: 코드를 잘못 수정할 가능성이 낮음
• 뛰어난 여러 파일 이해 능력: 함께 수정해야 할 파일을 파악함

o1이나 o1-mini는 Composer 기능을 지원하지 않으므로 사용하지 마세요. Cursor가 다른 모델로 자동 전환되어 예상보다 결과가 좋지 않을 수 있습니다.

2단계: Agent 모드 활성화(선택 사항)

Cursor Settings → Beta → Agent에서 설정합니다.

활성화하면 Composer는 다음 작업을 할 수 있습니다.

• shell 명령 실행(npm install, git status)
• 코드베이스 검색(Cmd+Enter로 특정 함수를 사용하는 모든 위치 찾기)
• 파일 생성/삭제
• 프로젝트 구조 자율 분석

Agent 모드는 AI에 도구 상자를 주는 것과 같습니다. 직접 작업할 수 있지만 “과도한 공사”를 할 가능성도 커지므로 뒤에서 제어 방법을 설명하겠습니다.

3단계: 요금 정책 이해

• 무료 버전: Composer 기능이 제한되며 하루에 몇 번만 요청 가능
• Pro 버전: 월 500회 premium 요청으로 충분함
• Business 버전: 무제한

사용량이 많다면 Pro 버전을 권합니다. 저는 Pro를 사용하며 한 달에 약 300~400회 요청합니다.

인터페이스 구성 살펴보기

Composer의 인터페이스는 다음과 같습니다.

┌─────────────────────────────────┐
│  Composer  [Normal] [Agent]     │  ← 모드 전환
├─────────────────────────────────┤
│  📝 입력창(요구 사항 설명)        │
│  @ 파일/폴더/코드 참조           │
├─────────────────────────────────┤
│  💬 대화 기록                    │
│  📄 파일 diff 미리보기           │
│  ✅ Accept  ❌ Reject            │
└─────────────────────────────────┘

오른쪽 위에서 Normal 모드와 Agent 모드를 전환할 수 있습니다.

아래쪽의 diff 미리보기가 매우 중요합니다. 파일별 변경 내용을 볼 수 있습니다. Accept All을 바로 누르지 마세요. 뒤에서 이 문제를 자세히 다루겠습니다.

@ 참조 기능 활용법

@ 기호는 Composer의 핵심 기능입니다. 다양한 대상을 참조할 수 있습니다.

@Files: 특정 파일 참조

@src/components/Header.tsx
이 컴포넌트를 반응형 디자인으로 바꿔 주세요.

AI는 이 파일 하나만 수정해야 한다는 것을 알기 때문에 다른 곳을 함부로 건드리지 않습니다.

@Folders: 폴더 전체 참조

@src/utils
이 유틸리티 라이브러리를 리팩터링하고 기능별로 파일을 분리해 주세요.

AI는 폴더 안의 모든 파일을 살펴보고 전체 구조를 이해한 뒤 리팩터링합니다.

@Code: 코드 블록 참조

코드를 선택한 다음 Cmd+I를 누르면 자동으로 참조됩니다.

@[선택한 함수 코드]
이 함수의 성능을 최적화해 주세요.

작은 범위의 최적화에 특히 적합합니다.

@Web: 웹페이지 내용 참조

@https://docs.react.dev/reference/react/useEffect
React 공식 문서의 모범 사례에 따라 이 effect를 리팩터링해 주세요.

AI는 웹페이지 내용을 읽고 문서의 설명에 따라 코드를 수정합니다. 저는 AI가 공식 문서에 맞춰 코드를 수정하게 할 때 이 기능을 자주 사용합니다. 오류가 생길 가능성을 줄일 수 있습니다.

@Docs: 프로젝트 문서 참조

@README.md
문서 설명에 따라 이 기능을 구현해 주세요.

프로젝트에 규칙 문서가 있다면 @로 참조해 AI가 규칙에 맞춰 작업하게 할 수 있습니다.

@Codebase: 코드베이스 전체 검색

Cmd+Enter를 누르고 다음과 같이 입력합니다.

localStorage를 사용하는 모든 위치를 찾아 IndexedDB로 바꿔 주세요.

Agent 모드에서 AI는 프로젝트 전체를 검색하고 관련 코드를 모두 찾아 함께 수정합니다.

Normal 모드와 Agent 모드

두 모드의 차이는 무엇일까요?

Normal 모드:

• 명확한 작업에 적합
• 지정한 파일만 AI가 수정
• 제어하기 쉽고 다른 파일이 의도치 않게 바뀔 가능성이 낮음
• 속도가 빠름
• Token 사용량이 적음

Agent 모드:

• 복잡하고 추론이 필요한 작업에 적합
• AI가 자율적으로 코드를 검색하고 명령을 실행하며 파일을 생성할 수 있음
• 더 똑똑하지만 변경 범위가 예상을 벗어날 수 있음
• 속도가 느림
• Token 사용량이 많음

선택 방법:

간단한 작업 → Normal. 예: “이 컴포넌트의 스타일을 바꿔 줘”, “오류 처리를 추가해 줘”.

복잡한 리팩터링 → Agent. 예: “Redux를 Zustand로 마이그레이션해 줘”, “권한 시스템을 구현해 줘”.

잘 모르겠다면 → Normal을 먼저 사용하고 잘되지 않을 때 Agent를 사용합니다.

저는 시간의 80%는 Normal, 20%는 Agent를 사용합니다. 대부분은 Normal이면 충분하며 Agent는 너무 무거울 수 있습니다.

여러 파일 편집의 5가지 황금 원칙

이 부분이 핵심입니다. 여러 문제를 직접 겪은 뒤 정리한 5가지 원칙이며, 그대로 따르면 문제의 90%를 피할 수 있습니다.

원칙 1: 작업 분할

❌ 잘못된 예:

“프로젝트 전체를 리팩터링하고 TypeScript로 바꾸고 성능을 최적화하고 테스트를 추가해 주세요.”

이런 지시를 받으면 Composer는 혼란스러워합니다. 어디서 시작하고 무엇을 먼저 해야 할지 알기 어렵습니다. 결국 수정 내용이 엉망이 되어 2시간 동안 되돌려야 할 수도 있습니다.

✅ 올바른 방법:

대화를 4번으로 나눕니다.

1번째: “src/utils 디렉터리의 모든 파일을 TypeScript로 바꿔 주세요.”
2번째: “utils에 단위 테스트를 추가해 주세요.”
3번째: “Header 컴포넌트의 성능을 최적화해 주세요.”
4번째: “API 호출 로직을 리팩터링하고 오류 처리를 통일해 주세요.”

작은 목표 하나를 마칠 때마다 git commit을 한 번 수행합니다. 명확하고 제어하기 쉬우며 되돌리기도 쉽습니다.

왜 나눠야 하나요?

• AI의 이해가 어긋나는 것을 방지(한 번에 너무 많이 말하면 핵심을 놓침)
• 단계별 검토가 쉬움(diff가 작아 문제를 찾기 쉬움)
• 오류 발생 시 쉽게 되돌릴 수 있음(해당 단계만 되돌리고 다른 단계에는 영향 없음)
• token 사용량 감소(작업이 작으면 AI가 덜 고민하므로 비용이 적음)

제 경험상 Composer 대화 한 번에 관련되는 파일은 10개를 넘기지 않는 것이 좋습니다. 10개를 넘으면 나눕니다.

원칙 2: 범위 명시

@ 참조를 사용해 파일 범위를 명확히 지정합니다.

예를 들어 사용자 관련 기능을 수정한다면 다음과 같이 입력합니다.

@src/components/User
@src/types/user.ts
@src/api/user.ts

사용자 관련 API를 RESTful에서 GraphQL로 변경해 주세요.

그러면 AI는 이 3곳만 수정하고 다른 곳은 건드리지 말아야 한다는 것을 알 수 있습니다.

범위를 명확히 하지 않으면 어떻게 될까요? AI가 다른 파일까지 임의로 수정할 수 있습니다. 예를 들어 “API 호출 방식을 통일해 줘”라고만 말하면 서드파티 라이브러리의 API까지 바꿔 프로젝트가 망가질 수 있습니다.

장점:

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

요금 보기 →광고

• AI가 다른 파일을 잘못 수정하지 않음
• 변경을 제어하기 쉬움
• 돌발 상황 감소

저는 이제 Composer를 사용할 때 가장 먼저 관련 파일을 @로 참조합니다. 습관으로 만들어 보세요.

원칙 3: 파일별 검토

Composer가 수정을 끝내도 Accept All을 바로 누르면 안 됩니다.

Accept All이 매력적이라는 것은 압니다. AI가 파일 20개를 수정했을 때 클릭 한 번으로 전부 적용하면 시원합니다.

하지만…

실제로 겪은 사례:

한 번은 Composer에 “모든 console.log를 커스텀 logger로 바꿔 줘”라고 요청했습니다.

Composer는 파일 30개를 수정했습니다.

저는 확인도 하지 않고 바로 Accept All을 눌렀습니다.

결과는 다음과 같았습니다.

• 서드파티 라이브러리의 console.log까지 삭제됨
• 일부 디버깅 코드가 잘못 삭제됨
• 프로젝트를 실행할 수 없게 됨

되돌리고 조사하고 수동으로 복구하는 데 1시간이 걸렸습니다.

올바른 과정:

1. 각 파일의 diff 미리보기를 클릭합니다.
2. 변경 내용을 한 줄씩 확인합니다.
3. 문제가 없음을 확인한 뒤 개별적으로 Accept합니다.
4. 문제를 발견하면 즉시 Reject하고 요구 사항을 다시 설명합니다.

물론 느립니다. 파일 20개를 수정하면 diff도 20번 확인해야 합니다. 하지만 사고의 90%를 피할 수 있습니다.

저는 이제 Composer가 작업을 끝내면 커피 한 잔을 준비하고 앉아서 천천히 검토합니다. 서두르면 안 됩니다.

원칙 4: 즉시 커밋

작은 작업이 하나 끝날 때마다 즉시 git commit합니다.

# Composer 수정 한 번을 완료한 후
git add .
git commit -m "feat: 迁移用户 API 到 GraphQL"

왜 중요한가요?

Composer 대화 기록은 저장되지 않습니다. 페이지를 새로고침하면 사라집니다.

파일 10개를 수정했지만 commit하지 않은 상태에서 페이지가 멈춰 대화가 사라졌다고 생각해 보세요. 무엇을 수정했는지, 어디까지 했는지 기억나지 않아 처음부터 다시 해야 할 수 있습니다.

하지만 단계마다 commit하면 다음과 같은 장점이 있습니다.

• 문제가 생겼을 때 쉽게 되돌릴 수 있음(git reset --hard HEAD)
• 각 변경을 추적하기 쉬움(git log에서 변경 기록 확인)
• Composer 대화가 사라져도 괜찮음(코드는 이미 저장됨)

제 작업 흐름은 Composer 수정 → diff 검토 → Accept → git commit입니다. 몸에 밸 때까지 반복합니다.

원칙 5: 컨텍스트 유지

문제:

Composer는 대화 기록을 저장하지 않습니다. 페이지를 새로고침하면 이전 대화가 사라집니다.

“방금 하던 리팩터링을 계속해 줘”라고 말해도 AI는 “어떤 리팩터링인지 모르겠습니다”라고 합니다.

해결 방법:

방법 1: 중요한 대화를 스크린샷으로 저장

복잡한 작업을 시작하기 전에 Composer 지시문을 캡처합니다. 작업 도중 네트워크가 끊겨도 스크린샷을 보고 무엇을 하려 했는지 떠올릴 수 있습니다.

방법 2: 복잡한 작업은 먼저 Chat에서 계획한 뒤 Composer로 실행

Chat 대화 기록은 저장됩니다. Chat에서 AI와 방안을 논의하고 확정한 뒤 Composer로 실행할 수 있습니다.

예를 들면 다음과 같습니다.

Chat 대화:
나: “axios를 fetch로 마이그레이션하고 싶은데 무엇을 주의해야 하나요?”
AI: “오류 처리, 인터셉터, 타입 정의에 주의해야 합니다...”
나: “좋아요. 마이그레이션 계획을 작성해 주세요.”
AI: “1단계...2단계...3단계...”

그런 다음 계획에 따라 Composer로 하나씩 실행합니다. Chat에는 계획이 계속 남아 있으므로 Composer 대화가 사라져도 괜찮습니다.

방법 3: 프로젝트 README에 변경 의도 기록

저는 README에 “리팩터링 기록” 섹션을 유지합니다.

## 2026-01-10 리팩터링 기록
- 작업: axios를 fetch로 마이그레이션
- Composer 지시문: “모든 axios 호출을 네이티브 fetch API로 바꾸되 동일한 오류 처리 로직을 유지해 주세요.”
- 관련 파일: src/api/*.ts
- 결과: 파일 15개 마이그레이션 성공

나중에 프로젝트를 다시 볼 때 왜 이렇게 수정했는지 알 수 있습니다.

Composer에서 흔히 겪는 7가지 문제와 예방법

이 부분에서는 제가 직접 겪은 문제를 모두 정리합니다. 같은 문제를 피하는 데 활용해 보세요.

문제 1: 대화 기록이 저장되지 않음

문제:

Composer 대화는 페이지를 새로고침하면 사라집니다.

수정 도중 페이지가 멈추거나 실수로 탭을 닫거나 Cursor가 종료되면 이전 대화가 모두 사라집니다.

예방법:

✅ 중요한 지시문을 스크린샷으로 저장(휴대전화로 찍어도 됨)
✅ 먼저 Chat에서 계획해 생각의 흐름을 기록
✅ git commit message에 각 변경의 의도를 기록
✅ 복잡한 작업을 여러 개의 작은 대화로 나눠 완료(대화 한 번에 파일 10개 이하)

문제 2: 파일 업데이트 중단

문제:

Composer가 수정 도중 멈춥니다.

네트워크가 불안정하거나 AI 서비스에 문제가 생겼을 수도 있고, 컴퓨터 팬 소리가 너무 커서 AI가 못 들었을 수도 있습니다(농담입니다).

결국 일부 파일만 수정되고 나머지는 수정되지 않습니다. 프로젝트는 어중간하게 망가진 상태가 됩니다.

예방법:

✅ 수정 전에 git commit(문제가 생기면 바로 되돌리기)
✅ 네트워크 안정성 확인(Composer는 네트워크 의존도가 높으므로 VPN이 불안정할 때는 사용하지 않기)
✅ 작업을 작게 나눠 한 번에 수정하는 파일 수 줄이기(파일이 적으면 업데이트가 빨라 중단될 가능성이 낮음)
✅ git diff로 실제 변경 내용 확인(어떤 파일이 정말 수정되었는지 확인)

저도 업데이트 중단을 두 번 겪었습니다. 처음에는 commit하지 않아 2시간 동안 수동으로 복구했고, 두 번째에는 commit이 있어 git reset으로 1초 만에 되돌렸습니다.

문제 3: 모델 자동 전환

문제:

o1 같은 일부 모델은 Composer를 지원하지 않습니다.

o1을 선택해도 Cursor가 다른 모델로 자동 전환할 수 있습니다. o1을 쓰고 있다고 생각했지만 실제로는 GPT-4o를 사용하게 되어 결과가 기대에 못 미칠 수 있습니다.

예방법:

✅ Claude 3.7 Sonnet으로 고정(Composer와 가장 잘 맞음)
✅ 오른쪽 위의 모델 이름을 직접 확인(선택했다고 해서 그대로 사용 중이라고 단정하지 않기)
✅ Cursor Settings에서 기본 모델 설정

저는 이제 Claude 3.7 Sonnet만 사용합니다. 안정적이고 신뢰할 수 있으며 오류율이 낮습니다.

문제 4: 컨텍스트 유실

문제:

Composer에서 대화를 이어 갑니다.

1번째: “사용자 API를 GraphQL로 바꿔 주세요.”
2번째: “계속해서 댓글 API도 바꿔 주세요.”

그런데 AI가 “어떤 사용자 API인지 모르겠습니다”라고 답합니다.

컨텍스트가 사라진 것입니다.

예방법:

✅ 대화할 때마다 관련 파일을 @로 다시 참조
✅ “이전 변경을 바탕으로 계속…”이라고 명확하게 설명
✅ 필요하면 새 대화를 열고 전체 배경을 다시 설명

저는 이제 대화할 때마다 첫 대화라고 생각하고 배경을 명확히 설명합니다.

문제 5: 파일 검색 실패

문제:

Cmd+Enter를 누르고 “@Codebase axios를 사용하는 모든 위치를 찾아 주세요”라고 입력합니다.

AI는 “찾지 못했습니다”라고 답합니다.

하지만 실제로는 파일 15개에서 axios를 사용하고 있습니다.

예방법:

✅ @Files로 파일을 명시(검색에 의존하지 않음)
✅ .cursorrules와 .gitignore 확인(일부 파일이 제외되었을 수 있음)
✅ 큰 프로젝트에서는 작업을 모듈별로 분할(AI가 프로젝트 전체를 검색하게 하지 않음)

@Codebase 검색은 큰 프로젝트에서 그다지 안정적이지 않습니다. 저는 이제 @Files로 파일을 명확히 지정합니다.

문제 6: 지나치게 공격적인 Agent 모드

문제:

Agent 모드를 켜면 AI가 임의로 다음과 같은 작업을 할 수 있습니다.

• 필요하지 않은 파일 생성
• 중요하다고 생각하는 코드 삭제
• 예상 범위를 벗어난 변경

예를 들어 “사용자 모듈을 리팩터링해 줘”라고 말했더니 AI가 src/user 디렉터리 전체를 삭제하고 다시 만들 수도 있습니다.

예방법:

✅ 복잡한 작업도 먼저 Normal 모드로 시도
✅ Agent 모드는 “의존성 마이그레이션”처럼 명확한 리팩터링 작업에 사용
✅ diff를 파일별로 검토하고 부적절한 변경은 즉시 Reject

Agent 모드는 강력하지만 위험할 수도 있습니다. 저는 의존성 마이그레이션처럼 매우 명확한 작업에만 사용합니다.

문제 7: 디스크 공간 부족

문제:

Composer는 임시 파일을 생성합니다.

디스크 공간이 부족하면 업데이트가 실패합니다. 파일을 절반쯤 수정한 상태에서 “디스크 공간 부족” 오류가 나타납니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

예방법:

✅ node_modules, dist 같은 임시 디렉터리를 정기적으로 정리
✅ 5GB 이상의 여유 공간 확보
✅ df -h로 디스크 사용량 확인

이 문제는 한 번만 겪었지만 원인을 찾기 어려웠습니다. 오류 메시지가 명확하지 않아 한참 조사한 뒤에야 디스크가 가득 찼다는 사실을 알았습니다.

실전 사례: axios를 fetch API로 마이그레이션

이론은 충분히 설명했으니 이제 실전 사례를 살펴보겠습니다.

사례 배경:

• 프로젝트: Next.js 블로그 시스템
• 작업: 모든 axios 호출을 네이티브 fetch API로 변경
• 관련 파일: API 파일 15개
• 예상 시간: 수동 작업은 2시간, Composer는 20분

Composer로 이 작업을 완료하는 방법을 step-by-step으로 보여 드리겠습니다.

1단계: Chat에서 계획

Composer부터 열지 말고 먼저 Chat에서 AI와 논의합니다.

나: 프로젝트의 axios를 모두 fetch API로 바꾸고 싶은데 무엇을 주의해야 하나요?

Chat:
1. fetch의 오류 처리는 axios와 달라 response.ok를 직접 확인해야 합니다.
2. fetch는 기본적으로 4xx/5xx에서 reject하지 않으므로 별도로 처리해야 합니다.
3. Content-Type을 직접 설정해야 합니다.
4. 요청 인터셉터는 커스텀 함수로 구현해야 합니다.

먼저 fetchWrapper 유틸리티 함수를 만드는 것이 좋습니다.

좋습니다. Chat이 방향을 제시했습니다. 유틸리티 함수를 먼저 작성한 뒤 일괄 교체하면 됩니다.

2단계: fetchWrapper 유틸리티 생성

Cmd+I로 Composer를 엽니다.

@src/utils

axios와 유사한 API 래퍼를 구현하는 fetchWrapper.ts 파일을 만들어 주세요.
- JSON 자동 처리
- 통일된 오류 처리
- 인터셉터 지원
- 기존 axios 호출 방식과 호환

Enter를 누릅니다.

Composer는 몇 초 동안 생각한 뒤 꽤 괜찮은 fetchWrapper.ts를 만들었습니다.

다음 항목을 확인했습니다.

• ✅ 타입 정의가 완전함
• ✅ 오류 처리 로직이 올바름
• ✅ API 설계가 합리적임

Accept합니다.

git commit -m "feat: add fetchWrapper utility"

3단계: 모듈별 마이그레이션

파일 15개를 한꺼번에 바꾸지 말고 여러 번으로 나눕니다.

posts와 comments 모듈부터 수정합니다.

@src/api/posts.ts
@src/api/comments.ts
@src/utils/fetchWrapper.ts

posts와 comments의 API 호출을 axios에서 fetchWrapper로 바꾸되, 함수 시그니처와 오류 처리 로직은 그대로 유지하세요.

Enter를 누릅니다.

Composer가 작업을 시작해 파일 3개를 수정했습니다.

4단계: diff 검토

가장 중요한 단계입니다.

파일을 하나씩 확인합니다.

posts.ts:

• import axios가 import { fetchWrapper }로 바뀜 ✅
• axios.get()이 fetchWrapper.get()으로 바뀜 ✅
• 오류 처리 로직 유지 ✅
• 함수 시그니처 유지 ✅

Accept합니다.

comments.ts:

• 변경 내용이 비슷하고 문제없음 ✅

Accept합니다.

fetchWrapper.ts:

• import가 올바르게 참조됨 ✅

5단계: 테스트

npm run dev

브라우저를 열어 posts와 comments 기능을 테스트합니다.

• 게시물 목록 불러오기 ✅
• 게시물 상세 보기 ✅
• 댓글 작성 ✅
• 댓글 삭제 ✅

모두 정상입니다.

git commit -m "feat: migrate posts and comments API to fetch"

6단계: 나머지 모듈 마이그레이션

3~5단계와 같은 방식으로 다음 모듈을 계속 마이그레이션합니다.

• users 모듈
• auth 모듈
• settings 모듈

모듈별 수정이 끝날 때마다 검토하고 테스트하고 commit합니다.

파일 15개를 모두 마이그레이션하는 데 25분이 걸렸습니다.

작업 중 겪은 문제

문제 1: Composer가 서드파티 라이브러리의 axios까지 수정함

처음에는 @Files로 범위를 명확히 지정하지 않아 node_modules 안의 코드까지 수정됐습니다.

해결 방법: “src 디렉터리 안의 코드만 수정하고 node_modules는 수정하지 마세요”라고 다시 설명했습니다.

문제 2: 오류 처리 로직이 사라짐

fetch의 오류 처리는 axios와 다릅니다. 단순히 교체하면 일부 오류가 포착되지 않습니다.

해결 방법: 지시문에 “동일한 오류 처리 로직을 유지하고 response.ok를 직접 확인하세요”라고 명시했습니다.

문제 3: 타입 정의 누락

TypeScript 오류가 발생했으며 fetchWrapper의 타입 정의가 완전하지 않았습니다.

해결 방법: Chat으로 타입 정의를 별도로 생성한 뒤 Cmd+K로 fetchWrapper.ts에 적용했습니다.

최종 결과

✅ 파일 15개 마이그레이션 완료
✅ 모든 API 기능 정상 동작
✅ 총 소요 시간: 25분(디버깅 포함)
✅ 코드 review: 문제없음
✅ 번들 크기 감소: axios는 30KB, fetch는 네이티브 API

수동으로 하면 2시간 정도 걸렸을 것입니다. Composer로는 25분이 걸렸으므로 효율이 5배 높아졌습니다.

경험 요약

1. 복잡한 작업은 먼저 Chat에서 계획합니다.
2. 단계별로 실행하고 각 단계가 끝나면 git commit합니다.
3. @ 참조로 파일 범위를 명확히 지정합니다.
4. diff를 파일별로 검토해 의도하지 않은 변경을 방지합니다.
5. 테스트한 뒤 다음 단계로 넘어갑니다.

이 5가지 방법은 모든 Composer 작업에 적용할 수 있습니다. 기억해 두세요.

결론

솔직히 Composer를 익힌 뒤 제 개발 효율은 최소 3배 높아졌습니다.

예전에는 여러 파일에 걸친 기능을 수정할 때 파일 사이를 오가며 코드를 복사해 붙여 넣었습니다. 오류가 생기거나 빠뜨리기 쉬웠고 피곤했습니다.

이제는 Composer에 지시 하나만 입력하면 AI가 수정할 파일을 자동으로 찾아 모두 처리합니다. 저는 diff를 검토하고 Accept만 누르면 됩니다. 10분이면 끝납니다.

5가지 핵심 원칙을 기억하세요.

1. 여러 파일과 관련됨 → Composer 사용
   여러 파일에 걸친 작업에는 Chat을 쓰며 시간을 낭비하지 마세요.

2. 작업을 작게 나눔 → 한 번에 너무 많이 수정하지 않기
   대화 한 번에 파일 10개를 넘기지 않습니다.

3. 파일별 검토 → Accept All을 바로 누르지 않기
   조금 느려도 사고가 나는 것보다 낫습니다.

4. 즉시 커밋 → 단계가 끝날 때마다 git commit
   Composer 대화는 저장되지 않으므로 코드는 저장해야 합니다.

5. 컨텍스트 유지 → 중요한 대화를 스크린샷으로 저장
   스크린샷, Chat 계획, README 기록을 함께 활용합니다.

단축키 두 개를 기억하세요.

• Cmd/Ctrl + L → Chat(질문)
• Cmd/Ctrl + I → Composer(코드 수정)

5초 선택법:

관련 파일이 몇 개인가요?
 → 1개 → 질문인가요, 코드를 수정하려는 것인가요?
    → 질문 → Chat
    → 코드 수정 → 변경 규모가 큰가요?
       → 작은 변경 → Chat + Cmd+K
       → 큰 변경 → Composer
 → 2개 이상 → Composer

Composer를 두려워하지 마세요.

처음에는 “너무 똑똑해서 제어하기 어렵다”고 느낄 수도 있습니다.

하지만 몇 번 사용해 보면 알게 됩니다. 위의 원칙만 지키면 Composer는 충분히 제어할 수 있고 매우 유용합니다.

지금 해볼 일:

지금 바로 시도해 보세요.

1. Cursor를 열고 Cmd+I를 누릅니다.
2. “변수 일괄 이름 변경”, “코드 스타일 통일” 같은 작은 작업으로 연습합니다.
3. 이 글의 5가지 원칙과 7가지 문제 예방법을 저장해 둡니다.
4. 앞으로 여러 파일을 수정할 일이 생기면 Composer부터 떠올립니다.

Chat만 사용하지 마세요.

Composer야말로 Cursor의 핵심 기능입니다.

직접 사용해 보면 얼마나 강력한지 알 수 있습니다.