개발팀이 여러 리포지토리에서 아키텍처 패턴과 코딩 표준을 적용하기 위해 Cursor 규칙을 구성하는 방법

엔지니어링 팀이 Cursor 환경에서 아키텍처 패턴과 코딩 표준을 조직 전체에 일관되게 적용하는 핵심 전략은 기존의 단일 파일 기반 레거시 .cursorrules에서 모듈형 프로젝트 규칙(.cursor/rules/*.mdc)으로 전환하고, YAML 프론트매터를 활용해 전역 불변 제약과 파일 경로(Glob) 기반 경계를 분리하며, Cursor Team Rules 대시보드나 CI/CD 자동화 파이프라인을 통해 다중 리포지토리에 동기화 및 거버넌스를 구축하는 것입니다.

조직 차원의 명확한 가드레일 없이 AI 코딩 어시스턴트를 도입하면 심각한 'AI 아키텍처 드리프트(Architectural Drift)'가 발생합니다. 엔지니어마다 서로 다른 프로그래밍 패러다임이 혼재되고, 모델이 이미 사용 중단(Deprecated)된 내부 패키지를 환각하여 참조하거나, 도메인 레이어를 우회하여 UI 컴포넌트에서 데이터베이스를 직접 호출하는 등 설계 원칙이 무너집니다. Git으로 버전 관리되는 체계적인 Cursor 규칙을 수립하면, 불필요한 프롬프트 토큰 낭비를 줄이면서도 AI 코드 생성에 높은 수준의 결정성을 부여할 수 있습니다.

팀 단위 AI 도입 시 직면하는 기술 거버넌스 과제

공통 가이드라인 없이 Cursor를 사용할 경우, 모델은 조직 고유의 아키텍처 맥락 대신 공개 인터넷 학습 데이터를 기준으로 코드를 작성합니다. 이로 인해 다음과 같은 협업 문제가 발생합니다.

• 아키텍처 계층 침범: 프론트엔드 UI 컴포넌트 내부에서 데이터베이스 쿼리를 직접 작성하거나, 도메인 서비스 계층에 Express 또는 Fastify의 요청/응답 객체를 전달하는 등 계층 간 분리가 깨집니다.
• 폐기되거나 검증되지 않은 의존성 유입: 모델이 과거 학습 데이터를 바탕으로 사용 중단된 내부 라이브러리(예: @company/design-system-v2 대신 구버전 @company/legacy-ui)를 추천하거나, 보안 승인을 받지 않은 외부 라이브러리를 임의로 추가합니다.
• 코드 스타일의 파편화: 동일한 프로젝트 내에서 함수형 패턴과 클래스 기반 패턴이 뒤섞이고, 오류 처리 방식, 로깅 규격, 상태 관리 라이브러리가 제각각 적용됩니다.
• 단위 테스트 품질 저하: 경계 조건 검증이 누락되거나, 프로젝트에서 채택하지 않은 Mocking 도구를 혼용하는 등 부실한 테스트 코드가 생성됩니다.

이러한 마찰을 방지하려면 기술 리더와 아키텍트가 팀의 공통 규약을 코드베이스와 함께 지속적으로 유지되는 규칙으로 공식화해야 합니다.

Cursor 규칙 아키텍처의 진화: .cursorrules에서 모듈형 .mdc로

초기 Cursor는 리포지토리 루트에 위치한 단일 .cursorrules 텍스트 파일을 지원했습니다. 이전 버전과의 호환성은 유지되지만, 단일 대용량 파일 방식은 매 상호작용마다 모든 지침을 프롬프트에 로드하므로 컨텍스트 윈도우를 과도하게 소모하고 모델의 지시 수행 정확도를 떨어뜨리는 한계가 있습니다.

현재의 Cursor는 .cursor/rules/ 디렉터리 내에 위치하며 YAML Frontmatter를 포함하는 프로젝트 규칙(.mdc, Markdown Cursor) 체계로 전면 전환되었습니다.

.mdc 규칙 파일의 구조

각 .mdc 파일은 상단의 YAML 구성 메타데이터와 하단의 구체적인 기술 가이드라인(Markdown)으로 결합됩니다.

---
description: 도메인 서비스 계층 경계 및 레포지토리 패턴 규약
globs: src/domains/**/*.ts, src/services/**/*.ts
alwaysApply: false
---

# 도메인 계층 아키텍처 규칙

- 도메인 서비스는 원시 HTTP 요청 객체를 직접 수신하거나 파싱해서는 안 됩니다.
- 모든 데이터 영속화 변경은 레포지토리 포트 인터페이스를 통해서만 수행해야 합니다.

프론트매터 트리거 옵션 및 동작 방식

YAML Frontmatter는 규칙이 컨텍스트 윈도우에 언제, 어떻게 주입될지를 결정합니다.

소프트웨어 아키텍트를 위한 실전 규칙 청사진

엔터프라이즈 환경에서는 단일 책임 원칙에 따라 규칙을 여러 .mdc 파일로 분리하는 것이 이상적입니다. 아래는 실무에서 바로 적용 가능한 3가지 프로덕션 템플릿입니다.

1. 전역 아키텍처 불변 원칙 (.cursor/rules/00-core-architecture.mdc)

리포지토리 전체에 항상 적용되는 최상위 기준선입니다.

---
description: 전역 아키텍처 불변 원칙, 기본 기술 스택 및 사용 금지 패키지
alwaysApply: true
---

# 핵심 아키텍처 원칙

## 기술 스택 및 버전 기준
- 런타임 환경: Node.js v20 LTS
- TypeScript: v5.4+ (`strict: true` 필수 활성화)
- 프레임워크: Next.js App Router (v14+)
- 상태 관리: Zustand (Redux 또는 MobX 도입 금지)

## 엄격히 금지된 라이브러리 및 패턴
- 금지: `axios` (`@lib/api-client`로 래핑된 표준 `fetch` 사용)
- 금지: `@company/ui-core-v1` (폐기됨; `@company/design-system-v2` 필수 사용)
- 금지: `moment.js` (`date-fns`로 단일화)

## 코드 품질 표준
- 명시적 `any` 타입 사용 금지. 동적 데이터는 `unknown`과 타입 가드를 함께 사용할 것.
- 조기 반환(Early Return / Guard Clauses)을 준수하고 3단계 이상의 중첩 `if/else` 블록 지양.
- 소스 코드에 API 비밀키, 토큰, 환경 설정 자격 증명을 절대 하드코딩하지 말 것.

2. 백엔드 도메인 계층 및 클린 아키텍처 (.cursor/rules/backend-services.mdc)

개발자가 백엔드 도메인 서비스 코드를 편집할 때만 선택적으로 로드됩니다.

---
description: 백엔드 서비스의 헥사고날 아키텍처 및 레포지토리 패턴 규약
globs: src/services/**/*.ts, src/domains/**/*.ts
alwaysApply: false
---

# 백엔드 도메인 아키텍처 규약

## 계층별 책임 분리
- 컨트롤러는 HTTP 요청 역직렬화, 파라미터 유효성 검사, 상태 코드 반환만 담당합니다.
- 서비스는 순수한 도메인 비즈니스 로직만 수행합니다. Express나 Fastify의 `req`, `res` 객체를 서비스로 전달해서는 안 됩니다.
- 레포지토리는 데이터 저장을 캡슐화합니다. 서비스는 구체적인 ORM 인스턴스가 아닌 추상 인터페이스에 의존해야 합니다.

## 구현 예시 비교

```typescript
// ✅ 권장: 서비스는 추상 인터페이스에 의존하며 순수 도메인 엔티티를 다룸
export class OrderService {
  constructor(private readonly orderRepository: OrderRepositoryPort) {}

  async processOrder(orderId: string): Promise<Result<Order>> {
    const order = await this.orderRepository.findById(orderId);
    if (!order) return Result.fail('Order not found');
    order.markPaid();
    await this.orderRepository.save(order);
    return Result.ok(order);
  }
}

// ❌ 금지: 비즈니스 로직 내부에서 ORM 인스턴스를 직접 호출하여 데이터 갱신
export class OrderService {
  async processOrder(orderId: string) {
    await prisma.orders.update({ where: { id: orderId }, data: { status: 'PAID' } });
  }
}

### 3. 단위 및 통합 테스트 표준 (`.cursor/rules/testing-standards.mdc`)

AI가 생성하는 테스트 코드가 팀의 테스트 프레임워크 및 검증 스타일에 부합하도록 안내합니다.

```markdown
---
description: 단위 테스트 및 통합 테스트 작성 표준 및 검증 요구사항
globs: **/*.test.ts, **/*.spec.ts, src/tests/**/*
alwaysApply: false
---

# 테스트 자동화 표준

## 테스트 스택
- 테스트 실행기: Vitest
- Mock 도구: `vi.mock()` (Jest 런타임 혼용 금지)
- 단언 라이브러리: 명시적 매처를 지원하는 `expect()`

## 테스트 설계 가이드라인
- Arrange-Act-Assert (준비-실행-검증) 3단계 구조를 엄격히 준수할 것.
- 단위 테스트 파일은 소스 파일과 동일 디렉터리에 배치: `feature.service.ts` -> `feature.service.test.ts`.
- 단위 테스트에서 실제 외부 네트워크나 데이터베이스를 호출하지 말 것. 인터페이스 경계에서 Mock 처리 필수.
- 누락된 파라미터, 권한 오류, 예외 발생 등 부정적 경계 테스트 케이스를 반드시 포함할 것.

다중 리포지토리 확장 전략: 모노레포와 폴리레포 비교

단일 저장소를 넘어 수십, 수백 개의 리포지토리에 걸쳐 일관성을 유지하기 위해 엔터프라이즈 환경에서는 구조화된 거버넌스가 필요합니다.

                          전사적 규칙 거버넌스 체계
                                     │
         ┌───────────────────────────┴───────────────────────────┐
         ▼                                                       ▼
   모노레포 전략 (Monorepo)                                폴리레포 전략 (Polyrepo)
  ├── .cursor/rules/00-core.mdc                          ├── 중앙 규칙 저장소: org-cursor-rules
  ├── .cursor/rules/apps-web.mdc (웹 전용 Glob)          ├── CI/CD 유효성 검증 및 동기화 파이프라인
  └── .cursor/rules/shared-ui.mdc (공통 패키지 Glob)      └── Cursor Team Rules (관리자 대시보드 배포)

전략 A: 모노레포에서의 계층형 Glob 스코프 격리

Turborepo, Nx 또는 pnpm workspaces 기반의 모노레포에서는 모든 규칙을 루트 .cursor/rules/에 배치하고 디렉터리별 Glob으로 격리합니다.

• globs: ["apps/web/**/*"]: Next.js 서버 컴포넌트, Tailwind 유틸리티 및 클라이언트 상태 분리 적용.
• globs: ["apps/api/**/*"]: OpenAPI 명세, 마이그레이션 스키마 및 백엔드 라우팅 제약 적용.
• globs: ["packages/ui/**/*"]: 시맨틱 버전 호환성, 웹 접근성(ARIA) 및 무거운 서드파티 프레임워크 결합 금지 적용.
• 장점: 프론트엔드 작업 시 백엔드 DB 규칙이 로드되지 않아 프롬프트 맥락이 명확하게 유지됩니다.

전략 B: 폴리레포 환경의 CI/CD 코드화 거버넌스 (Rules as Code)

독립된 마이크로서비스 저장소들을 운영하는 경우, Cursor 규칙을 공유 라이브러리처럼 버전 관리합니다.

1. 중앙 거버넌스 저장소 운영: 표준 .mdc 파일들을 보관하는 전용 Git 저장소(예: github.com/org/cursor-rules-standards)를 생성하고, 시맨틱 버전 태그(예: v1.2.0)를 부여합니다.
2. CI 드리프트 검증: 개별 서비스 저장소의 CI 파이프라인에서 로컬 .cursor/rules/ 디렉터리가 중앙 저장소의 승인된 릴리스와 일치하는지 자동 검증합니다.
3. 자동화된 동기화 워크플로: GitHub Actions 또는 스크립트를 통해 중앙 규칙이 업데이트될 때마다 각 서비스 저장소로 Pull Request를 자동 발행합니다.

전략 C: Cursor Team Rules 기반 중앙 배포

Cursor Team 또는 Enterprise 요금제를 사용하는 조직은 클라우드 관리 콘솔을 활용할 수 있습니다.

• 대시보드 일괄 배포: 조직 관리자가 웹 대시보드에서 전사 공통 규칙을 등록하면 모든 팀원의 환경에 자동으로 반영됩니다.
• 강제 규칙(Enforced)과 권장 규칙(Optional) 분리: 보안 및 라이선스 관련 핵심 원칙은 로컬에서 비활성화할 수 없도록 강제하고, 보조 팁은 권장 사항으로 설정할 수 있습니다.
• 즉각적인 신규 리포지토리 지원: 새 저장소를 생성하거나 새 개발자가 합류하더라도 별도 파일 복사 없이 전사 표준을 즉시 상속받습니다.

실무 권장 사항 및 안티패턴 방지

Cursor 규칙을 모듈화된 .mdc 파일 체계로 구조화하고, 경로 기반 격리와 중앙화된 동기화 메커니즘을 결합함으로써 개발 조직은 AI가 제공하는 개발 생산성을 극대화하는 동시에 아키텍처 표준을 완벽히 지켜낼 수 있습니다.

참고 자료

• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI