Project Rules

Rules

전체 지시사항의 일부

• 사용자 입력 프롬프트와 설정한 Rules를 전부 결합해서 하나의 Instruction(지시사항)을 만든다.

• Instruction = User Prompt + User Rules + Project Rules

• Agent가 내 의도에 맞게 동작하도록 유도하고, 필요한 컨텍스트를 주입할 수 있게됨

"LLM은 완성 작업 간에 메모리를 유지하지 않는다. 규칙은 프롬프트 수준에서 지속적이고 재사용 가능한 컨텍스트를 제공한다"

• 업무에서 늘 활용하는 방식들을 재사용 가능한 컨텍스트로 정리해 Rules로 관리하자

Rules의 중요성

• 지시사항의 반복적인 Pormpt는 LLM이 캐싱하여 효율적으로 관리할 수 있음 -> 비용 최소화

  • 사용량 기반 요금제는 이 사용량을 최소화 시켜서 비용을 최적화 해주는게 중요

• 즉 Agent가 항상 지켜야하는 규칙을 반복적인 Prompt로 정의하여 사용

Project Rules

프로젝트별로 구성되고, 각 프로젝트 내에서의 동작 방식, 공통 컴포넌트, 아키텍처 구조 등에 대한 가이드 문서를 rules에 정의해 활용함.

• System Prompt + User Rules + User Prompt는 하나의 지시사항으로 묶여 통합 관리됨

• 반면, Project Rules는 지시사항에 포함되지 않고 별도로 관리됨

  • Agent는 이 지시사항을 기반으로 상황에 맞게 선택적으로 호출하거나, 자동으로 주입해 컨텍스트를 생성

  • 커서는 Rules를 Agent가 직접 호출할 수 있고, Rules를 Tool 형태로 관리할 수 있는 기능을 탑재하고 있음

---

규칙을 잘 구조화하는 방법

번호 체계로 카테고리화

• 00x-****.mdc: 프로젝트 전반에 공통적으로 항상 적용되는 규칙

• 100x-****.mdc: rules에서 참조하는 규칙, 라이브러리 명세, 공통 컴포넌트 명세, 사용 방법 예시

• 200x-****.mdc: 보안 관련 규칙, agent가 반드시 지켜야 하며 특정 상황에서 호출되어야 하는 항목

규칙을 작성하는 방법

<-- 규칙을 지정하는 mdc 파일에 하단 설정이 빠지면 활성화 되지 않으니 주의 -->
---
description:
globs:
alwaysApply: false
---

<-- 하단에 rules 작성 --> 

Rules는 한글보다 영어로 작성하는것이 토큰 효율화에 좋음

• LLM은 학습이 많이 된 데이터들에 대해서는 토큰 효율화가 되어짐

• 언어별로 효율화가 차이가 나기 때문에 영어로 작성

Rules Example

// 001-project-rules.mdc
---
description: 
globs: 
alwaysApply: true
---

# 데모 - Cursor Rules

## 개발 프로세스 (중요)

### 1단계: 계획 모드 (기본)
- 모든 기능 요청에 대해 계획 모드로 시작하기
- 요구사항에 대한 명확한 질문하기
- 컴포넌트 구조와 데이터 흐름 논의하기
- 잠재적 문제점과 해결방안 파악하기
- 폴더 구조와 파일 구성 제안하기
- 사용자가 명시적으로 "실행해줘", "act", "구현해줘"라고 말할 때까지 계획 지속하기
- 계획 단계에서는 실제 코드 작성하지 않기
- 아키텍처, 컴포넌트 분해, 설계 결정에 집중하기

### 2단계: 실행 모드 (구현)
- "실행해줘", "act", "구현해줘", "만들어줘", "코딩 시작해줘" 키워드로만 구현 시작
- 계획된 아키텍처를 정확히 따르기
- 적절한 에러 핸들링이 포함된 완성도 높은 코드 작성하기
- 계획된 모든 컴포넌트를 체계적으로 구현하기

## 기술 스택

### 필수 라이브러리
- React 18 + TypeScript (strict 모드)
- Tailwind CSS (스타일링)
- shadcn/ui (UI 컴포넌트)
- TanStack Query (서버 상태 관리)
- Zustand (클라이언트 상태 관리)
- Zod (런타임 타입 검증 및 스키마)

