Cursor AI 2025 완전 가이드: Composer 2.0부터 .cursorrules까지 — AI 코딩의 새로운 표준

[Composer 모델 아키텍처 개요]

사용자 프롬프트
    |
    v
컨텍스트 수집 (@file, @folder, @codebase)
    |
    v
Composer 프론티어 모델 (코딩 전용 훈련)
    |
    v
멀티파일 편집 계획 생성
    |
    v
Diff View로 변경사항 표시 + 사용자 리뷰
    |
    v
Accept/Reject → 코드 적용

[Background Agent 워크플로우]

1. 사용자: "이 이슈 해결해줘" (GitHub Issue 링크 제공)
2. Cursor: 클라우드 샌드박스에서 코드베이스 클론
3. Background Agent: 코드 분석 → 수정 → 테스트 실행
4. 결과: PR 자동 생성 (사용자 리뷰 대기)
5. 사용자: PR 확인 후 머지

[크레딧 소비 예시]

Composer 기본 요청:        1 크레딧
Composer 에이전트 요청:    5 크레딧
GPT-4o 채팅:              2 크레딧
Claude 3.5 Sonnet 채팅:   2 크레딧
Tab 자동완성:             0.1 크레딧
인라인 편집 (Cmd+K):      1 크레딧

# 전통적인 자동완성: 변수명/함수명 제안
user.ge  # -> getName, getEmail, getAge 등 제안

