Cursor Composer 리팩토링 자동화 — 실전 10개 레포에서 돌려본 결과 정리

Cursor Composer, 솔직히 리팩토링에 쓸만해요?

결론부터 말하면 파일 5개 이상 건드리는 리팩토링엔 Composer가 확실히 빠릅니다. Next.js 프로젝트, Python 백엔드, Node CLI 툴처럼 성격이 다른 레포에 차례로 돌려보면 공통으로 드러나는 패턴이 있어요.

정리하면 이래요.

• 반복이 많고 규칙이 뚜렷한 작업일수록 Composer 쪽이 압도적으로 유리해요
• 레거시 타입 에러가 얽힌 레포는 롤백하게 되는 경우가 생겨요
• Accept 한 커밋은 한 번에 여러 파일이 바뀌니까 리뷰 습관이 중요해요
• 테스트가 있는 모듈일수록 되돌리기가 쉬워서 시도 부담이 낮아요

이 글에서는 성공한 워크플로우, 삽질한 부분, 그리고 저만의 프롬프트 템플릿 3종을 정리할게요.

1. 성공 시나리오 — 매개변수 객체화 리팩토링

Express 라우터 수십 개가 req.query.page, req.query.size 식으로 개별 파라미터를 받고 있었어요. 타입스크립트 전환 중이었는데, 이걸 PaginationOptions 하나로 묶고 싶었거든요.

Composer에 이렇게 입력했어요.

routes/ 아래 모든 파일에서 req.query 페이지네이션 파라미터를
PaginationOptions 객체로 통일해줘.
- page: number (default 1)
- size: number (default 20)
- sort: string | undefined
별도 types/pagination.ts 파일 만들고 re-export 해줘.

결과: 대부분 파일은 바로 Accept 했고, 커서 기반 페이지네이션처럼 구조가 다른 몇 개만 Reject 했어요. 수동으로 했다면 반나절은 붙잡았을 작업이 한 세션에 정리됐어요.

2. 삽질한 부분 — 레거시 타입 에러가 폭발한 사례

반대로 안 맞았던 케이스도 있어요. Express 3.x 기반 레거시 레포를 한 번에 "Express 4 + TypeScript로 마이그레이션" 시켰더니, 빌드 에러가 무더기로 쏟아졌어요. 타입 매칭이 반쯤 된 상태로 커밋이 올라와서 되돌리는 데도 한참 걸렸어요.

교훈은 이거예요.

• 파일 3~5개 단위로 끊어서 맡기기
• 테스트가 없으면 Composer 실행 전에 스냅샷 테스트 먼저 작성
• .cursorrules에 "코드 깨지면 빌드 로그 같이 출력해" 규칙 넣기

두 번째 시도에서는 라우터 디렉토리 하나씩 끊어서 돌렸고, 빌드 에러가 손으로 바로 잡을 수 있는 수준까지 줄었어요. 작업 범위 좁히기가 Composer 성패의 90%예요.

3. 제가 매일 쓰는 프롬프트 템플릿 3종

템플릿 A — 반복 패턴 추출

이 디렉토리에서 3번 이상 반복되는 로직을 공통 함수로 분리해줘.
- 함수 이름은 동작 중심 (예: calculateTax, not taxHelper)
- 유닛 테스트 1개씩 같이 생성
- 기존 호출부는 새 함수 호출로 교체

템플릿 B — 타입 안전성 강화

이 파일들에서 any 타입을 찾아서 구체 타입으로 바꿔줘.
- 외부 API 응답이면 Zod 스키마 생성
- 내부 객체면 interface 정의
- runtime 유효성 검증 코드 같이 추가

템플릿 C — 테스트 커버리지 보강

최근 3개월 커밋된 파일 중 테스트 없는 함수에 대해
Jest 테스트 작성해줘.
- happy path 1개 + edge case 2개씩
- mock은 MSW 사용
- 기존 테스트 스타일과 동일하게

이 세 개로 리팩토링 요청의 80% 정도가 커버돼요. 나머지는 건별로 즉석에서 작성해요.

4. 어떤 작업에서 효과가 큰가

개인 프로젝트 기준으로 작업 성격별 체감을 정리해봤어요.

정리하면 패턴이 반복되고 판단 기준이 명확한 작업일수록 Composer가 잘 맞아요. 반대로 성능 튜닝처럼 맥락 판단이 필요한 작업은 사람이 방향을 잡아준 뒤 맡겨야 안전해요.

Pro 요금은 월 20달러인데, 리팩토링을 자주 돌리는 사람이라면 아끼는 시간만으로 값을 한다는 후기가 많아요. 다만 체감 효과는 레포 상태와 작업 성격에 따라 편차가 크니까, 한 달 써보고 본인 기준으로 판단하는 게 좋아요. 최신 요금제와 요청 한도는 Cursor 공식 가격 페이지에서 확인하세요.

5. Composer와 같이 쓰면 좋은 도구 3가지

• Git worktree: 리팩토링 브랜치 동시에 여러 개 실험할 때
• Biome: Composer가 만든 코드 포맷팅 자동 정리 (포맷팅 속도가 빠른 편)
• pre-commit hook: Composer 커밋 전에 타입 체크·테스트 강제