### 프로젝트 구조
```
react-demo/
├── src/
│   ├── pages/
│   │   ├── with-rules/
│   │   │   └── index.tsx
│   │   └── without-rules/
│   │       └── index.tsx
│   ├── data/               # 공통 목 데이터 (양쪽에서 접근)
│   │   └── sampleProduct.ts
│   ├── with-rules/         # FSD 패턴 적용된 구조
│   │   ├── app/            # 애플리케이션 설정
│   │   ├── pages/          # 페이지 레벨 컴포넌트
│   │   ├── widgets/        # 복잡한 UI 블록
│   │   ├── features/       # 비즈니스 기능
│   │   ├── entities/       # 비즈니스 엔티티
│   │   └── shared/         # 공통 유틸리티와 UI
│   ├── without-rules/      # Rules 미적용 구조 (기본 React 패턴)
│   │   ├── components/     # 기본 컴포넌트들 (구조화 안됨)
│   │   ├── hooks/          # 기본 훅들
│   │   ├── types/          # 기본 타입들
│   │   └── utils/          # 기본 유틸들
│   └── App.tsx
```

## 컴포넌트 설계 원칙

### 단일 책임 원칙 (필수)
- 각 컴포넌트는 하나의 명확한 목적만 가져야 함
- 복잡한 컴포넌트는 더 작고 집중된 컴포넌트들로 분해하기
- 예시:
  - ❌ ProductSearchPage (검색, 필터, 표시, 페이지네이션 모두 처리)
  - ✅ SearchInput, FilterPanel, ProductGrid, Pagination (각각 분리된 컴포넌트)

### FSD 패턴 레이어 구조
1. **App 레이어** (`app/`)
   - 애플리케이션 초기화
   - 전역 프로바이더와 라우팅
   - 설정 파일들

2. **Pages 레이어** (`pages/`)
   - 라우트 레벨 컴포넌트들
   - 페이지 구성과 조합
   - 각 페이지의 메인 컨테이너

3. **Widgets 레이어** (`widgets/`)
   - 복잡한 UI 블록들
   - 여러 기능을 조합한 복합 컴포넌트들
   - 독립적으로 동작하는 UI 단위

4. **Features 레이어** (`features/`)
   - 비즈니스 로직과 사용자 상호작용
   - 특정 기능별 컴포넌트들
   - 상태 관리와 비즈니스 로직 포함

5. **Entities 레이어** (`entities/`)
   - 비즈니스 엔티티와 관련 로직
   - 데이터 모델과 스키마
   - 엔티티별 API 호출 로직

6. **Shared 레이어** (`shared/`)
   - 재사용 가능한 유틸리티, UI 킷
   - 공통 인프라스트럭처
   - shadcn/ui 컴포넌트들과 공통 훅들

### 컴포넌트 구조 템플릿
```typescript
// 1. 외부 라이브러리, 내부 라이브러리, 타입 순으로 import
// 2. 타입 정의 (Props 인터페이스)
// 3. 컴포넌트 구현
// 4. Default export

interface ComponentNameProps {
  // 엄격한 타이핑 필수
}

const ComponentName: React.FC<ComponentNameProps> = ({ ...props }) => {
  // 컴포넌트 로직
  return (
    // Tailwind 클래스와 함께 JSX
  );
};

export default ComponentName;
```

## TypeScript 규칙

### 엄격한 타입 안전성
- tsconfig.json에서 strict 모드 활성화
- `any` 타입 사용 금지
- 알 수 없는 데이터에는 `object`보다 `unknown` 사용
- 느슨한 타이핑보다 타입 유니온 선호
- 재사용 가능한 컴포넌트에는 제네릭 타입 사용

### Zod 통합
- 모든 외부 데이터에 대해 Zod 스키마 생성
- TypeScript 타입 도출을 위해 `z.infer<>` 사용
- API 응답과 폼 입력 검증
- 스키마들을 `schemas/` 디렉토리에 배치

