Cursor AI 실전 꿀팁: .cursorrules 설정으로 내 프로젝트 맞춤형 코딩 보조 만들기

AI 코딩 에디터의 대세로 자리 잡은 Cursor AI를 사용할 때, 매번 "TailwindCSS 사용해 줘", "TypeScript 엄격 모드로 짜줘", "한국어로 주석 달아줘"라고 동일한 요구사항을 반복해서 입력하고 계신가요?

프로젝트 루트 디렉토리에 .cursorrules 파일 하나만 만들어두면, Cursor AI가 내 프로젝트의 컨벤션, 기술 스택, 코드 스타일을 완벽하게 이해하고 일관된 고품질 코드를 생성해 줍니다. 이번 포스트에서는 실전 프로젝트에 바로 적용할 수 있는 최적의 .cursorrules 작성법과 템플릿을 공개합니다.

1. .cursorrules 파일이란?

.cursorrules 파일은 해당 프로젝트에서 Cursor의 AI(Chat, Cmd+K, Composer)가 작동할 때 항상 참조하는 시스템 프롬프트(System Prompt) 역할을 합니다.

• 위치: 프로젝트의 최상위 루트 디렉토리 (/.cursorrules)
• 장점:
  • 팀 공통 코딩 컨벤션 자동 준수
  • 불필요한 반복 지시어 제거로 프롬프트 작성 시간 단축
  • AI가 잘못된 라이브러리나 과거 버전 문법을 사용하는 현상 방지

2. 실전 적용 추천 .cursorrules 템플릿

아래 코드를 복사하여 프로젝트 루트에 .cursorrules 파일로 저장해 보세요. (Next.js + TypeScript + TailwindCSS 기준 예시)

# 프로젝트 코딩 스타일 & 컨벤션 가이드라인

## 1. 기본 원칙
- 항상 최신 TypeScript 정적 타입을 엄격하게 정의합니다 (any 타입 사용 금지).
- 코드 주석 및 AI의 모든 답변은 한국어로 작성합니다.
- 가독성과 재사용성을 극대화한 가벼운 함수형 컴포넌트(FC) 구조를 지향합니다.

## 2. 프론트엔드 스택 규칙 (Next.js App Router)
- React Server Component(RSC)를 기본으로 활용하며, 클라이언트 상호작용이 필요한 경우에만 파일 상단에 `'use client'`를 서술합니다.
- 스타일링은 Tailwind CSS를 우선적으로 사용합니다. inline style 사용을 금지합니다.
- 아이콘은 `lucide-react` 라이브러리를 사용합니다.

## 3. 에러 처리 및 상태 관리
- 모든 API 요청 및 비동기 처리에는 `try-catch` 블록과 명확한 에러 로그를 포함시킵니다.
- 컴포넌트 내부의 복잡한 비즈니스 로직은 커스텀 훅(`use...`)으로 분리합니다.

## 4. 응답 형식
- 수정된 코드를 제시할 때는 변경된 부분과 이유를 명확하고 간결하게 설명해 주세요.

3. 효율을 200% 올리는 .cursorrules 활용 노하우

팁 1: 패키지 버전 명시하기

AI가 이미 Deprecated(폐기)된 구버전 메소드를 추천하지 않도록 주요 패키지 버전을 기술해 두세요.

예시: Next.js 14+ App Router 문법을 따르며, pages 디렉토리 구조는 고려하지 마세요.

팁 2: 파일 생성 규칙 지정

AI가 파일 이름을 만들 때 헷갈리지 않도록 명명 규칙(Naming Convention)을 선언합니다.

예시: 컴포넌트 파일명은 kebab-case(eg. user-profile-card.tsx)로 작성하세요.

💡 마무리하며

잘 만든 .cursorrules 파일 하나는 신입 개발자에게 전달하는 프로젝트 룰북과 같습니다. AI에게 일관된 힌트와 경계선을 제공함으로써, 코드 리팩토링 및 가동 시간이 대폭 단축되는 것을 직접 체감해 보세요!