Cursor Docs 를 번역한 포스팅입니다.
출처 : https://docs.cursor.com/context/rules
Rules
에이전트 모델이 재사용 가능하고 범위가 지정된 지침에 따라 어떻게 동작할지를 제어합니다.
규칙은 에이전트(Agent)와 Cmd-K AI에게 시스템 수준의 안내를 제공하는 방식으로, 프로젝트나 사용자 본인을 위한 문맥, 선호도, 워크플로우를 지속적으로 반영할 수 있게 해줍니다.
Cursor는 다음 세 가지 유형의 규칙을 지원합니다:
-
프로젝트 규칙 (Project Rules)
.cursor/rules에 저장되며, 버전 관리되고 코드베이스 범위에 적용됩니다. -
사용자 규칙 (User Rules)
Cursor 환경 전반에 적용되는 글로벌 규칙입니다. 설정(Settings)에서 정의되며 항상 적용됩니다. -
메모리 (Memories)
Chat에서의 대화를 기반으로 자동 생성되는 규칙입니다. -
.cursorrules (구버전)
여전히 지원되지만 더 이상 권장되지 않으며 앞으로는 Project Rules 사용을 권장합니다.
규칙은 어떻게 작동하나요?
대형 언어 모델(LLM)은 완료(Completion) 간에 기억을 유지하지 않습니다.
규칙(Rules)은 이러한 한계를 보완하기 위해 프롬프트 수준에서 지속적이고 재사용 가능한 문맥(Context)을 제공합니다.
규칙이 적용되면, 그 내용이 모델 컨텍스트의 시작 부분에 포함되어
코드 생성, 수정 해석, 워크플로우 지원 등 어떤 작업이든 일관된 지침을 제공합니다.
프로젝트 규칙 (Project Rules)
프로젝트 규칙은 .cursor/rules 디렉토리에 존재합니다. 각 규칙은 개별 파일로 저장되며, 버전 관리됩니다. 경로 패턴(Path Pattern)을 통해 범위를 지정할 수 있고, 수동으로 호출하거나 관련성에 따라 자동 포함될 수 있습니다.
또한 하위 디렉토리는 해당 폴더에 범위가 한정된 자체 .cursor/rules 디렉토리를 포함할 수 있습니다.
프로젝트 규칙은 다음의 목적으로 사용할 수 있습니다:
- 코드베이스에 대한 도메인 특화 지식을 문서화
- 프로젝트에 특화된 워크플로우 또는 템플릿 자동화
- 스타일 또는 아키텍처 결정을 표준화
규칙 유형 (Rule Type)
각 규칙 파일은 .mdc (Markdown with metadata) 형식으로 작성됩니다. 이 형식은 메타데이터와 콘텐츠를 하나의 파일에 함께 포함할 수 있는 가벼운 포맷입니다.
규칙은 다음과 같은 유형을 지원합니다:
| 규칙 유형 (Rule Type) | 설명 |
|---|---|
| Always | 항상 모델 컨텍스트에 포함됩니다. |
| Auto Attached | 특정 glob 패턴과 일치하는 파일이 참조될 때 자동으로 포함됩니다. |
| Agent Requested | AI가 규칙을 참조할 수 있으며, 포함 여부를 스스로 판단합니다. 설명이 필수입니다. |
| Manual | @ruleName 형태로 명시적으로 호출될 때만 포함됩니다. |
MDC 규칙 예시
Ask AI
---
description: RPC 서비스 보일러플레이트
globs:
alwaysApply: false
---
- 서비스를 정의할 때는 내부 RPC 패턴을 사용하세요.
- 서비스 이름은 항상 `snake_case`를 사용하세요.
@service-template.ts@service-template.ts와 같이 참조된 파일은, 이 규칙이 적용될 때 추가 컨텍스트로 포함됩니다.
💡 팁
Cmd + Shift + P > "New Cursor Rule" 명령어를 사용하면 Cursor 내에서 빠르게 새 규칙을 생성할 수 있습니다.
다음은 해당 문장의 한국어 번역입니다:
중첩 규칙 (Nested Rules)
.cursor/rules 디렉토리를 프로젝트 구조 곳곳에 배치함으로써 규칙을 체계적으로 구성할 수 있습니다. 예를 들어:
project/
.cursor/rules/ # 프로젝트 전체에 적용되는 규칙
backend/
server/
.cursor/rules/ # 백엔드 서버에만 적용되는 규칙
frontend/
.cursor/rules/ # 프론트엔드에만 적용되는 규칙중첩 규칙의 특징:
- 해당 디렉토리의 파일이 참조될 때 자동으로 규칙이 적용됩니다.
- 컨텍스트 선택기 및 에이전트가 접근할 수 있는 규칙 목록에 포함됩니다.
- 관련 코드 가까이에 도메인 특화 규칙을 배치하기에 적합합니다.
이 방식은 특히 **모노레포(Monorepo)**나, 구성 요소별로 서로 다른 지침이 필요한 프로젝트에 유용합니다.
규칙 생성하기 (Creating a rule)
규칙은 다음 방법으로 생성할 수 있습니다:
New Cursor Rule명령어 실행- Cursor Settings > Rules로 이동
이 작업은 .cursor/rules 디렉토리에 새로운 규칙 파일을 생성합니다.
또한 Settings 메뉴에서 전체 규칙 목록과 각 규칙의 활성화 상태를 확인할 수 있습니다.
규칙 생성하기 (Generating Rules)
/Generate Cursor Rules 명령어를 사용하면, 대화 중에 직접 규칙을 생성할 수 있습니다.
이 기능은 특히 다음과 같은 상황에서 매우 유용합니다:
에이전트(Agent)의 동작 방식에 대한 여러 결정 사항을 대화 중에 정리했을 때
그 내용을 기반으로 규칙을 생성해 두면, 향후 동일한 지침을 반복적으로 재사용할 수 있습니다.
즉, 중요한 결정이 오간 대화를 한 줄로 정리하고, 프롬프트 수준의 지침(rule)으로 변환함으로써
일관된 작업 흐름과 자동화된 맥락 설정이 가능해집니다.
모범 사례 (Best Practices)
좋은 규칙은 명확한 초점, 실행 가능성, 그리고 적절한 범위를 갖추고 있어야 합니다.
✅ 규칙을 잘 작성하기 위한 가이드라인:
- 간결하게 유지하세요. 규칙은 500줄 이하로 작성하는 것이 이상적입니다.
- 큰 개념은 분리하세요. 복잡한 개념은 여러 개의 규칙으로 나누어 조합 가능하게 설계하세요.
- 구체적인 예시 또는 참조 파일을 제공하세요. 예: @example-service.ts와 같은 참조 파일은 규칙의 이해를 돕습니다.
- 모호한 지침은 피하세요. 규칙은 내부 문서를 쓰듯 명확하고 구체적으로 작성하세요.
- 반복되는 프롬프트는 규칙으로 재사용하세요. 같은 요청을 자주 하게 된다면, 그것을 하나의 규칙으로 만들어 효율을 높이세요.
Examples
📚 도메인 특화 지침 (Domain-specific guidance)
✅ 프론트엔드 컴포넌트 및 API 유효성 검사 기준
이 규칙은 프론트엔드 컴포넌트의 일관된 스타일링과 애니메이션을 보장하기 위한 기준을 제공합니다:
components 디렉토리에서 작업할 때:
- 스타일링에는 반드시 Tailwind를 사용하세요.
- 애니메이션에는 Framer Motion을 사용하세요.
- 컴포넌트 명명 규칙을 따르세요.
이 규칙은 API 엔드포인트의 유효성 검사 표준을 정의합니다:
api 디렉토리에서:
- 모든 유효성 검사는 Zod를 사용하세요.
- 반환 타입은 Zod 스키마로 정의하세요.
- 스키마에서 생성된 타입을 내보내기(export) 하세요.
🧱 보일러플레이트 및 템플릿 (Boilerplate and Templates)
✅ Express 서비스 및 React 컴포넌트 템플릿
이 규칙은 새로운 Express 서비스를 생성할 때 사용할 템플릿을 제공합니다:
새 Express 서비스를 만들 때 이 템플릿을 사용하세요:
- RESTful 원칙을 따르세요
- 에러 처리 미들웨어를 포함하세요
- 적절한 로깅 설정을 하세요
@express-service-template.ts참조
이 규칙은 React 컴포넌트의 구조를 정의합니다:
React 컴포넌트는 다음 구조를 따라야 합니다:
- 상단에 Props 인터페이스 정의
- 컴포넌트는 Named Export로 작성
- 하단에 스타일 정의
@component-template.tsx참조
⚙️ 워크플로우 자동화 (Workflow Automation)
✅ 개발 워크플로우 및 문서 생성 자동화
이 규칙은 앱 분석 워크플로우를 자동화합니다:
"앱을 분석해줘"라고 요청하면:
npm run dev로 개발 서버를 실행하세요- 콘솔에서 로그를 가져오세요
- 성능 개선 사항을 제안하세요
이 규칙은 코드로부터 문서를 자동 생성하는 데 도움이 됩니다:
문서를 작성할 때는 다음을 수행하세요:
- 코드에 작성된 주석을 추출하세요
README.md를 분석하세요- Markdown 형식의 문서를 생성하세요
사용자 규칙 (User Rules)
사용자 규칙은 Cursor Settings > Rules에서 정의할 수 있습니다.
- 이 규칙은 모든 프로젝트에 전역적으로 적용되며, 항상 모델 컨텍스트에 포함됩니다.
사용자 규칙을 활용할 수 있는 예:
- 응답 언어 또는 톤 설정
- 개인 스타일 선호도 반영
📌 예시:
Ask AI
Please reply in a concise style. Avoid unnecessary repetition or filler language. 사용자 규칙은 **MDC 형식(.mdc)**을 지원하지 않으며, 일반 텍스트로만 작성됩니다.
메모리 (Memories) [베타]
**메모리(Memories)**는 Chat에서의 대화를 기반으로 자동 생성되는 규칙입니다.
이 규칙은 현재 Git 저장소 단위로 범위가 지정됩니다.
→ 향후에는 범위 확장 및 기능 개선이 예정되어 있습니다.
Cursor Settings > Rules에서 메모리를 확인 및 삭제할 수 있습니다.- 단, **개인정보 보호 모드(Privacy Mode, Legacy)**가 활성화된 사용자는 메모리 기능을 사용할 수 없습니다.
.cursorrules (구버전)
프로젝트 루트 디렉토리에 위치한 .cursorrules 파일은 여전히 지원되지만,
더 이상 권장되지 않으며 향후 제거(deprecated)될 예정입니다.
⚠️ 우리는 더 나은 제어력, 유연성, 가시성을 제공하는
Project Rules 형식으로의 마이그레이션(이전)을 권장합니다.
