Rules

재사용 가능하고 스코프가 있는 지침으로 Agent 모델의 동작을 제어해.

Rules는 Agent와 Inline Edit에 시스템 레벨의 지침을 제공해. 프로젝트를 위한 지속적인 컨텍스트, 기본설정, 워크플로로 생각하면 돼.

Cursor는 네 가지 유형의 Rules를 지원해:

Project Rules

.cursor/rules에 저장되고, 버전 관리되며, 코드베이스 스코프로 적용돼.

User Rules

Cursor 환경 전역에 적용돼. 설정에서 정의되고 항상 적용돼.

AGENTS.md

마크다운 형식의 Agent 지침. .cursor/rules의 간단한 대안이야.

.cursorrules (Legacy)

아직 지원되지만 더는 권장하지 않아. 대신 Project Rules를 써.

규칙이 작동하는 방식

대규모 언어 모델은 각 완료 사이의 내용을 기억하지 않아. 규칙은 프롬프트 수준에서 지속적이고 재사용 가능한 컨텍스트를 제공해.

규칙이 적용되면, 규칙 내용이 모델 컨텍스트의 시작에 포함돼. 이렇게 하면 AI가 코드를 생성하거나, 수정 사항을 해석하거나, 워크플로를 도울 때 일관된 가이드를 제공할 수 있어.

규칙은 Chat과 Inline Edit에 적용돼. 활성 규칙은 Agent 사이드바에 표시돼.

프로젝트 규칙

프로젝트 규칙은 .cursor/rules에 있어. 각 규칙은 파일이며 버전 관리돼. 경로 패턴으로 범위를 지정하거나, 수동으로 호출하거나, 관련성에 따라 자동 포함할 수 있어. 하위 디렉터리는 해당 폴더 범위에만 적용되는 자체 .cursor/rules 디렉터리를 둘 수 있어.

프로젝트 규칙을 사용해서:

• 코드베이스에 대한 도메인 지식을 체계화해
• 프로젝트 특화 워크플로우나 템플릿을 자동화해
• 스타일이나 아키텍처 결정을 표준화해

규칙 구성

각 규칙 파일은 메타데이터와 콘텐츠를 지원하는 MDC(.mdc)로 작성돼. 타입 드롭다운에서 description, globs, alwaysApply 속성을 바꿔 규칙 적용 방식을 제어해.

Rule Type	Description
Always	항상 모델 컨텍스트에 포함됨
Auto Attached	glob 패턴과 일치하는 파일이 참조될 때 포함됨
Agent Requested	AI가 포함 여부를 결정할 수 있도록 제공됨. 설명을 반드시 제공해야 함
Manual	@ruleName으로 명시적으로 언급될 때만 포함됨

---
description: RPC Service boilerplate
globs:
alwaysApply: false
---

- 서비스 정의 시 내부 RPC 패턴을 사용해
- 서비스 이름은 항상 snake_case를 사용해.

@service-template.ts

중첩 규칙

프로젝트 전반에 .cursor/rules 디렉터리를 배치해 규칙을 구성해. 해당 디렉터리의 파일이 참조되면 중첩 규칙이 자동으로 연결돼.

project/
  .cursor/rules/        # 프로젝트 전역 규칙
  backend/
    server/
      .cursor/rules/    # 백엔드 전용 규칙
  frontend/
    .cursor/rules/      # 프런트엔드 전용 규칙

규칙 만들기

New Cursor Rule 명령을 사용하거나 Cursor Settings > Rules로 이동해서 규칙을 만들어. 그러면 .cursor/rules에 새 규칙 파일이 생성돼. 설정에서 모든 규칙과 상태를 확인할 수 있어.

규칙 생성하기

대화 중에 /Generate Cursor Rules 명령으로 규칙을 바로 생성해. 에이전트 동작을 정했고 그 결정을 재사용하고 싶을 때 유용해.

모범 사례

좋은 규칙은 명확한 초점이 있고, 실행 가능하며, 범위가 분명해야 해.

• 규칙은 500줄 이하로 유지해
• 큰 규칙은 여러 개의 조합 가능한 규칙으로 쪼개
• 구체적인 예시나 참고 파일을 제공해
• 모호한 안내는 피하고, 내부 문서처럼 명확하게 작성해
• 채팅에서 프롬프트를 반복할 때는 규칙을 재사용해

예시

프런트엔드 컴포넌트와 API 검증 기준

이 규칙은 프런트엔드 컴포넌트 기준을 제공해:

components 디렉터리에서 작업할 때:

• 스타일링은 항상 Tailwind 사용
• 애니메이션은 Framer Motion 사용
• 컴포넌트 네이밍 컨벤션 준수

이 규칙은 API 엔드포인트 검증을 강제해:

API 디렉터리에서:

• 모든 검증에 zod 사용
• zod 스키마로 반환 타입 정의
• 스키마에서 생성된 타입 export

