Cursor Rules Improvement Plan

📋 개요

현재 생성된 .cursor/rules/ 구조를 Cursor 공식 가이드라인에 맞춰 최적화하고, 중복 제거 및 개선점을 제시합니다.

---

🔍 1. 중복 내용 분석

1.1 파일 네이밍 규칙 중복

문제점:

• data/partitioning.mdc: 청크 파일 네이밍 (raw_NNNN.json) 포함
• data/chunking.mdc: 동일한 파일 네이밍 패턴 포함

해결방안:

• partitioning.mdc: 디렉토리 구조 및 파티셔닝 규칙만 유지
• chunking.mdc: 파일 네이밍 패턴 및 청킹 규칙 통합

1.2 Chunk Size 제약 중복

문제점:

• infrastructure/cloudflare-workers.mdc: “Chunk size: 10MB ~ 20MB”
• data/r2-constraints.mdc: “Keep individual files between 10MB and 20MB”

해결방안:

• cloudflare-workers.mdc: Workers 런타임 제약사항 (메모리, ReadableStream)
• r2-constraints.mdc: R2 스토리지 및 파일 크기 제약 (더 구체적)

권장: r2-constraints.mdc에 통합, cloudflare-workers.mdc는 런타임 제약만 유지

1.3 모듈화 규칙 중복

문제점:

• code-quality/modularity.mdc: “Small modules”, “50 lines per function”
• code-quality/code-generation.mdc: “Small modules” 언급

해결방안:

• code-generation.mdc: AI 코드 생성 원칙만 (Boring, Explicit, Testable)
• modularity.mdc: 구체적인 모듈화 규칙 (250 lines, 50 lines function)

---

🗑️ 2. 불필요한 내용 제거

2.1 과도한 설명 제거

현재 문제:

• modularity.mdc: 예시 코드 블록이 너무 길고, 설명이 반복적

Cursor 가이드 원칙:

“파일 내용을 복사하는 대신 참조 파일을 사용하세요”

개선방안:

• 예시 코드 블록 제거 → 실제 프로젝트 파일 참조로 대체
• @src/routes/seeds.ts 같은 참조 추가

2.2 일반적인 명령어 문서화 제거

현재 문제:

• ci-cd/deployment.mdc: “Use GitHub Secrets” 같은 일반적인 지침

Cursor 가이드 원칙:

“에이전트는 이미 일반적인 도구를 알고 있습니다”

개선방안:

• 프로젝트 특화된 규칙만 유지
• 일반적인 GitHub Actions 사용법 제거

2.3 드문 예외 케이스 제거

현재 문제:

• 일부 규칙에 “If unavoidable → explicit documentation” 같은 예외 케이스

Cursor 가이드 원칙:

“드물게 적용되는 예외적인 경우에 대한 지침을 추가하지 마세요”

개선방안:

• 핵심 규칙만 유지, 예외 케이스 제거

---

✨ 3. Cursor 가이드 준수 개선

3.1 참조 파일 추가 (@reference)

현재 상태:

• 대부분의 규칙이 추상적인 설명만 포함

개선방안: 각 규칙에 실제 프로젝트 파일 참조 추가:

## 참조 파일

@src/lib/path/path-builders.ts  # 파티셔닝 구현 예시
@src/lib/d1/task-state.ts        # D1 사용 패턴
@.github/workflows/deploy.yml    # Artifact 전달 패턴

3.2 Globs 패턴 최적화

현재 문제:

• 일부 globs가 너무 넓거나 중복됨
• src/**/*.ts가 여러 규칙에 중복 적용

개선방안:

