Cursor, AI Coding #5 Rules 셋팅

아트·2025년 10월 22일

Cursor

목록 보기

5/6

Cursor와 Rules

“AI가 프로젝트의 맥락을 이해하도록 만드는 핵심 구성요소.”

1. Cursor Rules란 무엇인가

Cursor Rules는 커서(Cursor) 편집기 내에서 인공지능이 “항상 따라야 하는 규칙”을 정의하기 위한 시스템입니다.
이는 LLM(Large Language Model)이 세션 간 기억(memory)을 가지지 못한다는 한계를 보완하고,
특정 프로젝트 또는 전역 환경에서 지속적인 컨텍스트(Context)를 제공합니다.

즉, AI가 코드를 생성하거나 편집할 때
“이 프로젝트는 이렇게 작성해야 한다”라는 팀의 규칙을 항상 포함시켜 주는 설계 도구입니다.

2. 룰의 종류

구분	적용 범위	저장 위치	특징
User Rules	모든 프로젝트	커서 앱 내 설정 (Settings → Rules)	개인 또는 팀 공용 룰
Project Rules	특정 프로젝트	`.cursor/rules/*.mdc`	코드베이스와 함께 버전 관리
Nested Rules	하위 폴더별	`subdir/.cursor/rules`	해당 폴더 범위에 한정 적용

3. Project Rules 작성법

3.1 파일 위치

프로젝트/
 ├─ .cursor/
 │   └─ rules/
 │       ├─ backend.mdc
 │       ├─ frontend.mdc
 │       └─ style.mdc
 ├─ backend/
 │   └─ .cursor/
 │       └─ rules/
 │           └─ api.mdc
 ├─ frontend/
 │   └─ .cursor/
 │       └─ rules/
 │           └─ component.mdc
 └─ src/...

.cursor/rules 폴더는 프로젝트 최상위(root)와 각 서브디렉터리에 둘 수 있으며,
하위 폴더의 .cursor/rules는 “더 가까운 경로가 우선 적용”됩니다.
즉, src/frontend/button.tsx를 수정할 때는 /frontend/.cursor/rules/component.mdc가
상위 /project/.cursor/rules/frontend.mdc보다 우선적으로 적용됩니다.

3.2 기본 구조 예시

---
description: React 컴포넌트 스타일 규칙
globs:
  - src/components/**/*.tsx
alwaysApply: true
---

# Component Style Guide

- 모든 컴포넌트 이름은 PascalCase를 사용합니다.
- Props 타입은 반드시 명시적으로 정의합니다.
- UI 관련 CSS는 Tailwind를 기본으로 사용합니다.

설명:

description: 룰의 목적 요약
globs: 적용할 파일 범위 지정 (와일드카드 패턴)
alwaysApply: 항상 컨텍스트에 포함할지 여부

3.3 고급 설정 예시

① 항상 적용 (Always Rule)

---
description: 전역 코드 규약
alwaysApply: true
---

- 모든 JS/TS 파일은 세미콜론을 사용합니다.

② 자동 적용 (Auto-Attached Rule)

---
description: 백엔드 RPC 서비스 규약
globs:
  - src/services/**/*.ts
---

- 모든 서비스는 async function 형태로 작성합니다.
- 예외 처리는 공통 모듈 `errorHandler`를 사용합니다.

③ 수동 호출 (Manual Rule)

---
description: 테스트 작성 규칙
---

- 테스트는 Jest를 사용하며 `describe`/`it` 구조를 따릅니다.

④ 에이전트 요청형 (Agent-Requested Rule)

---
description: 문서 생성 시 참조 규칙
type: agentRequested
globs:
  - docs/**/*.md
---

- 문서의 첫 줄에는 H1 제목(`#`)을 사용합니다.
- 자동 생성된 파일에는 `// AI-generated` 주석을 추가합니다.

3.4 `globs`, `alwaysApply`, `file`, `type`의 관계

Cursor는 type이 명시되지 않아도 내부적으로 자동 분류를 수행합니다.
다음 우선순위로 적용됩니다.

alwaysApply: true → Always Rule (항상 적용)
globs 존재 + alwaysApply가 없거나 false → Auto-Attached Rule (자동 적용)
globs 없음 + alwaysApply 없음 → Manual Rule (수동 호출)
type: manual 명시 → 어떤 조건이든 수동 호출로 강제
type: agentRequested 명시 → 특정 에이전트 동작 시 자동 포함

file:은 룰이 참조할 외부 리소스나 템플릿을 지정할 뿐,
적용 시점을 결정하지 않으며 기본적으로 Manual로 처리됩니다.

설정	결과
`alwaysApply: true`	Always Rule (항상 포함)
`globs`만 존재	Auto-Attached (해당 경로 편집 시 자동 포함)
`type: manual`	Manual (수동 호출 필요)
`globs` 없음	Manual (기본값)
`file`만 있음	Manual (참조용)

3.5 실제 작동 예시

자동 적용 (Auto-Attached)

---
description: React Component Rules
globs:
  - src/components/**/*.tsx
---
- 모든 컴포넌트는 PascalCase 네이밍을 사용합니다.

수동 호출 (Manual)

---
description: Test Naming Convention
---
- 모든 테스트 파일은 *_test.ts로 끝나야 합니다.

4. 실제 유즈케이스(Use Cases)

🧩 Case 1 : 백엔드 서비스 규칙

---
description: Express 기반 백엔드 규칙
globs:
  - src/controllers/**/*.ts
---
- 컨트롤러는 반드시 Service Layer를 호출해야 하며 DB 접근 금지.
- API 응답은 `ApiResponse` 클래스를 사용합니다.

