cursor rules 설정으로 AI 코드 품질 잡는 법: 제가 쓰는 .cursorrules 최소 셋업

2026년 07월 03일

0 Views

cursor rules 설정으로 AI 코드 품질 잡는 법: 제가 쓰는 .cursorrules 최소 셋업

Cursor가 코드를 잘 짜게 만들고 싶다면, 먼저 프로젝트 루트에 규칙 파일을 두고 “이 팀의 코딩 방식”을 짧고 명확하게 고정하는 것이 가장 빠릅니다. 특히 Next.js, Supabase, Tailwind처럼 선택지가 많은 스택에서는 Cursor Rules가 없으면 AI가 매번 다른 스타일로 코드를 제안합니다.

내 프로젝트의 반복 실수 3가지를 적고, 위 예시를 기준으로 .cursorrules 파일을 오늘 하나 만들어보세요.

핵심은 거창한 프롬프트가 아닙니다. 폴더 구조, 금지 패턴, 테스트 기준, 네이밍 규칙을 20~40줄 안에 적고, ESLint·Prettier·TypeScript와 함께 묶어 쓰면 코드 품질이 훨씬 안정됩니다.

먼저 내 프로젝트에 맞는 규칙 파일부터 만들고 싶다면

아래 예시를 복사한 뒤, 사용하는 프레임워크와 금지 규칙만 바꿔서 Cursor에 넣어보세요.

Cursor Rules가 실제로 해결하는 문제

AI 코딩 도구를 쓰다 보면 처음에는 속도가 빨라집니다. 그런데 며칠 지나면 다른 문제가 생깁니다. 컴포넌트 위치가 들쭉날쭉하고, API 호출 방식이 섞이고, 에러 처리를 빼먹은 코드가 쌓입니다.

Cursor Rules는 Cursor에게 “우리 프로젝트에서는 이렇게 작성한다”는 기준을 계속 기억시키는 장치입니다. ChatGPT나 Claude Code에 매번 설명하던 내용을 프로젝트 안에 고정해두는 것에 가깝습니다.

제가 자주 쓰는 최소 규칙 구성

아래는 SaaS 대시보드나 내부 툴을 만들 때 쓰기 좋은 기본형입니다. 너무 길게 쓰면 Cursor가 중요한 내용을 놓칠 수 있어, 처음에는 이 정도로 시작하는 편이 좋습니다.

# Project Rules
- Use TypeScript strictly. Avoid any unless there is a clear reason.
- Use functional React components only.
- Keep server logic out of UI components.
- Prefer small files under 200 lines when possible.
- Use Tailwind CSS for styling. Do not create random CSS files.
- Validate external input with zod.
- Do not change public API names without asking.
- When editing existing code, follow the current file style first.
- Add or update tests for business logic changes.
- Explain risky changes before applying them.

이 규칙은 “멋진 코드”보다 “예측 가능한 코드”에 초점을 둡니다. AI가 새 기능을 만들 때도 기존 방식에서 벗어나지 않도록 잡아주는 역할을 합니다.

프로젝트별로 꼭 바꿔야 하는 부분

모든 프로젝트에 같은 규칙을 넣으면 효과가 떨어집니다. 예를 들어 Next.js App Router를 쓰는 프로젝트라면 서버 컴포넌트와 클라이언트 컴포넌트 기준을 넣어야 합니다. Supabase를 쓰면 RLS, service role key 사용 금지 같은 보안 규칙도 필요합니다.

반대로 작은 랜딩페이지 프로젝트에 테스트 규칙을 과하게 넣으면 작업 속도가 느려질 수 있습니다. 규칙은 많을수록 좋은 것이 아니라, 반복적으로 깨지는 부분을 막을 만큼만 넣는 것이 좋습니다.

Cursor Rules, ESLint, Prettier는 역할이 다릅니다

AI 코드 품질을 잡을 때 흔한 실수는 Cursor Rules 하나로 모든 걸 해결하려는 것입니다. 실제로는 규칙 파일은 방향을 잡고, ESLint와 Prettier는 기계적으로 검사하는 식으로 나눠야 안정적입니다.

도구	주요 역할	잘 잡는 문제	한계
Cursor Rules	AI에게 프로젝트 작성 기준 전달	폴더 구조, 금지 패턴, 아키텍처 방향	강제 검사 도구는 아님
ESLint	코드 품질 규칙 검사	미사용 변수, 위험한 패턴, React Hook 규칙	맥락 설명은 못함
Prettier	코드 포맷 통일	들여쓰기, 줄바꿈, 따옴표 스타일	설계 품질은 보지 않음
TypeScript	타입 안정성 확보	잘못된 인자, null 처리, 반환 타입 오류	비즈니스 의도는 모름

추천 조합은 간단합니다. Cursor에는 “어떻게 만들지”를 알려주고, ESLint·Prettier·TypeScript에는 “틀렸는지 검사”하게 만드는 방식입니다.

