Claude Code + Cursor 하이브리드 워크플로 도입기

도입 배경

컴포넌트팀은 동시에 3~5개의 클라이언트 프로젝트를 진행하는 아웃소싱 개발사 특성상, 각 프로젝트의 코드 스타일·도메인·기술 스택이 모두 달랐습니다. 2025년 하반기까지는 Cursor 단일 도구로 운영했지만, 다음과 같은 한계가 누적됐습니다.

대규모 리팩터링·마이그레이션 작업에서 Composer 프롬프트를 10개 이상 쪼개야 했음
클라이언트별 컨벤션을 매번 채팅 컨텍스트로 다시 주입해야 하는 비효율
백그라운드 작업(테스트 실행, 의존성 업데이트, 문서화)을 사람이 직접 트리거해야 함
Tab 자동완성에 의존하는 사이 "AI가 짜준 코드를 검토 없이 머지"하는 사고가 한 번 발생

이를 해결하기 위해 다음 4가지 요구사항을 만족하는 워크플로가 필요했습니다.

프로젝트별 컨벤션을 도구가 자동으로 읽어들이는 컨텍스트 격리
단일 작업 내에서 다중 파일 편집 → 테스트 → 커밋까지 자율 실행
인터랙티브 편집(빠른 피드백)과 위임형 작업(긴 자율 실행)의 분리
클라이언트별 비용을 측정·청구 가능한 사용량 추적

여러 조합을 검토한 결과 Cursor Composer 2 + Claude Code Opus 4.7 하이브리드 구성이 가장 적합했습니다. 2026년 기준 가장 생산적인 개발자들은 단일 도구를 고르지 않고 두 도구를 조합해 쓰며, Cursor를 일상 편집에 두고 Claude Code를 복잡 작업에 분배하는 패턴이 표준으로 자리 잡았습니다. (Nxcode)

워크플로 개요

작업을 두 도구에 분배하는 기준은 다음과 같이 정리했습니다.

Cursor Composer 2 — "수렴(convergence)" 모드

일상적인 컴포넌트 작성, JSX 스타일링, 인라인 리팩터링
디자인 핸드오프 직후의 마크업 작업 (Tab 자동완성이 가장 빠름)
PR 리뷰 시 in-editor diff 비교, 부분 수정 제안
디버깅 중 실시간 컨텍스트 추적

Claude Code Opus 4.7 — "탐색(exploration)" 모드

다중 파일 리팩터링, 라이브러리 마이그레이션, 아키텍처 변경
E2E 테스트 작성·실행·실패 자동 수정 루프
깃 워크트리 기반 병렬 작업(예: 브랜치 A에서 백엔드, 브랜치 B에서 프론트 동시 진행)
CLAUDE.md·Skills 기반의 클라이언트별 컨벤션 자동 적용

이 분배는 Cursor가 "느리게 가서 깊이 보는" 작업에 어울리고, Claude Code는 "병렬로 여러 작업을 동시에 굴리는" 위임 작업에 자연스럽다는 워크플로 형태의 차이를 그대로 따른 결과입니다. (Codeaholicguy)

핵심 의사결정 3가지

CLAUDE.md를 클라이언트별 모노레포 루트에 표준화 — 코딩 컨벤션, 금지 패턴, 배포 체크리스트, 도메인 용어 사전을 한 파일에 통합했습니다. Claude Code 세션 시작 시 자동 로드되어, 매번 컨텍스트를 재주입할 필요가 없어졌습니다.
Cursor .cursorrules와 CLAUDE.md를 단일 소스에서 동기화 — 두 도구의 규칙 파일이 어긋나면 같은 코드를 두 도구가 다르게 수정하는 문제가 생겼습니다. 내부 스크립트로 AGENTS.md를 마스터로 두고 두 파일을 자동 생성하도록 정리했습니다.
MCP 서버로 Linear·Sentry·Sanity를 Claude Code에 연결 — 2026년 3월 기준 활성 MCP 서버 1만 개 이상, SDK 월 다운로드 9,700만 건으로 표준화가 완료된 상태입니다. 이슈 트리아지 → 코드 수정 → PR 생성 → 배포 모니터링까지 한 세션에서 끝낼 수 있게 됐습니다. (Truto)

