모노레포 프로젝트에서 .cursorrules 파일로 팀 전체 코드 스타일 통일하기 - 완벽 가이드

모노레포 프로젝트에서 .cursorrules로 팀 코드 스타일을 통일하는 방법

대규모 모노레포 프로젝트에서 팀원마다 다른 코딩 스타일은 코드 리뷰 시간 증가, 일관성 저하, 유지보수 비용 상승의 주요 원인입니다. Cursor의 .cursorrules 파일을 활용하면 AI 코드 어시스턴트가 팀의 코딩 컨벤션을 자동으로 따르도록 설정할 수 있습니다. 이 가이드에서는 모노레포 환경에서 계층적 규칙 파일을 구성하고 팀 전체에 배포하는 전체 워크플로를 단계별로 안내합니다.

사전 준비 사항

• Cursor IDE 최신 버전 설치 (v0.40 이상 권장)- 모노레포 프로젝트 구조 (예: Turborepo, Nx, pnpm workspace)- Git 버전 관리 시스템- 팀 코딩 컨벤션 문서 (ESLint, Prettier 설정 등)

Step 1: .cursorrules 파일의 구조 이해

.cursorrules 파일은 프로젝트 루트 또는 하위 디렉토리에 배치하여 Cursor AI가 코드를 생성·수정할 때 따라야 할 규칙을 정의합니다. Cursor는 현재 작업 중인 파일의 위치에서 가장 가까운 .cursorrules 파일을 우선 적용합니다. monorepo/ ├── .cursorrules # 루트 레벨: 전역 규칙 ├── packages/ │ ├── frontend/ │ │ ├── .cursorrules # 프론트엔드 전용 규칙 │ │ └── src/ │ ├── backend/ │ │ ├── .cursorrules # 백엔드 전용 규칙 │ │ └── src/ │ └── shared/ │ ├── .cursorrules # 공유 라이브러리 규칙 │ └── src/ └── apps/ ├── web/ │ ├── .cursorrules # 웹 앱 전용 규칙 │ └── src/ └── mobile/ ├── .cursorrules # 모바일 앱 전용 규칙 └── src/

Step 2: 루트 레벨 글로벌 규칙 작성

프로젝트 루트의 .cursorrules에 팀 전체에 적용될 공통 규칙을 정의합니다. # .cursorrules (프로젝트 루트)

프로젝트 개요

• 모든 비즈니스 로직에는 단위 테스트를 작성합니다
• 테스트 파일명은 *.test.ts 또는 *.spec.ts 형식입니다
• describe-it 패턴을 사용합니다

Step 3: 패키지별 세부 규칙 작성

각 패키지의 기술 스택과 요구사항에 맞는 세부 규칙을 정의합니다.

프론트엔드 패키지 규칙

# packages/frontend/.cursorrules

import type { FC } from 'react';

interface ButtonProps {
  variant: 'primary' | 'secondary';
  onClick: () => void;
  children: React.ReactNode;
}

export const Button: FC<ButtonProps> = ({ variant, onClick, children }) => {
  return (
<button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
</button>
  );
};

• useEffect 내 직접 API 호출 금지
• props drilling 3단계 이상 금지 (Context 또는 Zustand 사용)
• index.ts에서 default export 금지 (named export 사용)

백엔드 패키지 규칙

# packages/backend/.cursorrules

## 백엔드 규칙
- NestJS 프레임워크를 사용합니다
- 모든 API 엔드포인트에 DTO 유효성 검사를 적용합니다
- 데이터베이스 접근은 Repository 패턴을 사용합니다
- 환경변수는 ConfigService를 통해 접근합니다
- API 응답은 통일된 ResponseDto 형식을 사용합니다

## API 응답 형식
```typescript
interface ApiResponse {
  success: boolean;
  data: T;
  message: string;
  timestamp: string;
}
```

## 보안 규칙
- 민감한 정보(API_KEY, DB 비밀번호)를 코드에 하드코딩하지 않습니다
- 모든 사용자 입력은 class-validator로 검증합니다
- SQL 쿼리는 ORM(TypeORM/Prisma)을 통해서만 실행합니다

Step 4: 팀 배포 및 Git 연동

.cursorrules 파일을 Git에 커밋하여 팀 전체가 동일한 규칙을 공유합니다. # .cursorrules 파일을 Git에 추가 git add .cursorrules packages/**/.cursorrules git commit -m "docs: add .cursorrules for team-wide code style enforcement" git push origin main

**.gitignore에 포함하지 마세요.** .cursorrules는 팀 공유 자산이므로 반드시 버전 관리에 포함해야 합니다.

Step 5: Cursor Settings에서 규칙 활성화 확인

• Cursor IDE를 실행합니다- Ctrl + Shift + P (macOS: Cmd + Shift + P)로 Command Palette를 엽니다- Cursor Settings를 검색하여 진입합니다- General > Rules for AI 섹션에서 프로젝트 규칙이 로드되었는지 확인합니다- Include .cursorrules 옵션이 활성화되어 있는지 점검합니다

Step 6: 규칙 검증 및 테스트

규칙이 올바르게 적용되는지 Cursor Chat에서 직접 테스트합니다. # Cursor Chat (Ctrl+L)에서 테스트 프롬프트 입력:

형태로 코드가 생성되어야 합니다

Pro Tips: 파워 유저를 위한 고급 활용법

# CODEOWNERS 파일에 추가
.cursorrules @team-lead
packages/**/.cursorrules @team-lead
.cursor/rules/** @team-lead

Q1: .cursorrules 파일과 .editorconfig, ESLint 설정의 차이점은 무엇인가요?

.editorconfig와 ESLint는 코드 포맷팅과 정적 분석을 자동화하는 도구입니다. 반면 .cursorrules는 Cursor AI가 코드를 생성하거나 수정할 때 따라야 할 고수준 아키텍처 패턴, 설계 원칙, 네이밍 컨벤션을 지시합니다. 이 세 가지를 함께 사용하면 코드 생성 단계부터 검증 단계까지 일관된 품질을 유지할 수 있습니다.

Q2: .cursorrules 파일의 최적 길이는 어느 정도인가요?

파일 하나당 200~500줄 이내를 권장합니다. 너무 길면 AI가 규칙을 누락하거나 우선순위를 잘못 판단할 수 있습니다. 규칙이 많다면 .cursor/rules/ 디렉토리를 활용하여 도메인별(보안, 스타일, 아키텍처 등)로 파일을 분리하는 것이 효과적입니다.

Q3: 모노레포에서 특정 패키지에만 다른 언어(Python 등)를 사용하는 경우 어떻게 설정하나요?

해당 패키지 디렉토리에 별도의 .cursorrules 파일을 생성하고 해당 언어의 컨벤션을 정의하면 됩니다. 예를 들어 packages/ml-service/.cursorrules에 Python 관련 규칙(PEP 8, type hints, docstring 형식 등)을 작성하면 해당 패키지에서 작업할 때 자동으로 Python 규칙이 적용됩니다. 루트의 TypeScript 규칙과 충돌 없이 독립적으로 동작합니다.