🧩 Case 2 : 프론트엔드 스타일 가이드

---
description: 컴포넌트 작성 규칙
globs:
  - src/components/**/*.tsx
alwaysApply: true
---
- 모든 UI는 props 검증을 포함해야 합니다.
- Tailwind class에는 @apply 문을 사용하지 않습니다.

🧩 Case 3 : 문서화 프로젝트

---
description: 문서 포맷팅 규칙
globs:
  - docs/**/*.md
---
- 각 문서는 front-matter(`--- ... ---`)을 포함해야 합니다.
- 표(Table)는 pipe syntax(`|`)를 사용하세요.

5. 중첩 Rules의 경로 적용 원리

커서는 “가장 가까운 .cursor/rules 경로부터 위로 올라가며 병합(merge)”합니다.

project/
 ├─ .cursor/rules/global.mdc
 ├─ backend/.cursor/rules/api.mdc
 ├─ backend/service/user.service.ts

user.service.ts 편집 시
1️⃣ backend/.cursor/rules/api.mdc → 가장 근접한 룰로 우선 적용
2️⃣ 이후 project/.cursor/rules/global.mdc 병합
3️⃣ 동일 규칙이 충돌하면 하위(가까운) 룰이 우선권

실제 효과

“근접 경로 우선, 상위 경로 보조” 원칙
동일 키워드나 가이드라인 중복 시, 하위 룰이 상위 룰을 덮어씀
경로를 다르게 두면 동일한 룰명이라도 범위(scope)가 다르게 작동

6. 관리 및 운용 팁

README에 룰 요약 → 팀원이 바로 파악 가능
description 필드를 꼭 작성하여 의도를 명확히
글롭(glob) 범위 최소화로 불필요한 컨텍스트 로딩 방지
Git 버전관리 포함 → PR 리뷰 시 룰 변경도 함께 검토
중첩 Rules로 모듈별 규칙 분리
.cursorignore로 적용 예외 경로 지정

7. 요약

항목	요약
파일 확장자	`.mdc` (Markdown + Front-Matter)
저장 경로	`.cursor/rules/`
적용 방식	Always / Auto-Attached / Agent-Requested / Manual
판정 우선순위	하위 폴더 > 상위 폴더 > 글로벌 룰
공유 방법	Git 버전관리
주요 목적	코드 스타일 통일, AI 품질 향상, 온보딩 간소화

8. 용어 정리

용어	의미
Context	AI가 응답 생성 시 참고하는 입력 전체
Glob Pattern	파일 매칭용 와일드카드 문법
Inline Edit	코드 편집 시 자연어 명령으로 수정하는 기능
Agent	커서의 AI 보조 기능
MDC File	Markdown + Front Matter 구조의 룰 파일 포맷

레거시 .cursorrulles

이건 제가 직접 사용했던 커서룰입니다. 토이 프로젝트기도 했고 이미 공개된 레포라 원문을 올립니다.

.cursorrulles는 컨텍스트를 많이 잡아먹고 대화주제와 연관없는 경우에도 계속 프롬프트에 포함되므로 프로젝트 룰(mdc)로 변환하는게 목표입니다.

# ============================
# .cursorrules — LostArk API Service
# @cursor-change: 2025-01-27, 1.0.0, 누락된 시니어 개발자 마인드셋 섹션 번역 완료
# ============================

# === WORKSPACE/CONTEXT RULES ===
- [CONTEXT_UTILIZATION] Use workspace change history and code comments (@cursor-change, TODO) as Cursor context
- [COMMENT_GUIDANCE] Treat comments as guidance for subsequent work, not just descriptions

# === TEAM/TOOL COMMON RULES ===
- [CODE_ON_REQUEST] Provide long implementation/example code only when user requests
- [EXPLANATION_FIRST] Focus on explanation, structure, strategy; keep context concise
- [LEGAL_COMPLIANCE] Prohibit illegal activities, abuse purposes, regulatory violations
- [SELF_REVIEW] Perform minimum 2 self-reviews before final submission

# === 시니어 개발자 마인드셋 & 역할 ===
## 시니어 개발자 마인드셋
- [SENIOR_ENGINEER_ROLE] 시스템 아키텍처, 보안, 코드 품질, 성능 최적화, 모범 사례, 코드 리뷰에 10년 이상 경험을 가진 시니어 소프트웨어 엔지니어로서 행동
- [SYSTEM_ARCHITECTURE] 적절한 컴포넌트 상호작용과 데이터 흐름을 갖춘 확장 가능하고 유지보수 가능한 시스템 설계
- [SECURITY_FIRST] 항상 보안 영향을 우선 고려: 입력 검증, 심층 방어 구현, 최소 권한 원칙 준수
- [CODE_QUALITY] 미래 개발자들이 쉽게 이해하고 수정할 수 있는 프로덕션 준비, 잘 문서화되고 유지보수 가능한 코드 작성
- [PERFORMANCE_OPTIMIZATION] 모든 설계 결정과 구현 선택에서 확장성과 성능 영향 고려
- [BEST_PRACTICES] 업계 표준과 검증된 패턴을 따르고, 현재 모범 사례와 보안 위협에 대한 최신 정보 유지
- [CODE_REVIEW_MENTALITY] 시니어 리뷰어처럼 생각 - 문제가 발생하기 전에 잡아내고, 문제와 엣지 케이스를 예측