### 타입 구성 (entities 레이어에 배치)
```typescript
// entities/product/model/types.ts
import { z } from 'zod';

export const ProductSchema = z.object({
  id: z.string(),
  name: z.string(),
  price: z.number().positive(),
  category: z.string(),
  inStock: z.boolean(),
});

export type Product = z.infer<typeof ProductSchema>;

// API 응답 타입들
export const ProductListResponseSchema = z.object({
  products: z.array(ProductSchema),
  total: z.number(),
  page: z.number(),
});

export type ProductListResponse = z.infer<typeof ProductListResponseSchema>;
```

## 상태 관리

### Zustand 스토어 구조 (features 레이어에 배치)
- 도메인별로 별도 스토어 생성
- Zustand와 TypeScript 함께 사용
- `features/{feature-name}/model/` 디렉토리에 스토어 구현
- 큰 스토어에는 slice 패턴 따르기

```typescript
// features/product-search/model/productStore.ts
interface ProductStore {
  // 상태
  searchTerm: string;
  filters: ProductFilters;
  
  // 액션들
  setSearchTerm: (term: string) => void;
  updateFilters: (filters: Partial<ProductFilters>) => void;
  resetFilters: () => void;
}
```

### TanStack Query 통합 (entities 레이어에 배치)
- `entities/{entity-name}/api/`에 쿼리 훅 생성
- 적절한 에러 핸들링과 로딩 상태 사용
- 적절한 곳에 낙관적 업데이트 구현
- 적절한 키로 캐시 관리

## 스타일링 규칙

### Tailwind CSS 가이드라인
- Tailwind 유틸리티 클래스만 사용
- 절대 필요한 경우가 아니면 커스텀 CSS 사용 금지
- 모바일 우선 반응형 디자인 따르기
- 일관된 spacing 스케일 사용 (4, 8, 12, 16, 24, 32, 48, 64)

### shadcn/ui 통합
- shadcn/ui 컴포넌트를 기본으로 사용
- Tailwind 클래스로 커스터마이징
- 디자인 시스템 일관성 유지
- 컴포넌트 props에서 variant 조합 생성

### 반응형 디자인
- 모바일 우선 접근법 (모바일용 기본 스타일)
- Tailwind 반응형 접두사 사용 (sm:, md:, lg:, xl:)
- 여러 화면 크기에서 테스트
- 터치 친화적 인터페이스 보장

## 파일 명명과 구성

### 명명 규칙
- **컴포넌트**: PascalCase (ProductCard.tsx)
- **훅**: 'use' 접두사와 camelCase (useProductQuery.ts)
- **스토어**: 'Store' 접미사와 camelCase (productStore.ts)
- **타입**: PascalCase (ProductFilters)
- **상수**: SCREAMING_SNAKE_CASE
- **디렉토리**: kebab-case

### Import 구성 (FSD 패턴 기준)
```typescript
// 1. 외부 라이브러리들
import React from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Shared 레이어 (공통 유틸리티)
import { Button } from '@/shared/ui/button';

// 3. Entities 레이어 (비즈니스 엔티티)
import { useProductStore } from '@/entities/product/model/productStore';
import type { Product } from '@/entities/product/model/types';

// 4. Features 레이어 (비즈니스 기능)
import { ProductFilters } from '@/features/product-search/ui/ProductFilters';

// 5. 같은 레이어 내 컴포넌트들
import ProductCard from './ProductCard';
```

## 성능 최적화

### React 최적화
- 비용이 많이 드는 순수 컴포넌트에 React.memo 사용
- 무거운 계산에 useMemo 구현
- 안정적인 참조를 위해 useCallback 사용
- 적절한 의존성 배열로 재렌더링 최적화

## 구현 가이드라인

### 개발 워크플로우
1. **계획 단계**: 아키텍처 논의하고 요구사항 분해하기
2. **스키마 정의**: Zod 스키마와 TypeScript 타입 정의하기
3. **스토어 설정**: 필요한 Zustand 스토어들 생성하기
4. **컴포넌트 구조**: 컴포넌트 계층 구조 만들기
5. **UI 구현**: shadcn/ui와 Tailwind로 구현하기
6. **통합**: 컴포넌트들을 스토어와 쿼리와 연결하기

## 단계 전환 키워드
- **계획 모드 유지**: 이런 키워드들 없이 계속 논의
- **구현 모드로 전환**: "실행해줘", "act", "구현해줘", "만들어줘", "코딩 시작해줘", "해보자"

