Cursor Composer: 실제로 작동하는 다중 파일 편집
대부분의 Cursor 사용자는 일반 채팅에 머물러요. 함수를 요청하고, 출력을 복사하고, 파일에 붙여넣고, 반복하죠. 작은 것에는 괜찮아요. 하지만 한 기능을 추가하려면 다섯 개 파일을 변경해야 할 때, 그 워크플로우는 망가져요.
Composer는 Cursor가 이 문제에 대한 답이에요. 별도의 패널에서 원하는 변경사항을 설명하면, Cursor는 한 번에 여러 파일에 걸쳐 편집을 제안해요. 검토하고, 각 변경사항을 수락하거나 거부하고, 다음으로 넘어가면 돼요. 복사-붙여넣기 없이. 컨텍스트 전환 없이.
이 가이드에서는 Cursor 포럼의 실제 워크플로우를 다룰게요. 마케팅 용어 없이. 실제로 작동하는 것만.
Composer vs 일반 채팅: 실제 차이점
일반 채팅은 Q&A예요. 질문하고, Cursor가 답해요. 코드를 파일로 옮기는 건 여전히 사용자의 몫이에요.
Composer는 행동이에요. 목표를 설명하면, Cursor가 어떤 파일을 건드려야 할지, 무엇을 변경해야 할지 파악해요. diff를 보여주고, 사용자가 무엇을 적용할지 결정하죠.
| 기능 | 일반 채팅 | Composer |
|---|---|---|
| 코드 제안 | 예 | 예 |
| 파일 직접 편집 | 아니요 | 예 |
| 다중 파일 변경 | 아니요 | 예 |
| 적용 전 diff 표시 | 아니요 | 예 |
| 체크포인트/롤백 | 아니요 | 예 |
| 가장 적합한 경우 | 질문, 단일 코드 조각 | 리팩토링, 기능, 일괄 업데이트 |
핵심 기능은 체크포인트예요. Composer는 변경 전에 스냅샷을 저장해요. 편집이 잘못되면 한 번의 클릭으로 체크포인트로 되돌릴 수 있어요. 일반 채팅에는 이런 안전장치가 없어요.
Cmd/Ctrl + I를 누르거나 왼쪽 사이드바의 Composer 아이콘을 클릭하세요. 채팅과 별도의 패널이에요 — 둘을 헷갈리지 마세요.
Composer를 사용할 때
한 개 이상의 파일에 걸친 작업에서 Composer가 빛을 발해요. 일반적인 시나리오는 다음과 같아요:
- 리팩토링 — 컴포넌트 간 prop 이름 변경, 공유 유틸리티 추출
- 기능 작업 — 새 API 엔드포인트 추가에는 라우트, 컨트롤러, 서비스, 테스트 파일이 필요해요
- 패턴 업데이트 — 모든 곳에서
fetch를 커스텀apiClient로 전환 - 타입 변경 — 열 개 파일에 영향을 미치는 인터페이스 업데이트
- 가져오기 정리 — 모듈 구조 재구성
채팅에서 코드를 복사-붙여넣기 하는 파일이 두 개를 넘어간다면, 멈추고 Composer를 사용하세요.
빠른 질문, 한 줄짜리, 또는 "이 정규식 설명해줘" — 일반 채팅이 더 빨라요. Composer에는 오버헤드가 있어요. 다중 파일 작업용으로만 사용하세요.
실제 워크플로우 1: 크로스 파일 리팩토링
types.ts에 User 타입이 있어요. displayName 필드를 추가하면서 이름이 혼란스러워졌으니 name을 fullName으로 바꾸고 싶어요.
영향을 받는 파일:
src/types.ts— 타입 정의src/components/UserCard.tsx— 이름 표시src/components/UserProfile.tsx— 이름 표시src/api/users.ts— 해당 필드를 수신/전송하는 API 호출src/lib/validators.ts— 사용자 검증을 위한 Zod 스키마
1단계: Composer 열기 (Cmd/Ctrl + I).
2단계: 변경사항 설명:
User 타입의 `name` 필드를 `fullName`으로 이름 변경하고 코드베이스 전체의 모든 사용처를 업데이트해. 동작은 변경하지 마 — 이건 순수한 이름 변경이야.
3단계: 제안된 diff를 검토하세요. Composer는 변경사항이 강조된 각 파일을 보여줘요. 다음을 확인하세요:
- 사용자와 관련된
name만 이름 변경되었는지(다른nameprop은 아님) - API 계층이 여전히 올바른 데이터를 수신/전송하는지
- 로직 변경이 끼어들지 않았는지
4단계: 파일별로 수락하거나 거부하세요. 한 파일이 이상하면 해당 파일만 거부하고 수동으로 수정하세요.
Composer는 때때로 과도하게 확장할 수 있어요. 컨텍스트가 비슷해 보이면 관련 없는 컴포넌트의 name prop을 이름 변경할 수도 있어요. 수락 전에 항상 diff를 훑어보세요.
실제 워크플로우 2: 여러 파일에 걸친 기능 추가
앱에 "사용자 역할"을 추가하고 싶어요. 관리자는 추가 UI 요소를 보고 추가 API 엔드포인트에 접근할 수 있어요.
관련 파일:
src/types.ts— User에role: 'user' | 'admin'추가src/api/auth.ts— JWT 페이로드에 역할 포함src/components/Navbar.tsx— 관리자에게만 관리자 링크 표시src/components/AdminPanel.tsx— 새 컴포넌트src/hooks/useAuth.ts—isAdmin플래그 노출src/middleware/auth.ts— 관리자 역할을 확인하는 새 미들웨어
1단계: Composer를 열어요.
2단계: 소원이 아니라 계획을 알려주세요:
앱에 사용자 역할을 추가해:
1. src/types.ts의 User 타입에 `role: 'user' | 'admin'` 추가
2. src/api/auth.ts의 로그인 응답을 업데이트해서 JWT 페이로드에 역할 포함
3. src/hooks/useAuth.ts에 `isAdmin` 계산값 추가
4. Navbar.tsx를 업데이트해서 isAdmin이 true일 때 "Admin" 링크를 조건부로 표시
5. src/components/AdminPanel.tsx에 플레이스홀더 관리자 대시보드 생성
6. JWT 역할을 확인하는 requireAdmin 미들웨어를 src/middleware/auth.ts에 생성
코드베이스의 기존 패턴을 사용해. 다른 API 파일과 동일한 에러 처리 스타일을 따라줘.
3단계: Composer가 다중 파일 diff를 생성해요. 각 파일을 검토하세요.
4단계: 새 AdminPanel.tsx가 이상하면 거부하고 나머지는 유지하세요. Composer 편집은 세분화되어 있어요.
Composer가 코딩하기 전에 계획을 요약해달라고 하세요. "편집하기 전에 변경할 파일과 이유를 목록으로 알려줘." 이렇게 하면 오해를 일찍 잡을 수 있고 비용도 들지 않아요.
실제 워크플로우 3: API 호출 일괄 업데이트
프론트엔드에 흩어진 원시 fetch 호출로 시작했어요. 이제 인증 헤더, 에러 처리, 기본 URL이 설정된 커스텀 apiClient가 있어요. 모든 것을 마이그레이션해야 해요.
파일: 잠재적으로 수십 개의 API 호출 지점.
1단계: apiClient가 존재하고 한 파일에서 올바르게 가져와지는지 먼저 확인하세요. Composer는 참조 구현이 있을 때 더 잘 작동해요.
2단계: Composer를 열고 작업 범위를 지정하세요:
src/의 모든 원시 `fetch` 호출을 src/lib/apiClient.ts의 `apiClient`로 교체해.
규칙:
- 기존의 `apiClient.get`, `.post`, `.put`, `.delete` 메서드 사용
- 수동 JSON.stringify와 response.json() 처리 제거 — apiClient가 이를 처리함
- 동일한 엔드포인트 경로 유지
- apiClient에 이미 없는 커스텀 헤더는 보존
src/api/ 디렉토리부터 시작하고, 필요하면 src/hooks/ 다음에 진행해.
3단계: 배치별로 검토하세요. 보지 않고 20개 파일을 한 번에 수락하지 마세요. Composer는 좋지만 완벽하지는 않아요.
4단계: 수락 후 테스트 스위트를 실행하세요. diff가 깨끗해 보여도 타입 오류와 런타임 동작이 달라질 수 있어요.
50개 이상의 파일이 있다면 청크로 나누세요. "먼저 src/api/를 마이그레이션해." 그 다음 "src/hooks/를 마이그레이션해." 큰 배치는 검토하기 어렵고 실수하기 쉬워요.
Composer + 에이전트 모드: 강력한 조합
Composer와 에이전트 모드는 서로 다른 문제를 해결해요. Composer는 원하는 것을 아는 타겟팅된 다중 파일 편집용이에요. 에이전트 모드는 AI가 탐색하고, 명령을 실행하고, 해결책을 찾아야 하는 개방형 작업용이에요.
하지만 둘은 함께 작동해요.
패턴: 에이전트가 계획, Composer가 실행
변경 범위를 파악하기 위해 에이전트 모드를 사용하세요:
React Context에서 Zustand로 상태 관리를 마이그레이션하고 싶어. AuthContext를 사용하는 모든 파일과 각 파일에 필요한 변경사항을 목록으로 알려줘.
에이전트 모드가 코드베이스를 검색하고 분석을 제공해요. 그런 다음 Composer를 열어 파일별로 변경사항을 실행하고, 완전한 diff 검토와 함께 적용하세요.
패턴: 리팩토링은 Composer, 검증은 에이전트
큰 Composer 리팩토링 후, 에이전트 모드로 전환하세요:
테스트 스위트를 실행하고 최근 리팩토링으로 인해 발생한 깨진 가져오기나 타입 오류를 수정해.
에이전트 모드가 정리를 처리하는 동안 Composer 변경사항을 검토하세요.
에이전트 모드에서 Cursor는 때때로 다중 파일 편집을 위해 내부적으로 Composer를 열어요. 이를 직접 제어할 수는 없지만, 에이전트 세션 중에 Composer 스타일의 diff가 나타나는 걸 볼 수 있어요. 동일한 방식으로 검토하세요.
흔한 실수와 피하는 방법
1. 모호한 프롬프트
나쁜 예: "인증을 더 좋게 만들어줘."
좋은 예: "User 타입에 role 필드를 추가하고, 로그인 API를 업데이트해서 JWT에 포함시키고, 관리자 사용자를 위해 Navbar에 관리자 링크를 표시해줘."
구체성이 놀라움을 줄여줘요.
2. 검토 없이 수락
Composer diff는 깔끔해 보이지만, 다음을 할 수 있어요:
- 유지하고 싶은 코멘트 삭제
- 관련 없는 줄의 포맷팅 변경
- 한 파일의 엣지 케이스 놓침
항상 diff를 훑어보세요. 30초면 되고, 재작업을 막을 수 있어요.
3. 한 번에 너무 많은 파일
Composer는 10~15개 파일은 잘 처리해요. 그 이상은 컨텍스트 창이 부담을 받고 품질이 떨어져요. 큰 작업은 논리적인 청크로 나누세요.
4. 체크포인트를 사용하지 않음
큰 Composer 세션을 시작하기 전에 체크포인트 버튼을 누르세요. 한 번의 클릭이에요. 세션이 잘못되면 한 번의 클릭으로 되돌릴 수 있어요. 이걸 건너뛸 이유가 없어요.
Composer 체크포인트는 Cursor 내부에 있어요. Git을 대체하지 않아요. 큰 Composer 작업 전에 Git에 커밋하세요. 두 가지 안전장치를 모두 사용하세요.
5. 변경 후 타입 오류 무시
Composer 편집은 대략 90%의 경우 컴파일돼요. 나머지 10%는 특히 이름 변경이나 인터페이스 변경 시 미묘한 타입 불일치를 도입할 수 있어요. 변경사항을 수락한 후 tsc나 린터를 실행하세요.
빠른 참조
| 동작 | 단축키 |
|---|---|
| Composer 열기 | Cmd/Ctrl + I |
| 변경 수락 | Cmd/Ctrl + Y |
| 변경 거부 | Cmd/Ctrl + N |
| 체크포인트 생성 | Composer 패널의 체크포인트 아이콘 클릭 |
| 체크포인트로 되돌리기 | 체크포인트 옆의 되돌리기 아이콘 클릭 |
요약
- 다중 파일 편집에는 Composer를, 질문에는 일반 채팅을 사용하세요.
- 정확히 원하는 것을 설명하세요. 파일 경로와 제약 조건을 포함하세요.
- 수락 전 모든 diff를 검토하세요.
- 큰 세션 전에 체크포인트를 생성하세요.
- 큰 작업은 청크로 나누세요.
- Composer와 에이전트 모드를 조합하세요: 에이전트가 탐색하고, Composer가 실행해요.
Composer는 마법이 아니에요. 다중 파일 작업에서 복사-붙여넣기 수고를 덜어주는 도구예요. 잘 쓰면 시간을 아껴줘요. 부주의하게 쓰면 정리 작업을 만들어요. 차이는 검토 단계에서 나와요 — 건너뛰지 마세요.