Express 서비스와 React 컴포넌트 템플릿

이 규칙은 Express 서비스 템플릿을 제공해:

Express 서비스를 만들 때 이 템플릿을 사용해:

• RESTful 원칙 준수
• 에러 처리 미들웨어 포함
• 적절한 로깅 설정

@express-service-template.ts

이 규칙은 React 컴포넌트 구조를 정의해:

React 컴포넌트는 다음 레이아웃을 따라:

• 상단에 Props 인터페이스
• 컴포넌트는 named export
• 하단에 스타일

@component-template.tsx

개발 워크플로 자동화와 문서 생성

이 규칙은 앱 분석을 자동화해:

앱 분석을 요청받았을 때:

1. npm run dev로 dev 서버 실행
2. 콘솔에서 로그 수집
3. 성능 개선 사항 제안

이 규칙은 문서 생성도 도와:

문서 초안을 작성할 때:

• 코드 주석 추출
• README.md 분석
• 마크다운 문서 생성

Cursor에 새 설정 추가하기

먼저 @reactiveStorageTypes.ts에 토글할 프로퍼티를 추가해.

@reactiveStorageService.tsx의 INIT_APPLICATION_USER_PERSISTENT_STORAGE에 기본값을 넣어.

베타 기능이면 @settingsBetaTab.tsx에 토글을 추가하고, 아니면 @settingsGeneralTab.tsx에 추가해. 토글은 일반 체크박스용으로 <SettingsSubSection>에 넣으면 돼. 예시는 파일의 나머지 부분을 참고해.

<SettingsSubSection
				label="Your feature name"
				description="Your feature description"
				value={
					vsContext.reactiveStorageService.applicationUserPersistentStorage
						.myNewProperty ?? false
				}
				onChange={(newVal) => {
					vsContext.reactiveStorageService.setApplicationUserPersistentStorage(
						'myNewProperty',
						newVal
					);
				}}
			/>

앱에서 사용하려면 reactiveStorageService를 import하고 해당 프로퍼티를 써:

const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage.myNewProperty

프로바이더와 프레임워크에서 제공되는 예시가 많아. 커뮤니티가 기여한 규칙은 크라우드소싱 컬렉션과 온라인 리포지토리 전반에서 찾을 수 있어.

AGENTS.md

AGENTS.md는 에이전트 지침을 정의하는 단순한 마크다운 파일이야. 간단한 사용 사례라면 .cursor/rules 대신 프로젝트 루트에 두고 쓰면 돼.

Project Rules와 달리 AGENTS.md는 메타데이터나 복잡한 설정이 없는 순수 마크다운 파일이야. 구조화된 규칙의 오버헤드 없이 간단하고 읽기 쉬운 지침이 필요한 프로젝트에 딱 좋아.

# Project Instructions

## Code Style
- Use TypeScript for all new files
- Prefer functional components in React
- Use snake_case for database columns

## Architecture
- Follow the repository pattern
- Keep business logic in service layers

현재 제한 사항

• 루트 레벨만: AGENTS.md는 프로젝트 루트에만 둬야 해 (v1.5)
• 스코핑 없음: 지침은 프로젝트 전체에 전역으로 적용돼
• 단일 파일: .cursor/rules와 달리 지침을 여러 파일로 나눌 수 없어

하위 디렉터리의 중첩 AGENTS.md 지원은 v1.6에 추가될 예정이야.

사용자 규칙

사용자 규칙은 모든 프로젝트에 적용되는 전역 환경설정으로, Cursor Settings → Rules에서 정의돼. 일반 텍스트라서 선호하는 소통 스타일이나 코딩 컨벤션을 설정하기에 딱 좋아:

Please reply in a concise style. Avoid unnecessary repetition or filler language.

.cursorrules (레거시)

프로젝트 루트의 .cursorrules 파일은 계속 지원되지만, 곧 사용 중단될 예정이야. 더 높은 제어권, 유연성, 가시성을 위해 Project Rules로 옮기는 걸 추천해.

FAQ

왜 내 규칙이 적용되지 않아?

규칙 유형을 확인해. Agent Requested라면 설명이 정의되어 있는지 확인하고, Auto Attached라면 파일 패턴이 참조된 파일과 일치하는지 확인해.

규칙이 다른 규칙이나 파일을 참조할 수 있어?

가능해. 규칙의 컨텍스트에 파일을 포함하려면 @filename.ts를 사용해.

채팅에서 규칙을 만들 수 있어?

가능해. /Generate Cursor Rules 명령어로 채팅에서 프로젝트 규칙을 생성할 수 있어. Memories가 활성화되어 있으면, 메모리는 자동으로 생성돼.

규칙이 Cursor Tab이나 다른 AI 기능에 영향을 줘?

아니. 규칙은 Agent랑 Inline Edit에만 적용돼.