Cursor Composer 마스터 가이드 — 멀티파일 에이전트 실전법

Cursor의 Composer는 단순한 채팅창이 아니라 여러 파일을 하나의 작업 단위로 묶어 다루는 편집 모드입니다. 한 함수 수정 같은 단일 파일 작업이 아닌, 컴포넌트 분리·스타일 토큰 일괄 변경·아키텍처 리팩터링 같은 다중 파일 작업에 진가를 발휘합니다. 이 글은 Composer를 효과적으로 쓰는 실전 패턴을 정리합니다.

Composer가 일반 Chat과 다른 점

Cursor에는 두 가지 AI 인터페이스가 있습니다. Chat은 질문에 답변을 텍스트로 주는 방식이고, Composer는 변경 제안을 파일 단위로 조직해서 보여주는 방식입니다. 단순 설명이 필요할 때는 Chat이 빠르고, 실제 코드 변경이 필요할 때는 Composer가 적합합니다.

Composer의 핵심은 다중 파일 변경 검토입니다. AI가 여러 파일을 동시에 수정해야 하는 작업을 하나의 변경 묶음으로 제시하고, 사용자가 diff를 검토한 뒤 전체 또는 일부를 적용할 수 있습니다. 이 검토 단계가 있어 의도와 다른 변경이 자동으로 적용되는 사고를 방지합니다.

좋은 Composer 요청의 패턴

Composer는 목표, 범위, 제약을 분명히 말할수록 결과가 좋아집니다. 단순히 "리팩터링해줘"가 아니라 "components/Card.tsx와 그 사용처 5곳에서 padding을 16px로 통일해줘. 다른 컴포넌트는 건드리지 마"처럼 구체적으로 지정합니다.

작업 범위를 명시할 때는 디렉토리 단위 제한이 효과적입니다. "src/play 폴더는 절대 건드리지 말고 src/ai 폴더만 수정해줘"처럼 명령하면 AI가 의도하지 않은 영역을 변경하는 것을 방지할 수 있습니다. 또한 "새 파일은 src/lib 아래에만 만들어줘" 같은 위치 제약도 자주 활용됩니다.

단계별 작업 분리

큰 작업을 한 번의 Composer 요청으로 처리하면 변경 범위가 광범위해집니다. 여러 단계로 분리하는 것이 안정적입니다. 예를 들어 디자인 토큰 마이그레이션은 다음 순서로 분리합니다.

첫째, 토큰 정의 파일만 수정. 둘째, 컴포넌트 한 카테고리(예: Button)만 새 토큰으로 교체. 셋째, 결과 검토 후 다음 카테고리로 진행. 이 방식은 매 단계마다 빌드와 시각 확인을 끼워 넣을 수 있어, 잘못된 방향으로 가도 빨리 되돌릴 수 있습니다.

검토와 적용 흐름

Composer가 제안한 변경을 받으면 무조건 적용하지 말고 diff를 한 번 훑어봅니다. 특히 의도하지 않은 import 추가, 변수 이름 변경, 타입 캐스팅이 있는지 봅니다. AI는 가끔 부수적인 정리를 함께 시도하는데, 이게 다른 코드의 동작을 미묘하게 바꿀 수 있습니다.

부분 적용도 자주 활용됩니다. 변경 묶음 중 핵심만 적용하고 부수적인 정리는 거부하는 식으로 통제할 수 있습니다. 모든 것을 자동 적용하기보다 의도한 변경만 골라 적용하는 것이 장기적으로 코드 품질을 유지하는 핵심입니다.

자주 쓰는 작업 시나리오

Composer가 잘 처리하는 작업은 명확합니다. 컴포넌트 분리, 디자인 토큰 마이그레이션, API 호출 패턴 변경, 테스트 코드 추가, 타입 안전성 강화 같은 패턴화된 변경입니다. 반대로 비즈니스 로직의 미묘한 의사결정이나 도메인 특화 알고리즘은 사람이 직접 작성하는 것이 더 정확합니다.

복잡한 디버깅도 Composer가 강합니다. "이 컴포넌트에서 무한 렌더링이 발생하는데 원인 찾아서 수정해줘"처럼 구체적인 증상을 알려주면 AI가 관련 파일을 자동으로 탐색하고 원인을 찾아 수정 제안을 만듭니다.

운영 팁

Composer 사용 빈도가 높아지면 .cursorrules 파일을 프로젝트 루트에 두는 것을 권장합니다. 이 파일에 프로젝트 코딩 컨벤션, 금지 패턴, 우선순위 규칙을 적어 두면 매번 Composer 요청에 같은 제약을 반복하지 않아도 됩니다. 팀 작업에서는 일관성 유지에도 도움이 됩니다.

또한 Composer 결과를 git에 자주 커밋하는 습관이 중요합니다. 작은 단위로 커밋해 두면 잘못된 변경이 발견됐을 때 git revert로 빠르게 되돌릴 수 있습니다. AI가 만든 변경이라도 git 히스토리는 결국 사람이 책임지는 영역이라는 점을 잊지 말아야 합니다.