Cursor IDE .cursorrules 파일로 TypeScript Next.js 프로젝트 실무 프롬프트 설정 최적화하기

코드 리뷰 때마다 AI가 엉뚱한 스타일로 코드를 뱉어내서 손을 봐야 했던 적, 있죠? 2026년 현재, Cursor IDE를 쓰는 팀이 급격히 늘면서 .cursorrules 파일 설정이 개발 생산성을 가르는 핵심 변수로 떠오르고 있어요.

Stack Overflow Developer Survey 2025에 따르면 AI 보조 코딩 도구를 업무에 쓰는 개발자가 전체의 76%를 넘었어요. 그런데 실제로 팀 단위에서 Cursor를 써본 사람들이 공통으로 꼽는 불만이 있어요. “설정 없이 쓰면 코드 스타일이 들쭉날쭉하다"는 거예요. .cursorrules 파일은 바로 이 문제를 해결하는 도구예요. TypeScript + Next.js 프로젝트라면 특히 더요.

핵심 요약

• .cursorrules 파일은 Cursor IDE가 코드를 생성할 때 따르는 프로젝트별 규칙 문서로, 없으면 AI가 팀 컨벤션을 무시한 코드를 만들어요.
• TypeScript + Next.js 조합에서 any 타입 사용 금지, App Router 패턴 강제 같은 규칙을 명시하면 AI 생성 코드의 재작업률을 절반 이하로 줄일 수 있어요.
• 2026년 기준 Cursor의 .cursorrules는 프로젝트 루트뿐 아니라 .cursor/rules/ 디렉토리 구조로 규칙을 분리 관리하는 방식이 실무 표준으로 자리잡고 있어요.
• 규칙 파일을 Git으로 버전 관리하면 신규 팀원 온보딩 시간을 대폭 줄일 수 있어요 — 컨벤션 문서가 곧 AI 설정 파일이 되니까요.

.cursorrules가 왜 지금 중요해졌을까요?

Cursor IDE가 처음 주목받은 건 2023년이었어요. GPT-4 기반으로 코드 자동완성을 해주는 도구 정도로 인식됐죠. 그런데 2025년 하반기부터 분위기가 달라졌어요. 스타트업뿐 아니라 대형 테크 기업 팀 단위에서 Cursor를 도입하기 시작하면서, “개인 도구"에서 “팀 도구"로 무게중심이 이동한 거예요.

팀에서 쓸 때 가장 먼저 마주치는 벽이 뭐냐고요? AI가 개발자 A의 스타일로 코드를 써줬다가, 개발자 B 세션에서는 완전히 다른 방식으로 써준다는 거예요. 같은 프로젝트인데 파일마다 패턴이 달라지는 거죠.

.cursorrules는 이 문제의 해답으로 등장했어요. 프로젝트 루트에 이 파일을 두면 Cursor가 코드를 생성하거나 수정할 때 반드시 참고하는 맥락 문서가 돼요. 마치 AI에게 “이 팀은 이렇게 코드를 써"라고 사전 교육하는 것과 같아요.

2026년 현재 Cursor 공식 문서에서는 .cursor/rules/ 디렉토리 구조도 지원해요. 규칙을 단일 파일이 아니라 관심사별로 쪼갤 수 있게 된 거예요. typescript.mdc, nextjs.mdc, testing.mdc 이런 식으로요. 큰 프로젝트에서는 이 방식이 훨씬 관리하기 쉬워요.

TypeScript + Next.js 프로젝트에 실제로 어떤 규칙을 넣어야 할까요?

타입 안전성 규칙: any 없는 세상 만들기

TypeScript를 쓰는 이유 중 하나가 타입 안전성인데, AI가 귀찮으면 any를 마구 쓰는 경우가 있어요. .cursorrules에 이걸 명시적으로 막아줘야 해요.

- TypeScript strict mode를 항상 켜두세요
- `any` 타입 사용 금지. 불확실한 타입은 `unknown`으로 처리하세요
- 외부 API 응답은 반드시 Zod 스키마로 검증하세요
- 유틸리티 타입(Partial, Required, Pick)을 적극 쓰세요

이 네 줄만 넣어도 AI가 생성하는 코드 품질이 눈에 띄게 달라져요. 특히 Zod 스키마 규칙은 Next.js API Route나 Server Action에서 입력값 검증을 빠트리는 실수를 막아줘요.

Next.js App Router 패턴 강제하기

Next.js는 Pages Router와 App Router가 공존하는 시기를 지나, 2026년엔 App Router가 사실상 표준이에요. 그런데 AI는 학습 데이터에 Pages Router가 많이 섞여 있어서, 명시하지 않으면 구형 패턴을 쓰는 경우가 생겨요.