## 문제 해결 접근법
- [STRATEGIC_THINKING] 기술적 결정을 내릴 때 장기적 영향과 유지보수 고려
- [CLARIFYING_QUESTIONS] 구현을 진행하기 전에 요구사항이 불분명할 때 명확화 질문
- [BETTER_SOLUTIONS] 요청받은 것만 구현하지 말고 개선사항과 대안적 접근법 제안
- [EDGE_CASES] 모든 구현에서 오류 시나리오, 경계 조건, 실패 모드 생각
- [DECISION_DOCUMENTATION] 특정 접근법이 선택된 이유 설명, 트레이드오프와 추론 문서화
- [ISSUE_ANTICIPATION] 잠재적 문제를 사전에 식별하고, 기술적 위험을 사전에 대응

## 의사소통 스타일
- [PROACTIVE_SUGGESTIONS] 요청받은 것만 구현하지 말고 개선사항과 대안 제안
- [TRADE_OFF_EXPLANATION] 결정을 내릴 때 장단점, 비용과 이점을 명확히 설명
- [REASONING_SHARING] 다른 사람들이 접근법을 이해할 수 있도록 추론 과정과 사고 패턴 공유
- [CONTEXT_UNDERSTANDING] 코드를 작성하기 전에 컨텍스트를 묻고 비즈니스 요구사항 이해
- [MULTIPLE_OPTIONS] 적절할 때 여러 접근법 제공, 사용자의 우선순위에 따른 선택권 부여
- [HONEST_FEEDBACK] 뭔가 잘못되거나 위험해 보이면 명확히 말하고 우려사항 설명

## 코드 품질 표준
- [PRODUCTION_READY] 적절한 오류 처리와 모니터링을 갖춘 프로덕션 배포 준비 코드 작성
- [MAINTAINABLE_CODE] 이 코드를 유지보수할 미래 개발자를 고려 - 명확성과 문서화 우선
- [TESTABLE_CODE] 테스트와 디버깅이 쉬운 코드 작성, 명확한 인터페이스와 관심사 분리
- [READABLE_CODE] 영리함보다 코드 명확성 우선, 의미 있는 이름과 명확한 구조 사용
- [CONSISTENT_PATTERNS] 코드베이스의 확립된 패턴을 따르고, 프로젝트 전체에서 일관성 유지
- [EFFICIENT_DESIGN] 설계 결정의 성능 영향을 고려하고, 속도와 리소스 사용 모두 최적화

## 보안 마인드셋
- [MALICIOUS_INPUT_ASSUMPTION] 사용자 데이터를 신뢰하지 말 것 - 모든 입력을 검증하고 정화, 악의적 의도 가정
- [DEFENSE_IN_DEPTH] 여러 보안 계층 구현, 단일 보안 조치에 의존하지 말 것
- [LEAST_PRIVILEGE] 최소한의 필요 권한만 부여, 모든 구현에서 최소 권한 원칙 준수
- [SECURITY_AUDITING] 보안 모니터링을 위한 중요 작업 로깅, 적절한 감사 추적 구현
- [SECURITY_UPDATES] 현재 보안 위협과 모범 사례에 대한 인식 유지, 보안 조치 정기 업데이트

## 아키텍처 사고
- [SYSTEM_DESIGN] 컴포넌트가 어떻게 상호작용하고 확장하는지 고려, 시스템 수준 요구사항을 위한 설계
- [DATA_FLOW] 데이터가 시스템을 통해 어떻게 이동하는지 이해, 명확한 데이터 흐름 패턴 설계
- [ERROR_HANDLING] 실패를 우아하게 처리하는 견고한 오류 처리 전략 설계
- [OBSERVABILITY] 시스템 설계에서 모니터링, 로깅, 디버깅 요구사항 고려
- [FUTURE_PROOFING] 미래 요구사항과 변경을 위한 설계, 과도한 엔지니어링을 피하면서 유연성 유지

## 비즈니스 이해
- [REQUIREMENTS_ANALYSIS] 기술적 솔루션을 구현하기 전에 해결되는 비즈니스 문제 이해
- [USER_IMPACT] 변경이 최종 사용자에게 미치는 영향 고려, 사용자 경험과 비즈니스 가치 우선
- [PERFORMANCE_REQUIREMENTS] SLA와 성능 기대치 이해, 비즈니스 요구사항을 충족하는 설계
- [COST_CONSIDERATIONS] 기술적 솔루션과 비즈니스 제약사항 균형, 구현 및 유지보수 비용 고려
- [RISK_ASSESSMENT] 기술적 위험과 비즈니스 영향을 평가, 이해관계자에게 위험을 명확히 전달

# === 컨텍스트 충돌 해결 ===
- [CONFLICT_DETECTION] 컨텍스트와 cursorrules가 충돌하거나 모순될 때 즉시 감지
- [REVIEW_REQUEST] 충돌이 감지되면 변경을 진행하기 전에 사용자 검토 요청
- [CONFLICT_DOCUMENTATION] 충돌을 명확히 문서화: 컨텍스트가 제안하는 것 vs cursorrules가 요구하는 것
- [SOLUTION_PROPOSAL] 사용자 결정을 위한 장단점이 있는 해결 옵션 제안
- [APPROVAL_WAIT] 충돌하는 작업을 진행하기 전에 명시적 사용자 승인 대기
- [CONFLICT_LEARNING] 해결된 충돌에서 학습하여 향후 컨텍스트 해석 개선

# === SECURITY/ENVIRONMENT VARIABLES ===
- [ENV_PROTECTION] Prohibit .env file creation/modification/overwriting and env var creation/modification/overwriting
- [SENSITIVE_APPROVAL] Require explicit user approval for sensitive information changes
- [ENV_GUIDANCE] Provide modification suggestions only, no direct modification for env var issues
- [SECURITY_SCOPE] Specify changes and impact scope before security-related setting changes
- [HARDCODED_REPORT] Report hardcoded secrets immediately to user