파일	현재 Globs	개선된 Globs
runtime/worker-code.mdc	src/**/*.ts	src/index.ts, src/routes/**
runtime/error-handling.mdc	src/**/*.ts	src/**/*.ts (유지)
infrastructure/cloudflare-workers.mdc	src/**/*.ts	src/**/*.ts (유지)
data/partitioning.mdc	**/datasets/**	scripts/**, src/lib/path/**

3.3 Always Apply 최소화

현재 상태:

• 5개 규칙이 alwaysApply: true

Cursor 가이드 원칙:

“규칙은 상황에 맞게 선택적으로 적용되어야 합니다”

개선방안:

파일	현재	개선안	이유
core-philosophy.mdc	alwaysApply: true	유지	핵심 철학은 항상 적용
tech-stack.mdc	alwaysApply: true	alwaysApply: false	기술 스택은 관련 파일에서만 필요
forbidden-patterns.mdc	alwaysApply: true	유지	금지 패턴은 항상 체크 필요
code-generation.mdc	alwaysApply: true	alwaysApply: false	AI 코드 생성 시에만 필요
modularity.mdc	alwaysApply: true	alwaysApply: false	코드 작성 시에만 필요

권장: 핵심 철학과 금지 패턴만 항상 적용

---

📝 4. 추가 개선 사항

4.1 구체적인 예시 파일 경로 추가

추가 필요:

# 각 규칙에 참조 파일 섹션 추가

## 참조 구현

- @src/lib/path/path-builders.ts - 파티셔닝 구현
- @src/lib/kv/domain-cache.ts - KV 사용 패턴
- @.github/scripts/lib/wrangler-config.sh - 설정 관리

4.2 규칙 간 의존성 명시

추가 필요:

---
description: "..."
globs: ["..."]
relatedRules: ["core-philosophy", "tech-stack"]
---

참고: Cursor는 공식적으로 relatedRules를 지원하지 않지만, 문서화 목적으로 추가 가능

4.3 실행 가능한 지침으로 개선

현재 문제:

• 일부 규칙이 추상적 (“Be explicit”, “Fail fast”)

개선방안:

• 구체적인 코드 패턴 예시 추가
• “Do this, not that” 형식으로 명확화

예시:

## ✅ 올바른 예시
```typescript
const result = schema.parse(input); // Zod로 검증

❌ 잘못된 예시

const result = input as MyType; // 타입 단언만 사용

---

## 🎯 5. 파일별 구체적 개선 계획

### 5.1 `core-philosophy.mdc`

**현재:** ✅ 적절함
**개선:** 참조 파일 추가

```markdown
## 참조 구현
@wrangler.jsonc - Contract-first 설정 예시

5.2 code-quality/modularity.mdc

현재: 예시 코드 블록이 너무 김 개선:

• 예시 코드 제거
• 실제 파일 참조로 대체: @src/routes/seeds.ts, @src/lib/path/path-builders.ts
• alwaysApply: false로 변경

5.3 data/partitioning.mdc

현재: 청크 파일 네이밍 포함 (중복) 개선:

• 청크 파일 네이밍 제거 (chunking.mdc로 이동)
• 디렉토리 구조 규칙만 유지
• 참조 파일 추가: @src/lib/path/path-builders.ts

5.4 data/chunking.mdc

현재: 파일 네이밍만 포함 개선:

• partitioning.mdc에서 청크 파일 네이밍 통합
• 참조 파일 추가: 실제 청크 파일 예시

5.5 infrastructure/cloudflare-workers.mdc

현재: Chunk size 제약 포함 (r2-constraints와 중복) 개선:

• Chunk size 제약 제거 (r2-constraints.mdc로 이동)
• Workers 런타임 제약만 유지 (메모리, ReadableStream)

5.6 ci-cd/deployment.mdc

현재: 일반적인 GitHub Actions 지침 포함 개선:

• 프로젝트 특화 규칙만 유지
• “Use GitHub Secrets” 같은 일반 지침 제거
• 참조 파일 추가: @.github/workflows/deploy.yml

5.7 runtime/error-handling.mdc

현재: 추상적인 지침 개선:

• 구체적인 에러 처리 패턴 예시 추가
• 참조 파일 추가: 실제 에러 처리 구현 예시

---

📊 6. 우선순위별 개선 작업

Phase 1: 즉시 개선 (High Priority)

1. ✅ 중복 제거

   • partitioning.mdc와 chunking.mdc 파일 네이밍 통합
   • cloudflare-workers.mdc와 r2-constraints.mdc chunk size 통합

2. ✅ Always Apply 최적화

   • tech-stack.mdc: alwaysApply: false로 변경
   • code-generation.mdc: alwaysApply: false로 변경
   • modularity.mdc: alwaysApply: false로 변경

3. ✅ 참조 파일 추가

   • 각 규칙에 실제 프로젝트 파일 참조 추가

Phase 2: 점진적 개선 (Medium Priority)

1. Globs 패턴 최적화
2. 구체적인 예시 코드 패턴 추가
3. 불필요한 설명 제거

Phase 3: 고급 개선 (Low Priority)

1. 규칙 간 의존성 문서화
2. 실행 가능한 지침으로 전환
3. 규칙 검증 자동화

---

📋 7. 개선 후 예상 효과

7.1 성능 개선

• Always Apply 최소화: 불필요한 규칙 로딩 감소 → 토큰 사용량 감소
• Globs 최적화: 관련 파일에서만 규칙 적용 → 컨텍스트 정확도 향상

7.2 유지보수성 향상

• 중복 제거: 규칙 업데이트 시 한 곳만 수정
• 참조 파일: 실제 구현과 규칙의 일관성 유지

7.3 개발자 경험 개선

• 구체적인 예시: 규칙 이해도 향상
• 명확한 지침: 모호함 제거

---

✅ 8. 검증 체크리스트

개선 완료 후 다음을 확인:

• 모든 규칙이 500줄 이하인가?
• 중복된 내용이 제거되었는가?
• 각 규칙에 참조 파일이 추가되었는가?
• Always Apply가 최소화되었는가? (핵심 철학, 금지 패턴만)
• Globs 패턴이 최적화되었는가?
• 구체적인 예시가 포함되었는가?
• 일반적인 도구 사용법이 제거되었는가?

---

📚 참고 자료

• Cursor Rules Documentation
• 현재 프로젝트 구조 분석
• Cursor 공식 가이드라인

---

작성일: 2026-01-28
버전: 1.0