가상의 예시: Todo SaaS에 적용하면 이렇게 달라집니다

예를 들어 Next.js와 Supabase로 Todo SaaS를 만든다고 가정해보겠습니다. 규칙이 없으면 Cursor가 어떤 화면에서는 직접 Supabase 클라이언트를 호출하고, 다른 화면에서는 서버 액션을 만들 수 있습니다. 인증 체크도 컴포넌트마다 제각각 들어갈 수 있습니다.

이때 규칙에 아래 내용을 추가하면 흐름이 정리됩니다.

- In Next.js App Router, fetch data in server components when possible.
- Client components should only handle interaction and local UI state.
- Supabase queries must be placed in /lib/supabase or server actions.
- Never expose service role keys to client components.
- Use zod schemas for create/update form validation.

이렇게 써두면 새 기능을 요청할 때 “Todo 수정 모달 만들어줘”라고만 해도 Cursor가 기존 구조를 따라갈 가능성이 높아집니다. 물론 결과를 그대로 믿기보다, 변경 파일과 보안 관련 코드는 반드시 직접 확인해야 합니다.

누구에게 어떤 방식이 맞을까

혼자 빠르게 만드는 빌더

MVP를 빠르게 만드는 단계라면 규칙을 짧게 유지하세요. 폴더 구조, 타입 엄격성, 환경변수 금지, UI 라이브러리 정도만 넣어도 충분합니다. 너무 많은 규칙은 Cursor의 제안 속도와 유연성을 떨어뜨릴 수 있습니다.

팀으로 운영하는 개발자

팀 프로젝트라면 Cursor Rules를 README나 코드 리뷰 기준과 맞춰야 합니다. GitHub Actions에서 ESLint와 테스트를 돌리고, Cursor에는 “변경 전 영향 범위를 설명하라”는 규칙을 넣는 편이 좋습니다. 팀원이 Cursor, Claude Code, GitHub Copilot을 섞어 쓰더라도 기준을 공유할 수 있습니다.

레거시 코드 고치는 경우

레거시에서는 “새 구조로 전부 바꿔라”보다 “기존 스타일을 우선 따르라”가 중요합니다. AI가 선의로 리팩터링을 크게 벌이면 리뷰 비용이 커집니다. 이때는 파일 단위 수정, 공개 API 변경 금지, 테스트 없는 대규모 이동 금지를 명시하세요.

가장 자주 막히는 지점

첫째, 규칙을 문서처럼 길게 쓰는 것입니다. Cursor가 모든 문장을 같은 무게로 처리하지 않습니다. 중요한 금지 규칙은 짧고 직접적으로 써야 합니다.

둘째, 규칙만 믿고 리뷰를 생략하는 것입니다. AI는 보안, 비용, 데이터 손실 가능성을 놓칠 수 있습니다. 결제, 인증, 데이터 삭제 관련 코드는 별도 체크리스트를 두는 것이 안전합니다.

셋째, 프로젝트가 바뀌었는데 규칙을 안 고치는 것입니다. Supabase에서 Prisma로 바꿨는데 예전 규칙이 남아 있으면 오히려 품질을 망칩니다.

FAQ

.cursorrules 파일만 만들면 바로 적용되나요?

대부분의 경우 프로젝트 루트에 두면 Cursor가 참고합니다. 다만 Cursor 버전과 설정 방식에 따라 Rules UI나 프로젝트 규칙 관리 방식이 달라질 수 있어 공식 문서를 같이 확인하는 것이 좋습니다.

규칙은 영어로 써야 하나요?

영어가 조금 더 안정적으로 작동하는 편입니다. 다만 팀 커뮤니케이션이 한국어라면 핵심 규칙은 영어, 설명 주석은 한국어로 섞어도 괜찮습니다.

Claude Code나 Codex에도 같은 규칙을 쓸 수 있나요?

개념은 비슷하게 재사용할 수 있습니다. 다만 각 도구가 읽는 파일명, 컨텍스트 방식, 명령 실행 권한이 다르므로 그대로 복사하기보다 도구별 지침 파일로 나누는 편이 안전합니다.

오늘 바로 할 일

지금 프로젝트에서 최근 Cursor가 자주 틀리는 패턴 3가지를 적어보세요. 예를 들면 “API 호출 위치가 섞임”, “any를 자주 씀”, “Tailwind 대신 CSS 파일을 만듦” 같은 것들입니다. 그 3가지를 규칙 파일의 첫 10줄 안에 넣는 것이 가장 현실적인 시작입니다.

cursor rules 설정으로 AI 코드 품질 잡는 법은 복잡한 프롬프트 기술이 아니라, 반복되는 실수를 프로젝트 규칙으로 바꾸는 작업입니다. 작게 시작하고, 실제 리뷰에서 발견한 문제를 한 줄씩 추가하세요.

cursor rules 설정으로 AI 코드 품질 잡는 법: 제가 쓰는 .cursorrules 최소 셋업