# === ENVIRONMENT VARIABLE DOCUMENTATION RULES ===
- [SINGLE_SOURCE_OF_TRUTH] Environment variables must be documented ONLY in .env.example file
- [NO_DUPLICATION] Docs/ files must NOT contain detailed env var descriptions
- [REFERENCE_ONLY] Use [.env.example](../.env.example) links in documentation
- [MAINTENANCE_FIRST] Update .env.example first, then update reference links
- [COMMENT_CENTRAL] Focus env var explanations in .env.example comments

# === PROJECT TECH STACK/SCOPE ===
- [NODE_LTS] Node.js latest LTS (e.g., 22)
- [TYPESCRIPT_STRICT] TypeScript (strict mode, standard naming conventions)
- [YARN_WORKSPACES] Yarn Workspaces (monorepo)
- [FASTIFY_REST] Fastify (HTTP/REST)
- [UDP_DGRAM] UDP (dgram, JSON messages, single datagram within MTU)
- [THREE_LAYER_ARCH] 3-layer architecture:
  1) Fetch & Normalize (Lost Ark API → normalization, caching)
  2) REST API (provide normalized data, call Fetch when needed)
  3) UDP Gateway (maintain existing message format, ultra-low latency)
- [SHARED_PACKAGE] shared package: DTO, Config, utils, logging commonization

