Cursor의 Composer 모드로 멀티파일 리팩토링 자동화하기

배경

Next.js 14 프로젝트의 /pages/api 디렉토리를 App Router의 Route Handler로 마이그레이션하는 작업을 진행했다. 단순 변환이지만 파일이 20개가 넘다보니 수작업으로 하기엔 실수 여지가 많았다.

Cursor의 Composer 모드가 멀티파일 편집에 강점이 있다는 이야기를 듣고 실전 투입해봤다.

Composer 모드 활용

1차 시도: 너무 포괄적인 요청

처음엔 "pages/api 폴더의 모든 파일을 app/api의 route.ts로 변환해줘"라고 요청했다. 결과는 참담했다. 파일 구조는 만들어졌지만 각 엔드포인트마다 다른 미들웨어, 에러 핸들링 로직이 제각각 변환되거나 누락됐다.

2차 시도: 단계별 지시

접근을 바꿔서 명확한 룰을 먼저 제시했다.

1. pages/api/users/[id].ts → app/api/users/[id]/route.ts
2. req, res → NextRequest, NextResponse
3. 기존 미들웨어 withAuth는 그대로 유지
4. 에러 핸들링은 try-catch + NextResponse.json 패턴 사용

이렇게 변환 규칙을 명시하니 일관성이 확보됐다. 3개 파일로 테스트 후 전체 적용했다.

효과적이었던 패턴

파일 범위 명시: "users 관련 API만" 같은 식으로 범위를 제한하니 context window 문제가 줄었다.

예시 제공: 첫 파일을 직접 변환해서 "이런 형태로"라고 보여주니 나머지도 동일 패턴으로 처리됐다.

diff 확인 습관: Composer가 수정한 내용을 바로 커밋하지 않고 git diff로 검토했다. 의도와 다르게 변경된 부분이 10% 정도 있었다.

아쉬운 점

TypeScript 타입 import 경로를 일부 잘못 수정하는 경우가 있었다. 특히 barrel export를 사용하는 경우 @/types/api를 @/types/api/users로 바꾸는 등 과도하게 구체화했다.

이런 부분은 결국 수동으로 검토하고 수정했다. AI 도구를 쓰더라도 코드 리뷰는 필수다.

결론

단순 반복 변환 작업에서 Composer는 확실히 시간을 아껴줬다. 20개 파일을 혼자 했으면 반나절 걸렸을 작업을 2시간만에 끝냈다.

다만 "AI가 알아서 해주겠지" 기대보단, 명확한 룰을 제시하고 검증하는 과정이 더 중요했다. 도구는 좋아졌지만 결국 개발자의 판단이 핵심이다.