Biome은 특히 Composer가 만든 코드에 들쑥날쑥한 공백이나 따옴표 통일할 때 최고예요. VSCode 익스텐션으로 설치하면 저장 시 자동 포맷팅 돼요.

Composer가 잘 맞는 사람, 아직 이른 사람

잘 맞는 경우부터 보면 이래요.

• 같은 패턴이 여러 파일에 흩어져 있어서 손으로 고치면 지루하기만 한 작업이 많은 사람
• 테스트가 어느 정도 깔려 있어서 결과를 빠르게 검증할 수 있는 프로젝트
• 코드 리뷰 습관이 잡혀 있어서 diff를 훑는 데 부담이 없는 사람
• 브랜치를 따로 파고 실험하는 흐름이 익숙한 사람

반대로 아직 이른 경우도 분명히 있어요.

• 테스트가 하나도 없고 수동 QA에만 의존하는 레포. 되돌릴 기준이 없어서 사고가 나면 원인 추적이 어려워요
• 도메인 규칙이 코드가 아니라 담당자 머릿속에만 있는 프로젝트. AI가 그 규칙을 알 방법이 없으니 그럴듯하게 틀린 코드가 나와요
• 배포 주기가 짧고 롤백 절차가 정리되지 않은 서비스. 리팩토링은 일정에 여유가 있을 때 하는 게 안전해요

실행 전에 준비하면 사고가 줄어드는 3가지

첫째, 작업 브랜치를 따로 파세요. Composer는 여러 파일을 한 번에 바꾸기 때문에, 메인 브랜치에서 바로 돌리면 되돌릴 때 손이 많이 가요.

둘째, 현재 상태를 먼저 커밋해두세요. 커밋하지 않은 수정본이 섞이면 어디까지가 사람이 쓴 코드이고 어디부터 AI가 쓴 코드인지 구분이 안 돼요.

셋째, 성공 기준을 문장으로 적어두세요. "빌드 에러 0, 기존 테스트 전부 통과, 공개 API 시그니처 변경 없음" 같은 식이에요. 프롬프트에 그대로 넣기도 좋고, 리뷰할 때 판단 기준이 되기도 해요.

리뷰할 때 꼭 확인하는 체크포인트

diff를 훑을 때 다음 순서로 보면 놓치는 게 적어요.

1. 삭제된 줄 먼저 보기. 추가된 코드보다 조용히 사라진 예외 처리가 더 위험해요
2. 에러 처리와 로깅이 그대로 남아 있는지 확인. 리팩토링 과정에서 가장 자주 증발하는 부분이에요
3. 기본값 확인. 매개변수를 객체로 묶을 때 기존 기본값이 바뀌면 런타임에서만 티가 나요
4. 테스트 파일 변경 여부. 테스트가 통과하도록 테스트 쪽을 고쳐버리는 경우가 있어요
5. import 정리. 안 쓰는 import는 린트가 잡아주지만, 순환 참조가 새로 생기면 빌드 단계에서야 드러나요

처음 쓰는 사람이 자주 하는 실수

• 한 번에 너무 많이 맡기기. 범위를 좁힐수록 성공률이 올라가요
• Accept를 몰아서 누르기. 파일 단위로 끊어 확인해야 문제 지점을 특정할 수 있어요
• 프롬프트에 맥락을 안 주기. 프로젝트 규칙은 .cursorrules에 적어두면 매번 설명하지 않아도 돼요
• 커밋 메시지를 대충 쓰기. 어떤 프롬프트로 만든 변경인지 남겨두면 나중에 재현하기 쉬워요

이런 실수는 대부분 "한 번에 끝내고 싶다"는 마음에서 나와요. Composer는 빠르지만 판단까지 대신해주지는 않아요. 사람이 범위를 정하고 결과를 확인하는 두 지점만 지키면 나머지 반복 작업은 도구가 알아서 처리해줍니다. 처음 한 주는 본인이 가장 잘 아는 모듈에서만 돌려보면서 이 레포가 어떻게 반응하는지 감을 잡는 걸 추천해요.

Composer로 첫 리팩토링 시작하는 순서

1. 테스트 한 개라도 있는 모듈부터 시작 (롤백이 쉬워요)
2. 프롬프트에 성공 기준을 명시 ("빌드 에러 0, 기존 테스트 통과")
3. Diff 뷰에서 파일 3~5개까지만 Accept, 나머진 다음 커밋
4. 커밋 메시지에 Composer 프롬프트 원문 남기기 (재현성 확보)

Cursor 0.46 업데이트 정리와 같이 읽으면 Cursor로 뭘 더 할 수 있는지 감이 와요. 리팩토링 자동화는 AI 에이전트 활용 사례 중에서도 투자 대비 수익이 제일 빠른 영역이에요.

오늘 바로 해볼 3가지

1. 본인 레포 중 파일 5~10개 정도 되는 모듈 하나 고르기
2. 위 템플릿 A로 반복 패턴 추출 요청
3. diff 뷰에서 한 파일씩 리뷰 → Accept/Reject 기준 잡기

30분이면 첫 커밋이 나와요. 한 번 경험해보면 "이걸 왜 지금까지 수동으로 했지" 싶어요. 처음부터 크게 욕심내지 말고, 실패해도 부담 없는 모듈에서 한 사이클을 끝까지 돌려보는 게 가장 빠른 학습 방법이에요.