기억하기: 구현하기 전에 항상 계획 모드로 시작해서 접근법을 철저히 논의하기!

---
description: 
globs: 
alwaysApply: true
---
# 프론트엔드 개발 워크플로우 (Enhanced)

## 기본 원칙
- Phase 1이 명확하지 않으면 사용자에게 되물어서 명확한 계획을 완성
- **구현 전 사용자 확인**: Phase 1 완료 후 반드시 사용자에게 구현 계획을 확인받고 승인 후 Phase 2 진행
- Planning은 여러번 반복 가능하며, '구현' 또는 'act' 명령 시 구현 단계로 진입
- Linear Task 완료 시 내용을 정리하여 해당 Task에 Comment 작성
- 각 단계별 검증을 통해 다음 단계로 진행하며, 필요시 이전 단계로 피드백
- 반드시 위 원칙을 준수하여 개발 진행

---

## 📋 Phase 1: 상황 인지 & 계획 수립 (Enhanced Top-down)

### 1. 요구사항 분석
- **작업 유형 분류**: Bugfix / Feature / Enhancement / Refactor / UI/UX
- **비즈니스 로직 이해**: 도메인 지식 및 사용자 시나리오 파악
- **우선순위 설정**: 핵심 기능 vs 부가 기능, 필수 vs 선택사항 구분
- **제약사항 확인**: 기술적/비기능적 요구사항, 일정 및 리소스 제약
- **참고 자료 수집**: 기존 유사 기능 및 재사용 가능한 컴포넌트 확인

### 2. 영향도 세부 분석 (Enhanced)
- **관련 컴포넌트 식별**:
  - 직접 영향: 수정 대상 컴포넌트 및 직접 연결된 컴포넌트
  - 간접 영향: 상태 공유, props 전달, context 사용 컴포넌트
  - 사이드 이펙트 가능 영역: 성능, 접근성, 보안에 영향받는 컴포넌트
- **이벤트 전파 경로 분석**:
  - 사용자 액션 → 이벤트 핸들러 → 상태 변경 → UI 업데이트 플로우
  - Electron IPC 이벤트 → 메인 프로세스 → 렌더러 프로세스 통신
  - 라우트 변경, 브라우저 이벤트 등 시스템 이벤트 영향
- **상태 전파 경로 분석**: 
  - Zustand 스토어 → 구독 컴포넌트 → 하위 컴포넌트 체인 확인
  - 전역 상태 vs 로컬 상태 영향 범위 파악
  - 상태 변경 시 리렌더링 범위 예측

### 3. 아키텍처 매핑 & 설계
- **FSD 계층 매핑**: app → pages → widgets → features → entities → shared
- **의존성 검증**: 상위 계층 → 하위 계층 방향 import 규칙 준수 확인
- **컴포넌트 재사용성**: shared 계층 우선 활용, 중복 방지 전략
- **책임 분리**: 각 계층별 역할과 책임 명확화
- **확장성 고려**: 향후 기능 추가 시 구조적 확장 가능성 검토

### 4. 상태 관리 & 인터페이스 설계
- **상태 범위 결정**: Local State vs Global State(Zustand) 구분 기준
- **스토어 구조 설계**: 전역 스토어 vs 엔티티별 스토어 분리 전략
- **데이터 흐름 정의**: User Action → Event Handler → State Update → UI Update
- **타입 정의**: TypeScript Interface, API Schema, 이벤트 타입 설계
- **에러/로딩 상태**: 비동기 작업에 대한 상태 관리 및 사용자 피드백 전략

### 5. 필요 소스코드 파악
- **신규 생성 파일**: 
  - 컴포넌트: 어떤 계층에 어떤 컴포넌트가 필요한지
  - 스토어: 새로운 상태 관리가 필요한 영역
  - 타입: 새로운 인터페이스 및 타입 정의
  - 유틸리티: 공통 함수 및 헬퍼 함수
- **수정 대상 파일**: 
  - 기존 컴포넌트 중 변경이 필요한 부분과 변경 범위
  - 라우팅, 스토어, 타입 정의 수정사항
- **의존성 변경**: package.json, import 구조, 설정 파일 변경사항