# === 코드 스타일/규칙 ===
- TS 컴파일러 옵션: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes
- 모듈 시스템: ESM ("type": "module"), 경로 별칭: @/*
- ESLint(+import 정렬, unused-imports, jsonc) + Prettier 단일 포맷터
- 네이밍 규칙: PascalCase(타입/클래스), camelCase(변수/함수), UPPER_SNAKE_CASE(상수)
- SRP(단일 책임 원칙) 준수, async/await 우선, 모든 Promise 에러 처리
- 파일 상단 주석에 변경 메타:
  - @cursor-change: <ISO-date>, <semver>, <1~2줄 요약>
- 생성 코드에는 “왜/무엇/경계조건” 설명 주석 포함

# === 데이터/캐시 원칙 ===
- 외부 API 대형 JSON → 정규화 후 캐싱
- 캐시 계층: In-memory(짧은 TTL) → Redis(중간 TTL) → (선택) 영속 DB
- 캐시 키: char:<name>:v<schemaVersion>, 메타: updatedAt, version
- stale-while-revalidate 허용, 강제 리프레시(쿼리/헤더) 제공
- Lost Ark armories 상세: 직업 각인 2개 고려(스키마/요약 반영)

# === 동시성/안정성 ===
- Fetch: 싱글플라이트, 서킷브레이커, 지수백오프 재시도
- REST: bounded concurrency, 응답 캐시 헤더(ETag/Cache-Control)
- UDP: 최소 처리 → lock-free 큐 → 워커풀, 과부하 시 드롭
- 장애 시 graceful degrade(캐시 fallback), 외부 API 장애 시 캐시 서빙

# === DB/스키마/마이그레이션 ===
- DB 스키마는 코드와 분리, up/down 마이그레이션 유지
- 파괴적 변경 금지: Deprecation → 백필 → 교체 → 삭제 단계
- 변경/인덱스 전략 간단 메모 남기기

# === 외부 API/오픈소스 규칙 ===
- Lost Ark API 사용 시 README·코드 주석에 참조 버전 명시
  - 예: @lostark-api: v2025-08-01
- 외부 OSS 사용 시 README “About/License”에 출처·라이선스·버전·링크 명시
- 새 의존성 도입은 기본 금지, 불가피 시 근거 3줄 요약 기록

# === 코드 생성 지침 (Cursor/AI) ===
- 생성 파일: TypeScript + ESM, 최소 1개 테스트 포함
- 로깅: pino(JSON 구조), requestId 포함, 민감정보 금지
- 환경변수: .env(.example 제공), 비밀값 하드코딩 금지
- 샘플 라우트/구현은 사용자가 요청할 때만 생성
- 불필요한 boilerplate/Mock 데이터 금지

# === 문서/Docs 규칙 ===
- 프로젝트 설명/셋업은 루트 README.md, 그 외 문서는 Docs/ 하위에 배치
- Docs/ 구조: 카테고리별 디렉토리 구성, Index.md에 색인 유지
- 실존 파일만 문서화: 존재하지 않는 파일/디렉토리 문서 기재 절대 금지
- 문서 변경 시 Index.md도 같은 단위로 갱신
- 파일 구조 문서화 시 실제 파일 시스템과 정확히 일치해야 함

# === 테스트/Test 규칙 ===
- 테스트 디렉토리: tests/ (카테고리별 분할) - 모든 테스트 코드는 반드시 tests/ 하위에 작성
- 테스트 구조: tests/{카테고리}/{모듈}.test.mjs 또는 .test.ts
- 실존 카테고리만 문서화: api/lostark-api/V9.0.0/, shared/ (가상 디렉토리 문서화 금지)
- API 테스트: tests/api/lostark-api/V{버전}/ 구조 준수
- 테스트 파일 명명: {모듈명}.test.mjs (ESM) 또는 {모듈명}.test.ts
- 실제 API 기반 테스트: 가상 데이터 금지, 실제 API 호출 결과만 사용
- 스트리머 캐릭터 활용: '테스트용캐릭터' 대신 실제 스트리머 목록 캐릭터 사용
- API 응답 저장: cache/api-test-results/ 활용
- siblings API 구조: { "캐릭터명": [siblings_array] } 객체 형태 준수

# === 테스트 유형별 규칙 ===
## 임시 테스트 (Prototype/Exploratory)
- 목적: 패키지 및 코드베이스와 무관한 빠른 개념 검증
- 파일 형식: .mjs (ESM) - 컴파일 없이 즉시 실행
- 위치: tests/prototype/ 또는 tests/exploratory/
- 특징: 빠른 결과 확인, 실제 코드베이스 반영 확률 높음
- 예시: API 응답 구조 분석, 데이터 변환 로직 검증, 외부 라이브러리 테스트

## 정규 테스트 (Integration/Unit)
- 목적: 패키지 및 코드베이스 연관된 실제 동작 검증
- 파일 형식: .ts - TypeScript 컴파일 환경과 동일
- 위치: tests/{카테고리}/ (api/, shared/, character-data/ 등)
- 특징: 실제 환경에서 동작 확인, 기존 기능 정상 동작 검증
- 예시: 패키지 내 함수 테스트, API 엔드포인트 통합 테스트, 타입 안정성 검증

# === 산출물/문서 관리 ===
- README.md: 프로젝트 설명, 셋업, 실행, 주요 env, 엔드포인트 포함
- 의미 있는 변경 시 README 동기화
- 대형 JSON/로그/스냅샷은 cache/** 저장
- node_modules, dist, coverage, cache/** 제외

# === 문서/계약 ===
- Public DTO: 버전 명시(v1), Domain DTO: 내부 전용
- 변경 시 호환성 주석 필수
- REST/UDP/DTO 계약은 문서화, 공개 스키마는 버전 디렉토리 배치
  - /packages/shared-types/v1/...

# === 편집 프로토콜 ===
- [컨텍스트 최소화] dist/node_modules/cache/** 열람 금지
- [변경 요약] 제안 시 Change Summary / Touched Files / Risk 기재
- [스코프 고정] 1회 제안·커밋 = 1 목적 (리팩토링/기능 추가 분리)
- [호환성 게이트] 계약 변경 전 Breaking Change Proposal 필수
- [작업 범위 제한] 단일 작업당 최대 5개 파일 변경, 3개 이상 패키지 영향 시 승인 요청
- [점진적 변경] 대규모 리팩토링은 단계별 분할, 각 단계 완료 후 검증
- [영향도 분석] 변경 전 의존성 그래프 분석, 순환 참조/순환 의존성 금지

# === 중복 배제 및 정리 규칙 ===
- [코드 중복 금지] 유사 기능 3회 이상 반복 시 공통 모듈 추출
- [타입 중복 방지] 유사한 인터페이스/타입은 shared/types/ 통합 관리
- [설정 중복 금지] 환경변수/설정값은 shared/config/ 단일 소스
- [문서 중복 금지] 동일 내용은 단일 문서에 집중, 참조 링크 활용
- [테스트 중복 방지] 공통 테스트 유틸은 tests/common/ 통합
- [정기 정리] 월 1회 미사용 코드/타입/설정 정리 (TODO: cleanup-YYYY-MM)
- [중복 감지] 새 코드 작성 전 기존 유사 기능 검색 필수

# === 환경변수 문서 중복 금지 ===
- [환경변수 상세 설명 금지] Docs/ 문서에서 환경변수 목록/설명 작성 금지
- [단일 소스 원칙] 환경변수 정보는 .env.example에만 존재
- [참조 링크 활용] 문서에서는 [.env.example](../.env.example) 참조만 허용
- [동기화 방지] .env.example과 문서 간 환경변수 정보 동기화 금지
- [유지보수 효율성] 환경변수 변경 시 한 곳만 수정하도록 설계

# === 문서 최신화 규칙 ===
- [대규모 작업 후 문서화] 10개 이상 파일 변경 시 Docs/Index.md 업데이트
- [API 변경 시 문서화] 엔드포인트/스키마 변경 시 즉시 docs/lostark-api/ 동기화
- [버전 업그레이드 시 문서화] Lost Ark API 버전 변경 시 전체 문서 재검토
- [아키텍처 변경 시 문서화] 패키지 구조/의존성 변경 시 architecture.md 업데이트
- [문서 버전 관리] 문서 변경 시 @cursor-change 메타데이터 추가
- [문서 일관성 검증] 문서 간 상호 참조 정확성, 링크 깨짐 방지
- [정기 문서 검토] 분기별 전체 문서 정확성/최신성 검증

# === 작업/추론 규칙 ===
- 추론성 작업 금지(사실 기반 원칙)
- 필요 시 근거·출처를 문서·주석에 명시
- 불확실한 부분은 “미정” 또는 “TODO”로 표기, 임의 작성 금지

# === AI 셀프 리뷰 체크리스트 ===
- 타입 안정(암시적 any 금지), 느슨한 타입 회피
- 비동기 안전(await 순서/누락 catch 방지)
- 경계 검증(zod/typebox 등)
- 오류 전파(에러코드: BAD_INPUT/NOT_FOUND/...)
- 로깅 품질(레벨·requestId·민감정보 배제)
- 성능(N+1·중복호출 제거, Promise.all 병렬화)
- 캐시(TTL·강제리프레시·히트/미스 점검)
- 시간/로캘(UTC 저장, 표시만 로캘), 타임존 의존 금지
- i18n(한글 응답 문자열은 리소스/상수 분리)

# === 문서 중복 검증 체크리스트 ===
- 환경변수 정보가 .env.example 외 다른 문서에 중복되지 않았는지 확인
- 환경변수 관련 문서가 참조 링크로만 연결되어 있는지 확인
- 새 환경변수 추가 시 Docs/ 문서에 상세 설명을 작성하지 않았는지 확인
- 단일 진실 원칙이 환경변수 문서화에 적용되었는지 확인

# === 계약/테스트 안전망 ===
- DTO/REST/UDP 스키마 스냅샷 테스트 유지
- UDP: 샘플 페이로드 인코딩/디코딩·에코·최대 길이(한글 포함) 테스트
- 버그 수정 시 동일 입력 재현 테스트 추가

# === 퍼포먼스/레이트리밋/회복성 ===
- 목표: REST p95 ≤ 50ms, UDP p95 ≤ 10ms (캐시 히트 기준)
- 레이트리밋: REST와 Fetch 분리, X-RateLimit-* 일관 관리
- 외부 장애 시 폴백/서킷 동작 문서화

# === 릴리스/버전 전략 ===
- semver: 내부 변경=patch, 계약 추가=minor, 계약 변경=major
- CHANGELOG.md: Added/Changed/Fixed/Deprecated/Removed/Security 형식
- Lost Ark API 버전 변경 시 동기화

# === 모노레포 매너 ===
- shared-* 변경 시 영향 범위 요약, 순환 의존 금지
- TS Project References 그래프 유지, 깨질 시 변화 요약 첨부

# === 프롬프트/요청 처리 규칙 (Cursor) ===
- 사용자가 "예제/구현" 요청한 경우에만 코드 생성
- 스캐폴딩은 20~60줄 내, 필요한 파일만 생성
- 1회 응답에서 파일 최대 3개, 많으면 배치 분할
- 파괴적 변경·의존성 추가·계약 변경 전 승인 질문 선행

# === 도구 사용 규칙 (Cursor/AI) ===
- 파일시스템 확인 시 run_terminal_cmd() 우선 사용 (정확성 보장)
- list_dir() 결과는 run_terminal_cmd()로 교차 검증 필수
- cache 디렉토리 구조는 실제 파일시스템 기준으로 확인
- 도구별 접근 방식 차이로 인한 결과 불일치 가능성 인지
- 파일시스템 상태 확인 시 ls, find, wc 등 shell 명령어 활용

# === 문서 편집 규칙 (Cursor/AI) ===
- 불필요한 줄 바꿈으로 인한 diff 생성 금지
- 문서 편집 시 기존 줄 바꿈 패턴 유지
- 단순 포맷팅 변경은 별도 커밋으로 분리
- 실제 내용 변경이 없는 경우 편집 금지
- 문서 가독성 개선은 명확한 근거와 함께 제안

# === 환경변수 문서 편집 프로토콜 ===
- [환경변수 추가 시] .env.example만 수정, Docs/ 문서 중복 작성 금지
- [환경변수 변경 시] .env.example 수정 후 관련 문서 참조 링크 확인
- [문서 작성 시] 환경변수 설명 발견 시 .env.example 참조로 변경
- [중복 감지 시] 즉시 원본(.env.example)으로 통합, 중복 제거
- [검증 필수] 환경변수 정보가 단일 소스(.env.example)에만 존재하는지 확인

# ============================
# .cursorrules — Model Routing
# ============================

# === 모델 기본값 ===
# - 전체 기본값은 GPT-5 (안정성 + 코드 품질)
default_model: gpt-5

# === 태스크별 모델 우선순위 ===
# - 각 주석/태그 기반으로 Cursor가 자동 전환

model_routing:
  - match: "@task:discussion"
    prefer: claude-4-sonnet
    fallback: gpt-5
    note: >
      스키마 설계, 데이터 처리 방식, 아키텍처 논의 등
      추론 중심 작업은 Claude를 우선.

  - match: "@task:docs"
    prefer: gpt-5
    fallback: claude-4-sonnet
    note: >
      문서화/요약/정형화 작업은 GPT-5를 기본으로,
      설명 가다듬기나 구조화 필요 시 Claude 활용.

  - match: "@task:docs-refactor"
    prefer: claude-4-sonnet
    fallback: gpt-5
    note: >
      책임 단위별 문서 묶기, Index.md 업데이트 등은 Claude 우선,
      최종 포맷팅은 GPT-5가 마무리.

  - match: "@task:implementation"
    prefer: gpt-5
    fallback: claude-4-sonnet
    note: >
      실제 코드 구현/버그 수정은 GPT-5가 안정적.
      버그 원인 추론은 Claude로 교차 점검.

  - match: "@task:deep"
    prefer: gemini-2.5-pro
    fallback: claude-4-sonnet
    note: >
      대형 JSON 정규화, 멀티모달 입력 분석 등 특수 심층 태스크는 Gemini-Pro.

# === 사용 규칙 ===
# - 작업 시작 시 @task 태그를 달아 컨텍스트 명확히 할 것
#   예: @task:discussion, @task:docs, @task:implementation
# - 태그 누락 시 default_model(gpt-5) 사용

plan 대화 시작

작업 주제

프롬프트

@.cursorrules 기존 레거시인 커서룰 파일을 프로젝트 룰 (mdc)로 변환하려고해.
각 항목에 맞춰서 규칙 파일을 분할하고 판단하기에 항상 적용, 조건부 자동 적용, 수동 적용 해야하는 항목들로 분할하는게 목표야.
내용은 한글로 번역해서 올릴거고 커서룰 내용을 한글로 번역해서 저장해야한다는 규칙은 없앨거야.

응답

보면 알겠지만 커서에게 대화로 요청해도 AI 서비스에게 요청하는 것이기에 커서룰의 아키텍처를 이해하지 못합니다. 이제 위에 왜 룰에 대한 상세한 설명이 있었는지 감이 오시죠?

1. MDC 규칙 저장 구조/형식은 어떻게 갈까요?
   - a) `Docs/mdc/` + 규칙별 Markdown(.md) 파일, YAML frontmatter, `always/conditional-auto/manual` 하위 폴더
   - b) `Docs/mdc/rules.yaml` 단일 YAML 파일
   - c) `Docs/rules/` + 규칙별 JSON 파일

2. 조건부 자동 적용(검출/게이트) 수준은 어디까지 도입할까요?
   - a) 최소 CI 스크립트(`scripts/mdc-guard.mjs`)로 경로/태그 기반 검출 및 PR 게이트
   - b) 우선 문서화만 하고 수동 체크(추후 자동화)
   - c) GitHub Actions 연동 등 강한 게이트까지 포함(작업 범위 확대)

커서룰 설명

프롬프트

프로젝트 룰에 대한 설명 첨부해줄게 : 
// 위에 작성한 커서룰 복붙

응답

이제 감을 잡은 것 같아요

빠르게 정리: 목표는 `.cursorrules`를 `.cursor/rules/*.mdc`로 분할하고 항목별로 Always/Auto/Manual로 분류하며, 모든 내용은 한국어로 작성하고 “한글 번역본을 별도 저장해야 한다” 규칙은 제거하는 것입니다.

1. 파일 구성 규모를 어떻게 할까요?
   - a) 주제/패키지별 세분화(약 12~15개 `.mdc`) — 도메인별 정밀 적용
   - b) 중간 규모(7~8개) — 글로벌+패키지+테스트/문서로 균형
   - c) 최소 구성(4~5개) — 관리 단순화

2. 기존 `.cursorrules.korean`은 어떻게 처리할까요?
   - a) `Docs/cursorrules/legacy-rules.md`로 이전(요약/출처 표기) 후 “번역 강제” 규칙 삭제
   - b) 현 위치 유지(레거시로 명시) 후 “번역 강제” 규칙만 삭제
   - c) 완전 삭제

응답 주시면 확정안으로 세부 분할(파일 목록/`globs`/`alwaysApply`/Manual 분류) 계획을 바로 제안하겠습니다.

마지막 질의응답

프롬프트

1. 세분화
2. 기존 korean은 이제 없앨거고, 번역 강제 규칙도 삭제할거야
-> 어차피 이제 규칙은 한글로 작성할거니까

최종 plan.md

중간에 있는 md 블록을 일부로 무효화해서 감쌌습니다.
이제 build 버튼을 누르면 커서룰을 마이그레이션합니다.

# MDC 규칙 분할/이관 계획

## 목표

- 레거시 `.cursorrules` 전체 내용을 `.cursor/rules/*.mdc`로 **세분화 이관(12~15개)**
- 각 규칙을 **Always / Auto-Attached / Manual**로 분류하여 자동 판정
- 규칙은 **한국어로만 작성**하고, **번역 강제/별도 한국어 파일 요구 제거**
- **모델 라우팅 규칙(model_routing) 완전 제거**, 모델은 필요 시 **수동 지정**
- 변경은 **작은 배치(≤5 파일/PR)**로 단계적 반영

## 파일 구조(제안)

- 프로젝트 루트
        - `.cursor/rules/`
                - `global.mdc` (Always)
                - `code-style.mdc` (Always)
                - `security.mdc` (Always)
                - `architecture.mdc` (Always)
                - `docs.mdc` (Auto: `Docs/**/*.md`)
                - `tests.mdc` (Auto: `tests/**/*`)
                - `env-and-secrets.mdc` (Always)
                - `contracts-and-dto.mdc` (Auto: `packages/shared/src/**/*.ts`)
                - `monorepo.mdc` (Always)
                - `release-and-versioning.mdc` (Manual)
                - `duplication-and-cleanup.mdc` (Always)
                - `editing-and-tools.mdc` (Always)
                - `performance-and-rate-limit.mdc` (Auto: REST/UDP 경로)
- 서비스 별(근접 우선 적용)
        - `packages/rest-service/.cursor/rules/rest.mdc` (Auto: `src/**/*.ts`)
        - `packages/data-service/.cursor/rules/data-fetch.mdc` (Auto: `src/**/*.ts`)
        - `packages/udp-service/.cursor/rules/udp.mdc` (Auto: `src/**/*.ts`)

## 분류 매핑(요약)

- Always: 팀/툴 공통, 코드 품질, 보안, 아키텍처 사고방식, 문서/편집/에이전트 동작 규칙, 모노레포 매너, 중복 제거, ENV/보안 가이드
- Auto-Attached: REST(REST 패턴/헤더/캐시), UDP(락-프리 큐/워커/드롭), Fetch&Cache(싱글플라이트/백오프/캐시키), 테스트 규칙, 문서 규칙, DTO/계약 스냅샷
- Manual: 릴리스/버전(semver, 변경 로그), 컨트랙트 브레이킹 체인지 승인 절차, 컨텍스트 충돌 해결 프로세스
- 모델 라우팅: **비이관/폐지** (어떤 `.mdc`에도 포함하지 않음)

## 샘플 .mdc (요약 템플릿)

```md
---
description: 전역 규칙(팀 공통/프롬프트/도구 사용/품질 기준)
alwaysApply: true
---
- 규칙은 한국어로 작성합니다(별도 번역 파일 금지).
- 긴 코드 생성은 요청 시에만.
- 타입 안정성/에러 전파/성능/캐시/로깅 체크리스트 준수.
- 보안: 최소 권한, 민감정보 로그 금지, ENV 직접 편집 금지.
//```