비용은 Cursor Pro $20 + Claude Code Max 5× $100, 1인당 월 $120 수준으로 정착했습니다. 클라이언트 청구 시에는 Claude Code 사용량 로그를 프로젝트 태그로 분류해 정산했습니다.

트러블슈팅: 6개월간 만난 4가지 함정

1. CLAUDE.md와 .cursorrules 규칙 충돌

같은 프로젝트에서 Cursor는 pnpm을, Claude Code는 npm을 쓰는 현상이 발생했습니다.

원인: 초기에 두 파일을 수동으로 관리하면서, 한쪽 파일에만 규칙이 추가되고 다른 쪽은 누락되는 케이스가 누적됐습니다. 결과적으로 같은 코드베이스에서 lockfile이 두 개 생성되는 사고가 일어났습니다.

해결: AGENTS.md를 단일 진실 공급원(SSOT)으로 두고, tools/sync-agent-rules.ts 스크립트로 .cursorrules와 CLAUDE.md를 자동 생성하도록 변경했습니다. 커밋 훅으로 두 파일이 직접 수정되는 것을 차단했습니다.

2. 병렬 에이전트 깃 충돌

Claude Code의 Agent Teams 기능으로 백엔드·프론트엔드를 동시에 작업시켰더니, 공유 파일(예: types/index.ts)에서 머지 충돌이 빈번하게 발생했습니다.

원인: 두 에이전트가 같은 워킹 디렉터리에서 동시에 파일을 수정하면서, 한쪽의 변경사항을 다른 쪽이 덮어쓰는 race condition이 발생했습니다.

해결: git worktree add로 에이전트별 분리된 작업 디렉터리를 만들고, 공유 타입 파일은 사전에 "owner agent"를 지정해 단일 에이전트만 수정하도록 워크플로 규칙을 추가했습니다. 머지는 사람이 직접 검토 후 진행하는 단계를 의무화했습니다.

3. Cursor "Auto" 모드의 모델 선택 불투명성

동일한 프롬프트인데 어떤 날은 Composer 2, 어떤 날은 Opus 4.7이 응답하면서 결과 품질·응답 속도가 들쭉날쭉했습니다. 클라이언트 데모 직전에 응답이 느려져 곤란한 상황도 발생했습니다.

원인: Cursor의 Auto 모드는 모델을 자동으로 라우팅하면서 크레딧 풀에서 차감하는데, 어떤 모델이 선택될지 사전에 알 수 없는 구조였습니다. (Prodmgmt)

해결: 클라이언트 데모·프로덕션 코드 작업에는 Auto 모드를 끄고, 작업 종류별로 모델을 명시적으로 고정하는 내부 가이드를 만들었습니다. 단순 자동완성은 Composer 2, 복잡한 추론은 Opus 4.7, 빠른 답변은 Sonnet 4.6으로 분기했습니다.

4. AI 생성 코드의 한글 변수명·주석 깨짐

Claude Code가 백그라운드에서 자율 실행할 때, 한글 변수명(예: 사용자정보)이나 한글 주석을 영어로 자동 번역해버리는 케이스가 있었습니다.

원인: 모델이 "코드 품질 개선" 휴리스틱으로 식별자를 영문화하는 경향이 있고, 클라이언트 도메인 용어(예: 의료·법률)가 영어 번역으로 의미가 왜곡되는 문제가 있었습니다.

해결: CLAUDE.md에 "기존 한글 식별자·주석은 절대 번역·변경하지 말 것" 규칙을 명시하고, PR 검증 단계에 한글 식별자 diff를 별도로 표시하는 GitHub Actions 체크를 추가했습니다. 도메인 용어 사전(예: "수가 = medical fee schedule")을 컨텍스트 파일에 포함시켜 영문 주석이 필요한 경우의 정확도도 같이 확보했습니다.

#ClaudeCode #Cursor #AI개발도구 #워크플로

도입 배경