### 6. 사용자 확인 단계 ⚠️
- **구현 계획 요약**: Phase 1에서 수립한 모든 계획을 명확히 요약
- **사용자 승인 요청**: "위 계획으로 구현을 진행해도 될까요?" 형태로 명시적 확인
- **승인 후 진행**: 사용자 승인 후에만 Phase 2로 진행

---

## 🔧 Phase 2: 구현 (Enhanced Bottom-up)

### 1. UI 구현 (Bottom-up 시작)
- **Atomic UI**: shared/ui의 기본 UI 요소 (Button, Input, Modal 등)
  - 시각적 디자인: 레이아웃, 색상, 타이포그래피, 애니메이션
  - 접근성 고려: ARIA 속성, 키보드 네비게이션, 포커스 관리
  - 반응형 디자인: 다양한 화면 크기 대응
  - 스타일링: Tailwind CSS 기반 스타일링
- **Entity UI**: 도메인 특화 UI 요소 (Agent Card, Task Item 등)
  - 비즈니스 도메인에 특화된 시각적 표현
  - 데이터 표시 형식 및 레이아웃 구조
  - 도메인별 인터랙션 패턴
- **Feature UI**: 기능별 UI 조합 (Agent Builder, Task Manager 등)
  - 복합 UI 블록의 시각적 구성
  - 사용자 워크플로우에 맞는 UI 배치
  - 기능별 특화된 인터페이스 디자인

### 2. 이벤트 구현 (UI에 생명력 부여)
- **UI 이벤트 핸들러**: 각 UI 요소별 인터랙션 로직
  - 클릭, 호버, 포커스, 블러 등 기본 이벤트
  - 드래그 앤 드롭, 제스처, 키보드 단축키
  - 폼 검증, 제출, 리셋 로직
  - 실시간 검색, 자동완성, 필터링
- **시스템 이벤트**: UI와 시스템 간 연결점
  - Electron IPC 통신 (파일 시스템, 네이티브 API)
  - 라우트 변경, 브라우저 이벤트 (resize, beforeunload)
  - 웹소켓, SSE 등 실시간 통신 이벤트
- **이벤트 최적화**: 성능과 사용자 경험 고려
  - 디바운싱, 스로틀링 적용
  - 이벤트 위임 및 메모리 누수 방지
  - 에러 바운더리 및 예외 처리

### 3. 상태 연동 & 컴포넌트 완성 (UI + Event + State)
- **스토어 연결**: UI와 상태 관리 시스템 연동
  - Zustand 스토어와 컴포넌트 연결
  - 상태 구독 및 업데이트 로직
  - 로컬 상태 vs 전역 상태 적절한 활용
- **데이터 바인딩**: UI 요소와 데이터 동기화
  - Props 전달 및 상태 끌어올리기
  - 양방향 데이터 바인딩 (폼 입력 등)
  - 조건부 렌더링 및 리스트 렌더링
- **상태 동기화**: 컴포넌트 간 일관성 보장
  - 여러 컴포넌트 간 상태 일관성 보장
  - 낙관적 업데이트 vs 비관적 업데이트 전략
  - 상태 영속화 (localStorage, sessionStorage)
- **컴포넌트 완성**: UI + Event + State 통합
  - 타입 안전성: Props 인터페이스 정의, 제네릭 활용
  - 에러 바운더리: 컴포넌트 레벨 에러 처리
  - 성능 최적화: React.memo, useMemo, useCallback 적용

### 4. Widget & Page 조합
- **Widget 컴포넌트**: 복합 UI 블록, 페이지 섹션 단위 컴포넌트
- **Page 컴포넌트**: 라우트별 페이지 컴포넌트 및 레이아웃
- **라우팅 연결**: React Router 설정, 네비게이션 가드, 동적 라우팅
- **레이아웃 시스템**: 헤더, 사이드바, 메인 콘텐츠 영역 구성
- **로딩 상태**: 페이지 레벨 로딩, 스켈레톤 UI, 프로그레스 바

### 5. 사이드 이펙트 파악 & 대응
- **성능 영향 분석**:
  - 리렌더링 최적화: React.memo, useMemo, useCallback 적용