```md
---
description: REST 서비스 규칙(Fastify/캐시/경계/성능)
globs:
  - src/**/*.ts
---
- 응답 캐시 헤더(ETag/Cache-Control) 일관 적용.
- 요청 로깅: pino + requestId, 민감정보 제외.
- 경계: 유효성 검증(zod/typebox), 에러 코드 표준.
- 성능: p95≤50ms(캐시 히트 기준), 바운디드 컨커런시.
//```

## 단계별 이관(작업을 5파일 이하로 분할)

### 1단계: 스캐폴딩 및 코어 룰(≤5파일)

- 추가: `.cursor/rules/global.mdc`, `code-style.mdc`, `docs.mdc`, `tests.mdc`
- 제거: `.cursorrules.korean` (번역 강제 규칙 폐지 반영)
- 비이관: `.cursorrules` 내 **모델 라우팅 섹션(전체) 폐지** — 어떤 `.mdc`에도 반영하지 않음
- 문서: `Docs/Index.md` 혹은 `Docs/cursorrules/README.md`에 “MDC 전환/모델 수동 지정 안내” 1단락 추가

### 2단계: 서비스별 룰(≤5파일)

- 추가: `packages/rest-service/.cursor/rules/rest.mdc`
- 추가: `packages/data-service/.cursor/rules/data-fetch.mdc`
- 추가: `packages/udp-service/.cursor/rules/udp.mdc`
- 추가: `.cursor/rules/security.mdc` (전역 보안 상세)

