뉴스

Cursor로 설계부터 마무리까지, 레거시 마이그레이션 해봤습니다

📝 아티클 핵심 요약

배경 및 위기 상황: 담당자 퇴사로 중단된 채 방치된 레거시 프로젝트였습니다. 인수인계와 문서가 전무한 상태에서 단 3개월 내에 론칭해야 하는 악조건이었습니다.
해결책 (Cursor AI 활용): 모두가 꺼리는 상황에서 작성자는 자원하여 프로젝트를 맡았습니다. 이후 AI 코드 에디터 Cursor의 핵심 기능들(Rules, Skills, Subagent, Hooks)을 공식 문서 메커니즘에 기반해 세팅하고, 설계부터 마무리까지 한 흐름으로 적용했습니다.
과정의 효율성: 본래 마이그레이션은 복잡하고 손이 많이 가는 작업이지만, Cursor의 능력을 활용한 덕분에 다른 업무와 병행하면서도 매우 수월하게 진행할 수 있었습니다.
최종 결과: 기존 레거시 프로젝트가 ‘AI 친화적인 구조’로 완벽하게 재정비되었습니다. 그 결과, 향후 새로운 변경 사항이 생겼을 때의 대응 속도까지 획기적으로 개선되는 성과를 얻었습니다.

💡 마이그레이션에 대한 인사이트 개발 세계에서 마이그레이션은 “잘 돌아가면 건드리지 마라(If it works, don’t touch it)”는 격언이나 파악하기 힘든 난해함, 낮은 가성비 때문에 기피되는 경향이 있습니다. 하지만 작성자는 과거의 뼈저린 마이그레이션 경험과 현재의 AI 도구(Cursor)를 결합하여, 두렵고 피하고 싶은 레거시 청산 작업을 빠르고 효율적인 프로세스로 혁신할 수 있음을 보여줍니다.

작성자는 방치된 레거시 코드를 최신 환경으로 성공적으로 옮기기 위해 Cursor의 핵심 기능 4가지(Rules, Skills, Subagent, Hooks)를 공식 문서의 메커니즘에 기반하여 유기적으로 설계하고 활용했습니다.

🛠️ Cursor 핵심 기능 활용법

Rules (규칙 설정): AI의 뼈대와 가이드라인 구축
- 활용: 프로젝트 전반에 적용될 기술 스택, 팀의 코딩 컨벤션, 디렉토리 구조 및 마이그레이션 원칙을 명확히 정의합니다. (주로 .cursorrules 파일을 활용)
- 효과: AI가 구식 라이브러리를 사용하거나 팀의 컨벤션에 어긋나는 엉뚱한 코드를 생성하는 ‘할루시네이션(환각)’을 방지합니다. AI가 항상 정해진 규칙 안에서 일관성 있는 결과물을 내도록 통제합니다.
Skills (스킬/컨텍스트): AI의 지식과 능력 확장
- 활용: Cursor가 레거시 코드의 전체 문맥(Context)을 파악하고, 최신 프레임워크의 공식 문서(Docs)를 참조하도록 연결합니다.
- 효과: “이 라우터를 Next.js 페이지로 바꿔줘”라고 지시했을 때, AI가 프로젝트 내 파일 간의 종속성을 완벽히 이해하고 최신 레퍼런스를 바탕으로 정확도 높은 코드 변환을 수행하게 만듭니다.
Subagent (서브에이전트): 복잡한 작업의 분할 및 단계별 실행
- 활용: 거대하고 막막한 마이그레이션 작업을 한 번에 처리하게 두지 않고, 작고 관리 가능한 단계(예: 의존성 업데이트 → 라우팅 마이그레이션 → UI 컴포넌트 재작성)로 쪼개어 실행합니다.
- 효과: AI가 방대한 작업량 때문에 문맥을 잃어버리는 현상을 방지합니다. 각 에이전트가 뚜렷한 목표 하나에 집중하게 만들어 단계별 완성도와 안정성을 높입니다.
Hooks (훅): 자동화된 검증 및 피드백 루프
- 활용: AI가 코드를 생성하거나 수정한 직후에 린터(Linter), 타입 체커(Type Checker), 테스트 코드 등이 자동으로 실행되도록 연결합니다.
- 효과: 변환된 코드가 기존 시스템을 망가뜨리지는 않는지 즉각적으로 검증합니다. 에러가 발생하면 AI가 에러 로그를 읽고 스스로 코드를 수정하는 ‘자동 피드백 사이클’을 형성하여 작업자의 검토 시간을 대폭 줄여줍니다.

💡 핵심 요약 작성자의 마이그레이션 성공 비결은 AI를 단순한 ‘코드 생성기’가 아니라, Rules로 규칙을 가르치고, Skills로 똑똑하게 만들며, Subagent로 일을 체계적으로 시키고, Hooks로 꼼꼼히 검증하는 ‘든든한 동료’로 세팅한 데 있습니다.

Cursor로 마이그레이션하는 방식

1. Rules (규칙 설정): AI의 헌법 제정