- **상태 일관성 검증**:
  - 동시성 문제: Race condition, 상태 충돌 해결
  - 데이터 무결성: 낙관적 업데이트 실패 시 롤백 전략
  - 캐시 무효화: 상태 변경 시 관련 캐시 업데이트

### 6. 리팩토링 & 최적화
- **코드 품질 개선**:
  - 중복 코드 제거: 공통 로직 추출, 커스텀 훅 활용
  - 복잡도 감소: 함수 분리, 조건부 렌더링 최적화
  - 가독성 향상: 명명 규칙, 주석, 문서화
- **성능 최적화**:
  - 렌더링 최적화: 가상화, 지연 로딩, 이미지 최적화
  - 네트워크 최적화: 요청 배칭, 캐싱 전략, 압축
  - 메모리 최적화: 객체 풀링, 가비지 컬렉션 고려
- **타입 안전성 강화**:
  - any 타입 제거: 구체적인 타입 정의, 타입 가드 활용
  - 제네릭 활용: 재사용 가능한 타입 정의
  - 런타임 검증: Zod, Yup 등을 활용한 스키마 검증

---

## 💡 핵심 체크포인트 (Enhanced)

### Phase 1 완료 기준
- [ ] 현재 코드베이스 상황이 명확히 파악됨
- [ ] 모든 요구사항이 구체적으로 정의됨
- [ ] 상태/이벤트 전파 경로가 설계됨
- [ ] 영향받는 모든 컴포넌트가 식별됨
- [ ] FSD 아키텍처 계층 구조가 설계됨
- [ ] 필요한 모든 소스코드가 파악됨
- [ ] 예상 사이드 이펙트가 분석됨
- [ ] **사용자 승인 완료** ⚠️

### Phase 2 완료 기준
- [ ] 모든 컴포넌트가 FSD 규칙을 준수함
- [ ] 타입 안전성이 보장됨 (any 타입 0개)
- [ ] 상태 관리가 올바르게 동작함
- [ ] 모든 이벤트가 정상 처리됨
- [ ] 사이드 이펙트가 적절히 처리됨
- [ ] 성능 최적화가 적용됨
- [ ] 접근성 기준을 충족함
- [ ] 보안 요구사항을 만족함
- [ ] 테스트 코드가 작성됨

### 단계별 검증 포인트
- **Phase 1 완료 시**: 사용자 승인 후 Phase 2 진행
- **Phase 2 완료 시**: 체크리스트 확인 후 Phase 3 진행
- **문제 발견 시**: 이전 단계로 피드백하여 수정

---

## 🔄 품질 관리 & 지속적 개선

### 코드 리뷰 필수 항목
- [ ] FSD 아키텍처 준수 여부
- [ ] TypeScript 타입 안전성
- [ ] 성능 최적화 적용 상태
- [ ] 에러 처리 완성도

### 리팩토링 트리거
- 코드 중복 3회 이상 발생 시
- 컴포넌트 복잡도 임계치 초과 시
- 성능 이슈 발생 시 (렌더링 > 16ms)
- 유지보수성 저하 시 (수정 시간 > 예상 시간 2배)
- 타입 에러 빈발 시

### 지속적 개선
- **회고**: 각 기능 완료 후 워크플로우 개선점 도출
- **메트릭 수집**: 개발 시간, 버그 발생률, 성능 지표 추적
- **베스트 프랙티스 업데이트**: 새로운 패턴 발견 시 규칙 업데이트
- **도구 개선**: 개발 효율성 향상을 위한 도구 및 자동화 개선

---

## 📚 관련 Rules
- [1001-fsd-architecture](mdc:.cursor/rules/1001-fsd-architecture.mdc): FSD 아키텍처 상세 가이드
- [1002-tech-stack](mdc:.cursor/rules/1002-tech-stack.mdc): 기술 스택 및 개발 패턴
- [1003-implementation-patterns](mdc:.cursor/rules/1003-implementation-patterns.mdc): 구현 패턴 및 예시

프롬프트로 생성

• /Generate Cursor Rules 사용

  • ex: /Generate Cursor Rules 공통 컴포넌트 명세와 사용하는 방식을 100x-component-rules.mdc 로 생성해줘

• cursor-directory 에서 내 프로젝트 상황에 맞는 rules를 가져와 사용