- App Router 구조 사용 (pages/ 디렉토리 금지)
- 데이터 페칭은 Server Component에서 직접 처리
- 클라이언트 컴포넌트는 'use client' 최상단에 명시
- Server Action은 'use server' 지시문과 함께 별도 파일로 분리
- Loading UI는 loading.tsx, 에러는 error.tsx로 처리

코드 스타일 & 네이밍 컨벤션

이 부분이 팀마다 가장 달라요. 그래서 팀 컨벤션을 그대로 적어주면 돼요. 예를 들면:

- 컴포넌트 파일명: PascalCase (예: UserProfile.tsx)
- 훅 파일명: camelCase, use 접두사 (예: useUserData.ts)
- 상수: UPPER_SNAKE_CASE
- import 순서: 외부 라이브러리 → 내부 모듈 → 상대 경로

.cursorrules 접근 방식 비교: 단일 파일 vs 디렉토리 구조

소규모 프로젝트라면 단일 파일로 시작해요. 빠르고 간단하니까요. 팀이 3명 이상이거나 프로젝트 수명이 6개월을 넘길 것 같다면, 처음부터 디렉토리 구조로 잡는 게 나중에 편해요.

그런데 규칙 파일이 200줄을 넘어가면 그때부터는 AI가 전체를 제대로 참고하지 못하는 경우도 생겨요. 파일이 너무 길어지면 핵심 규칙 20-30개만 남기고 덜 중요한 건 쳐내는 게 더 나아요. 이게 함정이에요 — 많이 쓴다고 더 잘 따르지 않아요.

실무에서 바로 쓸 수 있는 설정 흐름

문제 1: 신규 팀원이 합류했을 때 컨벤션 교육 비용

.cursorrules 파일을 Git에 커밋해두면 자연스럽게 해결돼요. 신규 팀원이 Cursor를 열면 AI가 이미 팀 컨벤션을 알고 있는 상태로 도와주거든요. 별도 컨벤션 문서를 읽히는 대신, 실제로 코드 작성하면서 자연스럽게 익히는 거예요.

문제 2: AI가 생성한 코드에 보안 취약점이 섞이는 경우

규칙에 보안 가이드를 추가하면 돼요.

- SQL 쿼리는 반드시 파라미터화된 쿼리 사용 (직접 문자열 결합 금지)
- 환경변수는 process.env로만 접근, 클라이언트에 노출 금지
- 사용자 입력은 서버에서 항상 재검증

문제 3: 테스트 코드를 AI가 빠트리는 경우

- 새 함수 작성 시 Jest + Testing Library 테스트 파일 함께 생성
- 테스트 커버리지 80% 이상 유지
- API mocking은 MSW 사용

참고로 Cursor가 .cursorrules를 팀 클라우드로 공유하고 동기화하는 기능을 로드맵에 담고 있어요. 2026년 하반기 중 베타가 나올 가능성이 있고, 이게 나오면 멀티 레포 환경에서 규칙을 일관되게 관리하는 문제가 깔끔하게 풀려요.

지금 당장 해볼 것

.cursorrules 파일 설정은 거창한 작업이 아니에요. 프로젝트 루트에 파일 하나 만들고, 팀이 가장 자주 고치는 AI 생성 코드의 패턴을 10줄짜리 규칙으로 적어두는 것부터 시작하면 돼요.

• .cursorrules는 AI와 팀 사이의 계약서예요 — 명확할수록 결과가 좋아요
• TypeScript 타입 규칙과 Next.js App Router 패턴은 반드시 명시하세요
• 규칙은 짧고 구체적으로 — “좋은 코드 작성” 같은 추상적인 말은 AI가 무시해요
• Git으로 버전 관리하면 팀 컨벤션 문서와 AI 설정이 하나로 합쳐지는 효과가 나요

팀에서 Cursor를 쓰고 있다면, 지금 바로 프로젝트에 .cursorrules 파일이 있는지 확인해보세요. 없다면 오늘 만들고, 있다면 마지막으로 업데이트한 게 언제인지 보세요. AI 도구는 설정한 만큼 일해요.

여러분 팀에서 가장 효과적이었던 Cursor 규칙이 있다면 댓글로 알려주세요 — 실제로 써본 사례가 쌓일수록 다음 분석에 도움이 돼요.

참고자료

1. Best Cursor Rules in 2026 — 20 Rules to Supercharge Your AI Coding — TokRepo
2. 지금 바로 Cursor AI IDE에서 설정할 수 있는 20가지 이상의 멋진 커서 규칙
3. Cursor 완전 가이드 2025: AI 코딩 워크플로우, rules·context 설정법 :: 쵸코쿠키의 연습장

Photo by Liam Briese on Unsplash