# Cursor Tab: 전체 로직 예측
def get_user_profile(user_id):
    # Tab을 누르면 아래 코드가 자동 완성됨
    user = db.session.query(User).filter_by(id=user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserProfile(
        name=user.name,
        email=user.email,
        avatar_url=user.avatar_url,
    )

// 코드를 선택하고 Cmd+K → "에러 핸들링 추가"
// Before:
async function fetchData(url: string) {
  const response = await fetch(url)
  const data = await response.json()
  return data
}

// After (Cmd+K 적용 후):
async function fetchData(url: string) {
  try {
    const response = await fetch(url)
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    const data = await response.json()
    return data
  } catch (error) {
    console.error(`Failed to fetch data from ${url}:`, error)
    throw error
  }
}

# 나쁜 예시
"이 코드 고쳐줘"

# 좋은 예시
"이 useEffect에서 무한 루프가 발생하는데,
 dependency array를 분석하고 수정 방법을 제안해줘.
 @file:src/hooks/useAuth.ts"

[에이전트 모드 실행 예시]

프롬프트: "Express 서버에 JWT 인증 미들웨어를 추가해줘"

Agent 실행 순서:
1. package.json 분석 → jsonwebtoken 패키지 필요 확인
2. 터미널: npm install jsonwebtoken
3. src/middleware/auth.ts 생성 (JWT 검증 미들웨어)
4. src/routes/index.ts 수정 (미들웨어 적용)
5. src/types/express.d.ts 수정 (Request 타입 확장)
6. .env.example 수정 (JWT_SECRET 추가)
7. 변경사항 Diff View로 표시

프로젝트 루트/
  .cursorrules           # 프로젝트 전체 규칙
  .cursor/
    rules/
      react.mdc          # React 관련 규칙
      api.mdc            # API 관련 규칙
      testing.mdc        # 테스트 관련 규칙

# Project: Next.js 14+ App Router

## Tech Stack

- Next.js 14 with App Router
- TypeScript (strict mode)
- Tailwind CSS
- Prisma ORM
- React Query (TanStack Query v5)

## Code Style

- Use functional components only
- Prefer named exports over default exports
- Use 'use client' directive only when necessary
- Follow the component/hook/utility separation pattern

## File Naming

- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Pages: lowercase with hyphens (user-profile/page.tsx)

## Component Structure

1. Imports (external, then internal)
2. Types/Interfaces
3. Component function
4. Helper functions (inside component if small, outside if reusable)

## API Routes

- Always use Route Handlers (app/api/...)
- Return NextResponse with appropriate status codes
- Validate request body with Zod schemas
- Handle errors with try-catch and meaningful error messages

## Testing

- Write tests alongside components (Component.test.tsx)
- Use React Testing Library
- Test user behavior, not implementation details

# Project: FastAPI Microservice

## Tech Stack

- Python 3.12+
- FastAPI
- SQLAlchemy 2.0 (async)
- Pydantic v2
- Alembic for migrations

## Code Style

- Follow PEP 8
- Use type hints everywhere
- Prefer async/await over sync code
- Maximum function length: 30 lines
- Use dependency injection via FastAPI Depends

## Project Structure

- app/api/routes/ - Route handlers
- app/core/ - Config, security, database
- app/models/ - SQLAlchemy models
- app/schemas/ - Pydantic schemas
- app/services/ - Business logic
- app/utils/ - Helper functions

## Error Handling

- Use custom exception classes
- Always return structured error responses
- Log errors with structlog

## Naming Conventions

- Functions: snake_case
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE
- Private methods: \_leading_underscore

# Project: Go REST API

## Tech Stack

- Go 1.22+
- Chi router
- sqlc for database queries
- golang-migrate for migrations

## Code Style

- Follow Go standard conventions
- Keep functions under 40 lines
- Use table-driven tests
- Return errors, don't panic
- Use context.Context as first parameter

## Project Structure

- cmd/ - Application entrypoints
- internal/ - Private application code
- pkg/ - Public library code
- api/ - API definitions and handlers

## Error Handling

- Wrap errors with fmt.Errorf and %w verb
- Use custom error types for domain errors
- Log at the boundary, return errors elsewhere

## Testing

- Test files next to source files (\*\_test.go)
- Use testify for assertions
- Use gomock for mocking interfaces

# 구체적인 파일 지정
@file:src/services/payment.ts
@file:src/types/payment.d.ts
"결제 실패 시 재시도 로직을 추가해줘. 최대 3회, 지수 백오프 적용."

# 전체 코드베이스를 던지고 모호한 요청
@codebase
"결제 관련 수정해줘"

# .cursorignore
node_modules/
dist/
build/
.env
*.min.js
*.map
package-lock.json
yarn.lock

[프롬프트 예시]
"모든 API 라우트의 응답 형식을 JSON:API 스펙으로 변경해줘.
@folder:src/routes
@file:src/types/api.ts

변경 사항:
1. 응답 래퍼를 { data, meta, errors } 형식으로 변경
2. 에러 응답도 JSON:API 형식으로 통일
3. 페이지네이션 메타 정보 추가
4. 관련 타입 정의 업데이트"

[프롬프트 예시]
"실시간 알림 시스템을 구현해줘.
@codebase

요구사항:
1. WebSocket 기반 실시간 알림
2. DB에 알림 저장 (읽음/안읽음 상태)
3. 알림 목록 API (페이지네이션)
4. 프론트엔드 알림 벨 컴포넌트
5. 읽지 않은 알림 카운트 배지"

[효과적인 버그 보고 형식]

"다음 버그를 수정해줘:

증상: 로그인 후 리다이렉트가 무한 루프에 빠짐
재현 경로: 로그인 -> 대시보드 -> 새로고침
에러 로그:
Error: Maximum update depth exceeded

@file:src/hooks/useAuth.ts
@file:src/app/dashboard/page.tsx
@file:src/middleware.ts

의심되는 원인: useEffect의 dependency array 문제"

[시각적 피드백 루프]

1. 코드 작성 (에디터)
2. 내장 브라우저에서 결과 확인
3. 스크린샷 캡처
4. AI 채팅에 "이 UI에서 정렬이 깨지는데 수정해줘" + 스크린샷 첨부
5. AI가 CSS/컴포넌트 수정
6. Accept → 즉시 브라우저에서 변경 확인
7. 반복

[모델 선택 가이드]

빠른 작업 (Tab 완성, 간단한 수정):
  → Composer (기본, 가장 빠름)

복잡한 아키텍처 결정:
  → Claude 3.5 Sonnet (추론 능력 우수)

긴 코드 생성:
  → GPT-4o (안정적인 긴 출력)

최신 라이브러리 관련:
  → @web + 모든 모델 (웹 검색으로 최신 정보 보충)

[프라이버시 설정 경로]
Settings → General → Privacy Mode → Enable

또는 Business 플랜에서:
Admin Console → Organization Settings → Enforce Privacy Mode

# AI가 생성하는 커밋 메시지 예시

feat: add JWT authentication middleware

- Create auth middleware with token verification
- Add refresh token rotation logic
- Update route handlers to use auth middleware
- Add JWT_SECRET to environment configuration

[Before Cursor]
- MVP 개발: 3~4주
- 버그 수정 사이클: 2~3일
- 코드 리뷰: 하루 1~2시간

[After Cursor]
- MVP 개발: 1~2주
- 버그 수정 사이클: 수 시간
- 코드 리뷰: 30분 (AI 사전 리뷰 후)

[Before Cursor]
- 레거시 마이그레이션: 분기 단위
- 코드 표준화: 지속적 리뷰 필요
- 온보딩: 2~3개월

[After Cursor]
- 레거시 마이그레이션: 주 단위
- 코드 표준화: .cursorrules로 자동 준수
- 온보딩: 2~3주 (AI가 코드 설명)

[전환 신호]

- VS Code 특정 확장이 Cursor에서 작동하지 않을 때
  → VS Code + Copilot으로 복귀

- JetBrains의 강력한 리팩토링 도구가 필요할 때
  → IntelliJ/PyCharm + AI Assistant

- 팀 전체가 특정 IDE 표준을 가지고 있을 때
  → 팀 표준에 맞추되, 개인 도구로 Cursor 병행 가능

- 오프라인 환경에서 작업해야 할 때
  → VS Code + 로컬 AI 모델 (Ollama + Continue)