Windsurf Cascade 모드로 레거시 API 리팩토링 자동화하기

배경

사내 결제 API 서버가 Express 4 기반으로 3년째 운영 중이었다. 성능 개선과 타입 안정성 강화를 위해 Fastify + TypeScript로 마이그레이션을 결정했는데, 70개 이상의 엔드포인트를 수작업으로 옮기기엔 시간이 부족했다.

Windsurf Cascade 활용

Cascade 모드는 여러 파일을 동시에 편집하면서 컨텍스트를 유지하는 것이 강점이었다. 작업 순서는 이렇게 진행했다.

1. 라우트 변환 패턴 학습

먼저 한 개 라우트를 직접 변환한 예시를 보여주고, 나머지를 자동화했다.

// Express (기존)
app.post('/payments', validatePayment, async (req, res) => {
  const result = await paymentService.create(req.body);
  res.json(result);
});

// Fastify (변환)
fastify.post('/payments', {
  schema: paymentSchema,
  handler: async (request, reply) => {
    const result = await paymentService.create(request.body);
    return result;
  }
});

Cascade에게 "routes 폴더의 모든 파일을 이 패턴으로 변환해줘"라고 요청했더니 15분 만에 초안이 완성됐다.

2. 미들웨어 변환

Express 미들웨어를 Fastify 플러그인으로 바꾸는 작업도 자동화했다. 인증 로직, 로깅, 에러 핸들링 등 7개 미들웨어를 한 번에 변환하면서 각 파일의 import 경로까지 자동 수정됐다.

3. 스키마 생성

Fastify는 JSON Schema 기반 검증을 권장한다. 기존 요청 검증 로직을 보고 Zod 스키마를 생성하도록 했는데, 타입 정의도 함께 export하는 패턴을 학습시켜서 일관성을 유지했다.

체감한 장점

• 컨텍스트 유지: 여러 파일 수정 시 이전 변환 패턴을 기억함
• 점진적 수정: 한 번에 모든 파일을 바꾸지 않고, 폴더 단위로 검토하며 진행 가능
• 테스트 생성: 변환된 라우트마다 Jest 테스트 템플릿까지 자동 생성

한계점

복잡한 에러 처리나 트랜잭션 로직은 수동 검토가 필요했다. 특히 DB 커넥션 풀 설정이나 Redis 연동 부분은 기존 코드를 참고하되 직접 수정해야 했다.

결과

2주 예상했던 작업을 4일로 단축했다. 남은 시간에 성능 테스트와 모니터링 대시보드 구축에 집중할 수 있었다. Windsurf는 단순 반복 작업보다 패턴 변환에 특히 효과적이라는 걸 확인했다.