728x90
반응형
- AI 코딩 어시스턴트를 더 똑똑하게 만들기 2025
Cursor의 Rules 기능을 사용하면 AI 코딩 어시스턴트가 프로젝트에 맞는 일관된 코드를 생성하도록 지시할 수 있습니다. 이번 포스트에서는 Cursor Rules의 모든 것을 예시와 함께 상세히 알아보겠습니다.
## Cursor Rules란?
Cursor Rules는 Agent 모델의 동작을 제어하는 재사용 가능하고 범위가 지정된 지시사항입니다. 쉽게 말해, AI에게 "이렇게 코드를 작성해줘"라고 미리 알려주는 설정이라고 생각하면 됩니다.
### 왜 Rules가 필요할까?
대형 언어 모델은 대화가 끝나면 이전 내용을 기억하지 못합니다. Rules는 이 문제를 해결하여 AI가 프로젝트의 코딩 스타일과 규칙을 일관되게 따르도록 도와줍니다.
## Rules의 3가지 유형
### 1. Project Rules (프로젝트 규칙)
- 저장 위치: `.cursor/rules` 폴더
- 특징: 버전 관리되며 프로젝트에만 적용
- 파일 형식: MDC(`.mdc`)
**실제 예시:**
```mdc
---
description: React 컴포넌트 표준
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---
React 컴포넌트 작성 시 다음을 따르세요:
- 항상 TypeScript 사용
- Props는 interface로 정의
- styled-components 대신 Tailwind CSS 사용
- 컴포넌트명은 PascalCase로 작성
예시 구조:
```tsx
interface ButtonProps {
children: React.ReactNode;
onClick: () => void;
variant?: 'primary' | 'secondary';
}
export const Button: React.FC<ButtonProps> = ({ children, onClick, variant = 'primary' }) => {
return (
<button
onClick={onClick}
className={`px-4 py-2 rounded ${variant === 'primary' ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-800'}`}
>
{children}
</button>
);
};
```
```
### 2. User Rules (사용자 규칙)
- 저장 위치: Cursor 설정
- 특징: 모든 프로젝트에 전역적으로 적용
**실제 예시:**
```
간결한 스타일로 답변해 주세요. 불필요한 반복이나 장황한 표현을 피해주세요.
코딩할 때는 한글 주석을 포함해 주세요.
변수명은 누가 봐도 알 수 있게 명확하게 지어주세요.
에러가 날 수 있는 부분은 미리 처리해주세요.
```
### 3. .cursorrules (레거시)
- 여전히 지원되지만 더 이상 권장되지 않음
- Project Rules 사용을 권장
## Rule 유형별 동작 방식
| 규칙 유형 | 동작 방식 | 언제 사용? |
|---------|----------|----------|
| **Always** | 항상 AI 컨텍스트에 포함 | 프로젝트 전반에 적용할 기본 규칙 |
| **Auto Attached** | 특정 파일 패턴 작업 시 자동 포함 | 특정 폴더나 파일 타입에만 적용 |
| **Agent Requested** | AI가 필요하다고 판단할 때 포함 | AI가 상황에 따라 선택적으로 사용 |
| **Manual** | @ruleName으로 명시적 호출 시에만 포함 | 특정 상황에서만 수동으로 적용 |
## 실무에서 활용할 수 있는 Rules 예시
### 1. API 개발 표준화
```mdc
---
description: API 엔드포인트 표준
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---
API 엔드포인트 작성 시 반드시 따라야 할 규칙:
1. 모든 입력 validation에 zod 라이브러리 사용
2. 에러 처리 미들웨어 포함
3. 적절한 HTTP 상태 코드 사용
4. 로깅 시스템 설정
예시 코드:
```typescript
import { z } from 'zod';
import { Request, Response, NextFunction } from 'express';
// 스키마 정의
const userSchema = z.object({
name: z.string().min(1, '이름은 필수입니다'),
email: z.string().email('올바른 이메일 형식이 아닙니다'),
age: z.number().min(0, '나이는 0 이상이어야 합니다')
});
// API 핸들러
export const createUser = async (req: Request, res: Response, next: NextFunction) => {
try {
// 입력값 검증
const validatedData = userSchema.parse(req.body);
// 비즈니스 로직 수행
const newUser = await userService.createUser(validatedData);
// 성공 응답
res.status(201).json({
success: true,
data: newUser,
message: '사용자가 성공적으로 생성되었습니다'
});
} catch (error) {
next(error); // 에러 미들웨어로 전달
}
};
```
```
### 2. 프론트엔드 컴포넌트 가이드
```mdc
---
description: 프론트엔드 컴포넌트 표준
globs: ["src/components/**/*.tsx", "src/pages/**/*.tsx"]
alwaysApply: false
---
React 컴포넌트 작성 표준:
1. 컴포넌트 구조
- Props interface를 상단에 정의
- 컴포넌트를 named export로 내보내기
- 스타일 관련 코드를 하단에 배치
2. 스타일링 규칙
- Tailwind CSS 사용 (styled-components 금지)
- 반응형 디자인 고려
- 접근성(a11y) 속성 포함
3. 네이밍 규칙
- 컴포넌트명: PascalCase
- Props: camelCase
- 이벤트 핸들러: handle + 동작명
예시:
```tsx
// ✅ 올바른 컴포넌트 구조
interface UserCardProps {
user: {
id: string;
name: string;
email: string;
avatar?: string;
};
onUserClick: (userId: string) => void;
className?: string;
}
export const UserCard: React.FC<UserCardProps> = ({
user,
onUserClick,
className = ''
}) => {
const handleCardClick = () => {
onUserClick(user.id);
};
return (
<div
className={`p-4 bg-white rounded-lg shadow-md hover:shadow-lg transition-shadow cursor-pointer ${className}`}
onClick={handleCardClick}
role="button"
tabIndex={0}
aria-label={`${user.name}의 프로필 보기`}
>
{user.avatar && (
<img
src={user.avatar}
alt={`${user.name}의 프로필 사진`}
className="w-12 h-12 rounded-full mb-3"
/>
)}
<h3 className="text-lg font-semibold text-gray-900">{user.name}</h3>
<p className="text-sm text-gray-600">{user.email}</p>
</div>
);
};
```
```
### 3. 데이터베이스 모델 규칙
```mdc
---
description: 데이터베이스 모델 표준
globs: ["src/models/**/*.ts", "src/entities/**/*.ts"]
alwaysApply: false
---
데이터베이스 모델 작성 규칙:
1. 필수 필드
- id: 기본키 (UUID 사용)
- createdAt: 생성 시간
- updatedAt: 수정 시간
2. 네이밍 규칙
- 테이블명: snake_case
- 컬럼명: snake_case
- 모델 클래스명: PascalCase
3. 관계 설정
- 외래키는 명확한 이름 사용
- 적절한 cascade 옵션 설정
예시 (TypeORM):
```typescript
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn, ManyToOne, OneToMany } from 'typeorm';
@Entity('users')
export class User {
@PrimaryGeneratedColumn('uuid')
id: string;
@Column({ type: 'varchar', length: 100, comment: '사용자 이름' })
name: string;
@Column({ type: 'varchar', length: 255, unique: true, comment: '이메일 주소' })
email: string;
@Column({ type: 'varchar', length: 255, comment: '암호화된 비밀번호' })
password_hash: string;
@CreateDateColumn({ comment: '계정 생성 시간' })
created_at: Date;
@UpdateDateColumn({ comment: '마지막 수정 시간' })
updated_at: Date;
@OneToMany(() => Post, post => post.author)
posts: Post[];
}
```
```
## 중첩된 Rules로 프로젝트 구조화
대규모 프로젝트에서는 폴더별로 다른 규칙을 적용할 수 있습니다:
```
my-project/
.cursor/rules/ # 프로젝트 전체 규칙
├── general.mdc # 일반적인 코딩 규칙
└── security.mdc # 보안 관련 규칙
backend/
.cursor/rules/ # 백엔드 전용 규칙
├── api-standards.mdc # API 표준
└── database.mdc # DB 모델 규칙
frontend/
.cursor/rules/ # 프론트엔드 전용 규칙
├── components.mdc # 컴포넌트 규칙
└── styling.mdc # 스타일링 규칙
```
## Rules 생성 방법
### 1. 명령어로 생성
- `Ctrl/Cmd + Shift + P` → `New Cursor Rule` 검색
### 2. 설정에서 생성
- `Cursor Settings` → `Rules` 탭에서 관리
### 3. 채팅에서 자동 생성
- 채팅 중 `/Generate Cursor Rules` 명령어 사용
- AI가 대화 내용을 바탕으로 규칙 자동 생성
## 모범 사례
### ✅ 효과적인 Rules 작성법
1. **구체적이고 실행 가능한 지침 제공**
```mdc
// ✅ 좋은 예시
- 함수명은 동사로 시작 (getUserData, calculateTotal)
- 에러 처리는 try-catch 블록 사용
- API 응답은 항상 { success, data, message } 형태로 반환
```
2. **명확한 예시 코드 포함**
```mdc
// ✅ 좋은 예시
에러 핸들링 예시:
```typescript
try {
const result = await apiCall();
return { success: true, data: result };
} catch (error) {
console.error('API 호출 실패:', error);
return { success: false, error: error.message };
}
```
```
3. **규칙을 작고 집중적으로 유지**
- 하나의 규칙 파일은 500줄 이하
- 큰 규칙은 여러 개의 작은 규칙으로 분할
### ❌ 피해야 할 실수
1. **모호한 지침**
```mdc
// ❌ 나쁜 예시
- 코드를 깔끔하게 작성하세요
- 성능을 고려해서 개발하세요
```
2. **너무 긴 규칙**
- 한 파일에 모든 규칙을 몰아넣지 말기
- 주제별로 분리하여 관리
## 실제 프로젝트 적용 사례
### 팀 프로젝트에서 코딩 스타일 통일
우리 팀은 다음과 같은 규칙으로 일관된 코드 스타일을 유지하고 있습니다:
```mdc
---
description: 팀 코딩 컨벤션
alwaysApply: true
---
우리 팀의 코딩 규칙:
1. 변수명/함수명 규칙
- 한글 주석 필수 작성
- 변수명은 의미가 명확하게 (userData가 아닌 currentUserProfile)
- Boolean 변수는 is/has/can으로 시작 (isLoading, hasPermission)
2. 에러 처리
- 모든 API 호출에 try-catch 적용
- 사용자에게 의미있는 에러 메시지 제공
- 콘솔에는 상세한 에러 정보 로깅
3. 코드 구조
- 함수는 20줄 이내로 제한
- 하나의 함수는 하나의 역할만 수행
- 복잡한 로직은 작은 함수들로 분해
```
## 마무리
Cursor Rules는 AI 코딩 어시스턴트를 더욱 똑똑하게 만들어주는 강력한 도구입니다. 프로젝트의 특성에 맞는 규칙을 설정하면 일관된 코드 품질을 유지하고 개발 생산성을 크게 향상시킬 수 있습니다.
지금 당장 여러분의 프로젝트에 Rules를 적용해보세요! 작은 규칙부터 시작해서 점진적으로 확장해 나가는 것이 좋습니다.
---
💡 **팁**: Rules 설정이 어렵다면 `/Generate Cursor Rules` 명령어로 AI에게 규칙 생성을 요청해보세요.
기존 코드를 분석해서 적절한 규칙을 제안해줍니다!
728x90
반응형