AI가 프로젝트 코드를 작성할 때 절대적으로 지켜야 하는 뼈대를 만듭니다.

파일 위치 및 이름: 프로젝트 최상단 루트에 .cursorrules 파일을 생성합니다. (최신 버전의 Cursor에서는 .cursor/rules/ 폴더 안에 여러 개의 .mdc 파일로 쪼개어 관리하기도 합니다.)
형식: Markdown 또는 일반 텍스트
작성 내용 예시:

# 프로젝트 기본 규칙
- 사용 스택: Next.js 14 (App Router), TypeScript, Tailwind CSS
- 스타일 가이드: 
  - 컴포넌트 이름은 PascalCase, 함수 및 변수 이름은 camelCase를 사용한다.
  - TypeScript에서 `any` 타입 사용은 엄격히 금지하며, 명확한 타입을 정의한다.
- 마이그레이션 원칙:
  - 기존 레거시의 클래스형 컴포넌트는 반드시 함수형 컴포넌트와 React Hooks로 변환한다.
  - 기존 주석의 의도는 최대한 살리되, 코드가 스스로 설명되도록 변수명을 명확히 한다.

2. Skills (스킬/컨텍스트): 지식 주입 및 참조

Cursor에게 특정 작업에 필요한 지식(레거시 코드의 구조나 최신 공식 문서)을 주입하는 방법입니다. 별도의 스킬 설정 파일이 있다기보다는 문서화 파일과 Cursor의 @ 멘션 기능을 유기적으로 활용합니다.

파일 위치 및 이름: /docs/tech-specs.md 등 임의의 마크다운 문서
형식: Markdown
활용 방법:
1. 최신 API 명세서나 사내 마이그레이션 가이드를 마크다운으로 정리해 둡니다.
2. Cursor의 채팅창(Chat)이나 컴포저(Composer)에서 @ 기호를 입력합니다.
3. @docs/tech-specs.md 파일을 호출하거나, 특정 레거시 파일(@LegacyComponent.js)을 직접 멘션하여 AI가 두 코드를 대조해가며 변환하도록 지시합니다.
4. (팁) Cursor 설정(Settings) > Features > Docs에서 자주 쓰는 프레임워크의 공식 문서 URL을 아예 등록해두고 @로 불러올 수도 있습니다.

3. Subagent (작업 분할): 마이그레이션 플랜과 Agent 모드

마이그레이션 같은 대규모 작업은 AI에게 한 번에 “다 바꿔줘”라고 하면 문맥을 잃고 실패(할루시네이션)합니다. 사람이 ‘작업 지시서’를 만들고, Cursor의 Composer(Agent 모드)에게 단계별로 실행하도록 통제해야 합니다.

파일 위치 및 이름: 프로젝트 최상단에 migration-plan.md 파일 생성
형식: Markdown (체크리스트 형태)
작성 내용 예시:

# 마이그레이션 단계별 플랜

- [ ] 1단계: `package.json`의 구형 의존성 패키지를 최신 버전으로 업데이트 및 설치
- [ ] 2단계: `src/routes/` 폴더의 구형 라우팅을 Next.js `app/` 디렉토리 구조로 이전
- [ ] 3단계: `src/components/` 내의 레거시 UI를 Tailwind CSS 기반으로 재작성

활용 방법: Cursor Composer(단축키 Ctrl+I 또는 Cmd+I)를 열고, “현재 @migration-plan.md 파일의 1단계를 실행해 줘”라고 지시합니다. 완료되면 체크박스를 표시하고 다음 단계를 지시하여 서브에이전트처럼 부립니다.

4. Hooks (자동화 및 검증): 터미널 피드백 루프

AI가 코드를 짠 직후에 기존 시스템을 망가뜨리지 않았는지 즉각적으로 검증하는 시스템입니다. 이는 Cursor 전용 파일이 아니라, 기존 개발 환경의 검증 도구를 Cursor 터미널과 연동하는 방식입니다.

파일 위치 및 이름: package.json
형식: JSON
작성 내용 예시:

{
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx",
    "typecheck": "tsc --noEmit",
    "test": "jest"
  }
}

활용 방법 (AI 자동 피드백):
1. AI가 코드를 생성한 뒤, Cursor 내장 터미널에서 npm run typecheck를 실행합니다.
2. 에러가 발생하면, 터미널 에러 메시지 옆에 나타나는 “Add to Chat” 버튼을 클릭하거나 단축키(Cmd/Ctrl + Shift + M)를 누릅니다.
3. 에러 로그가 그대로 AI 채팅창에 복사되며, “이 에러를 분석하고 코드를 수정해 줘”라고 지시하여 AI가 스스로 버그를 고치는 피드백 루프를 완성합니다.

결과적으로 Cursor AI의 강력함은 단순한 코드 생성이 아니라, .cursorrules로 통제하고, @로 문맥을 주고, 플랜 문서로 작업 단위를 쪼개며, 터미널로 검증하는 4박자를 갖출 때 비로소 완성됩니다.

참고사이트: https://yozm.wishket.com/magazine/detail/3605/

뉴스

뉴스