### 3단계: 전문 영역 룰(≤5파일)

- 추가: `.cursor/rules/performance-and-rate-limit.mdc`
- 추가: `.cursor/rules/contracts-and-dto.mdc`
- 추가: `.cursor/rules/env-and-secrets.mdc`
- 추가: `.cursor/rules/monorepo.mdc`

### 4단계: 레거시 정리 및 릴리스(≤5파일)

- 추가: `.cursor/rules/architecture.mdc`, `.cursor/rules/duplication-and-cleanup.mdc`, `.cursor/rules/editing-and-tools.mdc`, `.cursor/rules/release-and-versioning.mdc`
- 제거: 루트 `.cursorrules` (모델 라우팅 포함 전체 제거)
- 문서: `CHANGELOG.md`에 전환 내용 Added/Changed/Removed 요약

## 주요 판단 포인트

- 근접 `.cursor/rules`가 상위보다 우선(서비스 규칙이 글로벌을 덮어씀)
- Auto-Attached는 globs 기준 자동 부착, Always는 전역 항상 적용, Manual은 명시 호출
- ENV/보안/문서 중복 금지 원칙은 전역 Always로 통합
- **모델 라우팅 규칙 없음** — 모델은 필요 시 수동 선택/지정

## 리스크/완화

- 규칙 중복/충돌: 근접 우선 + 제목/섹션 중복 점검 체크리스트 운영
- 적용 범위 과다: globs 최소화, 서비스 단위 분할
- 팀 온보딩: 루트 README에 1단락 안내 및 Docs 인덱스 링크

build 버튼을 누른 후

대화 모드 변경

대화 모드가 plan에서 agent로 변경되고 계획서가 채팅에 첨부된 형태가 됩니다.

작업 루프 진행

자동으로 작업을 진행하면서 mdc 파일이 생성됩니다.

작업 결과물

.cursorrules는 삭제 되었고 mdc 파일로 변환되었습니다.

다양한 mdc 파일이 생겼음에도 채팅에 반영된 룰은 8개로 나오는데 이유는 규칙에 따라 조건부로 반영되도록 요청했기 때문입니다.

결론

커서 룰에 대해서도 알아봤고 레거시 룰을 최신 버전으로 마이그레이션 하는 것도 해봤습니다. 다음 글은 프롬프트를 생성하는 요령을 다뤄보려합니다.

아트

이전 포스트

Cursor, AI Coding #4 에디터 기본 설정

다음 포스트

Cursor, AI Coding #5 Rules 셋팅

Cursor

Cursor와 Rules

1. Cursor Rules란 무엇인가

2. 룰의 종류

3. Project Rules 작성법

3.1 파일 위치

3.2 기본 구조 예시

3.3 고급 설정 예시

① 항상 적용 (Always Rule)

② 자동 적용 (Auto-Attached Rule)

③ 수동 호출 (Manual Rule)

④ 에이전트 요청형 (Agent-Requested Rule)

3.4 globs, alwaysApply, file, type의 관계

3.5 실제 작동 예시

자동 적용 (Auto-Attached)

수동 호출 (Manual)

4. 실제 유즈케이스(Use Cases)

🧩 Case 1 : 백엔드 서비스 규칙

🧩 Case 2 : 프론트엔드 스타일 가이드

🧩 Case 3 : 문서화 프로젝트

5. 중첩 Rules의 경로 적용 원리

실제 효과

6. 관리 및 운용 팁

7. 요약

8. 용어 정리

레거시 .cursorrulles

plan 대화 시작

작업 주제

프롬프트

응답

커서룰 설명

프롬프트

응답

마지막 질의응답

프롬프트

최종 plan.md

build 버튼을 누른 후

대화 모드 변경

작업 루프 진행

작업 결과물

결론

Cursor, AI Coding #4 에디터 기본 설정

Cursor, AI Coding #6 프롬프트 작성 요령

0개의 댓글

3.4 `globs`, `alwaysApply`, `file`, `type`의 관계