02 - 커서 규칙: 프로젝트에 대한 AI 구성
각 개발자는 고유한 규칙, 아키텍처 패턴 및 품질 표준을 가지고 있습니다. 당신이 함께 일할 때 인간 동료인 경우 이러한 규칙은 코드 검토, 쌍 프로그래밍 및 문서화를 통해 전달됩니다. 하지만 AI 에이전트에게 동일한 기대치를 어떻게 전달할 수 있습니까? 커서의 반응과 규칙 시스템: AI에게 방법을 지시할 수 있는 강력하고 유연한 메커니즘 프로젝트 코드를 생성, 수정 및 추론해야 합니다.
이 기사에서는 커서 규칙 시스템의 모든 측면을 살펴보겠습니다. Angular, React, Python, API 백엔드에 대한 실제 예제를 통해 고급 구성 전략까지 그리고 훨씬 더. 결국 당신은 Cursor AI를 공동 작업자로 전환하는 데 필요한 모든 도구를 갖게 될 것입니다. 팀의 규칙을 항상 알고 있었던 것처럼 존중하십시오.
이 기사에서 배울 내용
- 규칙 시스템의 진화:
.cursorrules디렉토리로.cursor/rules/ - 네 가지 규칙 유형: 항상, 자동 연결, 에이전트 요청 및 수동
- 사용자 규칙과 프로젝트 규칙의 차이점 및 각 유형을 사용하는 경우
- 머리말, 글롭, 설명을 사용하여 효과적인 규칙을 작성하는 방법
- Angular, React, Python, FastAPI 및 REST API에 대한 전체 예제
- 고급 전략: 조건부 규칙, 규칙 상속, 자동 생성
- 팀 워크플로: Git을 통한 공유, 온보딩 및 공유 규칙
- CLAUDE.md 및 기타 AI 교육 시스템과의 비교
커서 IDE 및 AI 네이티브 개발 시리즈 개요
| # | Articolo | 집중하다 |
|---|---|---|
| 1 | 완전한 커서 IDE 가이드 | 전체 개요 |
| 2 | 현재 위치 - 커서 규칙 | 맞춤형 AI 설정 |
| 3 | 에이전트 모드 | 고급 자동화 |
| 4 | 계획 모드 | 보조 계획 |
| 5 | 후크와 MCP | 확장성 및 통합 |
| 6 | 전문적인 워크플로우 | 최고의 생산 방식 |
커서 규칙 시스템의 진화
커서의 규칙 시스템은 처음 도입된 이후 상당한 발전을 거쳤습니다. 이 역사를 이해하는 것은 현재 시스템이 왜 특정 방식으로 구성되어 있는지 이해하는 데 필수적입니다. 서로 다른 구성 세대 간의 혼동을 방지합니다.
1세대: .cursorrules 파일
첫 번째 구현에서 Cursor는 단일 파일을 지원했습니다. .cursorrules 프로젝트 루트에서.
이 파일에는 각 AI 상호 작용의 컨텍스트에 삽입된 자유 텍스트 지침이 포함되어 있습니다.
간단하고 간단했습니다. 규칙을 파일에 작성하면 AI가 이를 따릅니다.
Sei uno sviluppatore senior specializzato in Angular e TypeScript.
Regole di codice:
- Usa sempre standalone components
- Preferisci signals rispetto a BehaviorSubject
- Usa OnPush change detection in tutti i componenti
- Scrivi sempre i test unitari per i servizi
- Segui le convenzioni di naming Angular (kebab-case per i file)
Stile di risposta:
- Rispondi in italiano
- Spiega il ragionamento dietro ogni scelta
- Includi gestione degli errori in ogni esempio
이 접근 방식에는 다음과 같은 분명한 한계가 있었습니다. 모든 규칙은 단일 모놀리식 파일로 끝났습니다..
Angular 프런트엔드, Python 백엔드, Docker 인프라 및 CI/CD 파이프라인이 포함된 복잡한 프로젝트에서
파일 .cursorrules 그것은 빠르게 거대해지고 관리하기 어려워졌습니다. 또한 모든 규칙은
현재 상황과 관련이 없는 경우에도 항상 AI로 전송되었습니다.
2세대: .cursor/rules/를 사용한 프로젝트 규칙
이러한 제한 사항을 해결하기 위해 Cursor는 다음을 도입했습니다. 프로젝트 규칙 기반으로
디렉토리 .cursor/rules/. 이 새로운 접근 방식을 사용하면 규칙을 별도의 파일로 구성할 수 있습니다.
구조화된 메타데이터와 파일 패턴에 따른 조건부 활성화를 사용합니다.
디렉토리 .cursor/rules/ git 저장소에 커밋되도록 하여 모든 사람이
팀원은 자동으로 동일한 AI 지침을 공유합니다. 디렉터리의 각 파일은 파일입니다.
.mdc (Markdown with Context) YAML 머리말과 Markdown의 문의 본문을 포함합니다.
왜 .mdc가 아닌 .mdc인가요?
형식 .mdc (컨텍스트가 있는 마크다운)은 다음을 추가하는 독점 커서 확장입니다.
표준 Markdown 구조의 서문입니다. 머리말은 메타데이터를 설명으로 정의합니다.
규칙, 자동 활성화를 위한 glob 패턴 및 플래그 alwaysApply. 커서가 해석함
이 메타데이터를 사용하여 각 규칙을 적용할 시기와 방법을 결정합니다.
네 가지 유형의 규칙
최신 커서 시스템은 네 가지 규칙 활성화 모드를 정의합니다. 특정 사용 사례. 지침의 관련성 균형을 맞추려면 올바른 유형을 선택하는 것이 중요합니다. AI 컨텍스트 소비로.
1. 항상 규칙
유형 규칙 언제나 관계없이 AI와의 모든 상호 작용에 포함됩니다. 작업 중인 파일이나 요청한 내용에서. 이는 보편적인 협약에 이상적입니다. 항상 존중받아야 할 프로젝트.
---
description: Convenzioni globali del progetto
alwaysApply: true
---
# Convenzioni Progetto
## Linguaggio
- Rispondi sempre in italiano
- Usa commenti in inglese nel codice
- Variabili e funzioni in inglese (camelCase)
## Architettura
- Pattern: Feature-based folder structure
- State management: Signals (Angular) / Zustand (React)
- Testing: Ogni modulo deve avere copertura > 80%
## Git
- Commit messages in conventional commits format
- Prefissi: feat, fix, refactor, docs, test, chore
- Branch naming: feature/xxx, bugfix/xxx, hotfix/xxx
컨텍스트 소비에 대한 주의
규칙은 항상 와요 언제나 AI로 전송되어 각각의 컨텍스트 토큰을 소비합니다. 상호 작용. 이 유형은 진정한 보편적인 규칙에만 사용하세요. 규칙이 특정 항목에만 적용되는 경우 파일 또는 상황의 경우 컨텍스트 사용을 최적화하기 위해 자동 연결 또는 에이전트 요청을 선호합니다.
2. 자동 첨부 규칙
규칙 자동 부착 일치하는 파일을 작업할 때 자동으로 활성화됩니다. 특정 글로브 패턴에. 언어, 프레임워크 또는 파일 유형과 관련된 규칙에 적합합니다.
---
description: Regole per componenti Angular
globs: ["**/*.component.ts", "**/*.component.html"]
alwaysApply: false
---
# Componenti Angular
## Struttura
- Usa SEMPRE standalone components (no NgModule)
- Implementa OnPush change detection strategy
- Preferisci signals() e computed() per lo stato reattivo
- Usa input() e output() signal-based (non @Input/@Output decorators)
## Template
- Usa la nuova control flow syntax: @if, @for, @switch
- Preferisci @defer per lazy loading di sezioni pesanti
- Non usare mai ngIf, ngFor, ngSwitch (legacy)
## Naming
- File: kebab-case (es. user-profile.component.ts)
- Selettore: prefisso app- (es. app-user-profile)
- Classe: PascalCase (es. UserProfileComponent)
분야 globs 표준 글로브 패턴을 지원합니다. 다음과 같은 간단한 와일드카드를 사용할 수 있습니다. *.ts
또는 다음과 같은 복잡한 패턴 {**/*.service.ts,**/*.guard.ts}. 파일을 열 때
패턴과 일치하는 규칙은 AI 컨텍스트에 자동으로 포함됩니다.
3. 에이전트가 요청한 규칙
규칙 에이전트가 요청함 설명을 통해 AI에 표시되지만 에이전트가 현재 작업과 관련이 있다고 결정할 때만 컨텍스트에 포함됩니다. 이 남자와 항상 필요하지는 않지만 필요할 때 AI가 참고할 수 있어야 하는 전문 규칙에 이상적입니다.
---
description: Regole per la creazione e gestione delle migrazioni database con Prisma
alwaysApply: false
---
# Migrazioni Database
## Creazione Migrazioni
- Usa sempre `prisma migrate dev --name descrizione-cambiamento`
- Nomi migrazioni: snake_case, descrittivi (es. add_user_roles_table)
- Non modificare MAI migrazioni già applicate in produzione
## Schema Prisma
- Ogni modello deve avere: id, createdAt, updatedAt
- Usa @@map per nomi tabella in snake_case
- Relazioni: definisci sempre entrambi i lati
- Indici: aggiungi @@index per campi usati in WHERE e JOIN
## Rollback
- Testa sempre il rollback prima di applicare in staging
- Documenta i passaggi manuali necessari nel file di migrazione
이 예에서는 규칙에 다음이 없습니다. globs 그리고 그것은 alwaysApply: false. AI는 오직
설명 "Prisma를 사용한 데이터베이스 마이그레이션 생성 및 관리 규칙"이며 독립적으로 결정됩니다.
작업에 데이터베이스 작업이 포함될 때 규칙의 전체 내용을 포함할지 여부입니다. 이 접근법
특히 효율적입니다. AI는 맥락을 낭비하지 않고 전문 지식 카탈로그에 접근할 수 있습니다.
필요하지 않을 때.
4. 수동 규칙
규칙 수동 자동으로 포함되지 않습니다. 명시적으로 언급되어야 합니다.
개발자가 참조를 사용하여 @ruleName 프롬프트에서. 템플릿에 유용합니다.
특정 상황에서만 사용하려는 스니펫 또는 지침.
---
description: Template per la creazione di una nuova feature Angular completa
alwaysApply: false
---
# Template Nuova Feature
Quando creo una nuova feature Angular, genera i seguenti file:
## Struttura Directory
```
src/app/features/[feature-name]/
[feature-name].component.ts # Componente principale
[feature-name].component.html # Template
[feature-name].component.css # Stili
[feature-name].component.spec.ts # Test componente
[feature-name].service.ts # Servizio dati
[feature-name].service.spec.ts # Test servizio
[feature-name].routes.ts # Routing lazy-loaded
[feature-name].model.ts # Interfacce e tipi
```
## Checklist
- [ ] Componente standalone con OnPush
- [ ] Servizio con HttpClient e gestione errori
- [ ] Route lazy-loaded registrata in app.routes.ts
- [ ] Test unitari per componente e servizio
- [ ] Interfacce per i modelli dati
이 규칙을 사용하기 위해 개발자는 다음과 같이 작성합니다. "@new-feature-template을 따라 사용자 프로필에 대한 새 기능을 생성하세요.". AI는 규칙의 내용을 컨텍스트에 포함시키고 템플릿에 따라 코드를 생성합니다.
규칙 유형 요약
| 유형 | 활성화 | 사용 사례 | 소비 상황 |
|---|---|---|---|
| 언제나 | 항상 포함됨 | 유니버설 디자인 규칙 | 높음(항상 활성) |
| 자동 부착 | 파일의 글로브 패턴 | 언어/프레임워크별 규칙 | 중간(관련 파일만) |
| 에이전트가 요청함 | 설명에 따라 AI가 결정 | 필요에 따른 전문 지식 | 낮음(필요한 경우에만) |
| 수동 | @name을 사용한 명시적 호출 | 템플릿, 스니펫, 드문 지침 | 최소(요청 시에만) |
사용자 규칙과 프로젝트 규칙
커서는 두 가지 구성 수준을 구별합니다. 사용자 규칙 모든 사람에게 적용되는 것 당신의 프로젝트와 프로젝트 규칙 이는 단일 저장소에만 해당됩니다. 효과적인 설정을 위해서는 둘 중 하나를 언제 사용해야 하는지 이해하는 것이 중요합니다.
사용자 규칙: 전역 기본 설정
사용자 규칙은 다음에서 구성됩니다. Cursor Settings > General > Rules for AI. 이 규칙
이는 귀하가 작업하는 프로젝트에 관계없이 일정하게 유지되는 개인 선호도를 정의합니다.
저장소에 있는 파일이 아니며 로컬 커서 구성에 있습니다.
## Preferenze Generali
- Rispondi sempre in italiano per le spiegazioni
- Scrivi commenti nel codice in inglese
- Quando generi codice, aggiungi sempre la gestione degli errori
- Preferisci l'immutabilita: crea nuovi oggetti invece di mutare quelli esistenti
- Usa TypeScript strict mode in tutti i progetti TypeScript
- Segui i principi SOLID e clean code
- Quando suggerisci soluzioni, spiega il ragionamento
## Formato Preferito
- Funzioni brevi (<50 righe)
- File focalizzati (<400 righe)
- Nesting massimo: 4 livelli
- Naming esplicito e descrittivo
프로젝트 규칙: 저장소 규칙
프로젝트 규칙은 디렉토리에 있습니다. .cursor/rules/ 프로젝트에 참여하고 헌신하고 있습니다.
git 저장소에 있습니다. 이는 저장소를 복제하는 모든 팀 구성원이 자동으로
동일한 AI 지침을 사용하여 코드 생성의 일관성을 보장합니다.
사용자 규칙과 프로젝트 규칙: 언제 무엇을 사용할지
| 나는 기다린다 | 사용자 규칙 | 프로젝트 규칙 |
|---|---|---|
| 빗자루 | 모든 프로젝트 | 단일 저장소 |
| 위치 | 커서 설정 | .cursor/rules/*.mdc |
| 공유 | 로컬 전용 | Git(팀)을 통해 |
| 상위 | 기본(프로젝트에 의해 재정의됨) | 높음(컨텍스트별) |
| Esempio | 언어, 응답 스타일, 일반 원칙 | 프레임워크, 아키텍처, 특정 패턴 |
La 상위 직관적으로 작동합니다. 프로젝트 규칙이 사용자 규칙보다 우선합니다. 갈등이 있을 때. 사용자 규칙에 "클래스 사용"이 명시되어 있지만 프로젝트 규칙에 "함수 사용"이 명시되어 있는 경우 AI는 프로젝트 규칙을 따릅니다. 이를 통해 각 프로젝트는 별도의 규칙 없이도 고유한 규칙을 가질 수 있습니다. 전역 기본 설정을 변경해야 합니다.
효과적인 규칙의 분석
AI가 올바르게 따를 수 있는 규칙을 작성하려면 구조와 명확성에 주의를 기울여야 합니다. 지침의 단순성. 잘 작성된 규칙은 코드를 생성하는 AI의 차이점입니다. 귀하의 표준에 완벽하게 맞는 코드를 생성하는 일반 및 AI입니다.
.mdc 파일의 구조
각 파일 .mdc 두 부분으로 구성됩니다. YAML 서문 다음으로 구분됨
--- 그리고 마크다운의 본문 실제 지침과 함께.
---
description: [Descrizione concisa per l'AI - usata per Agent Requested]
globs: ["pattern1", "pattern2"]
alwaysApply: true|false
---
# Titolo della Rule
## Sezione 1: Istruzioni Generali
- Istruzione chiara e specifica
- Esempio concreto se necessario
## Sezione 2: Pattern da Seguire
- Pattern preferito con esempio
- Anti-pattern da evitare con spiegazione
## Sezione 3: Eccezioni
- Quando NON applicare queste regole
- Casi limite e come gestirli
효과적인 규칙 작성을 위한 모범 사례
실제 프로젝트에서 수백 개의 규칙을 구성한 후 다섯 가지 기본 원칙을 확인했습니다. 규칙의 효율성을 결정하는 요소입니다.
1. 일반적이지 않고 구체적이어야 합니다. "깨끗한 코드 작성"이라는 규칙은 쓸모가 없습니다. "각 함수에는 최대 4개의 매개변수가 있어야 하며 각각 명시적인 유형과 JSDoc이 있어야 합니다"라는 규칙 AI로 조작 가능.
2. 말로만 하지 말고 보여주세요. 항상 다음과 같은 구체적인 코드 예를 하나 이상 포함하세요. 규칙을 존중하세요. AI는 추상적인 설명보다 예를 통해 더 잘 학습합니다.
3. 안티 패턴도 정의합니다. 하지 말아야 할 일을 명시적으로 명시하십시오. 규칙이라면 "신호를 사용하세요"라고 말하지만 "BehaviorSubject를 사용하지 마세요"라고 말하지 않으면 AI는 두 가지 접근 방식을 혼합할 수 있습니다.
4. 규칙, 주제. 모든 것을 포괄하는 모놀리식 파일을 만들지 마십시오. 규칙을 분할하세요 영역별: 테스트용 규칙 하나, CSS용 규칙 하나, 아키텍처용 규칙 하나. 이렇게 하면 유지 관리가 더 쉬워집니다. 글로브를 통한 선택적 활성화가 가능합니다.
5. AI를 염두에 두고 설명을 작성해주세요. 분야 description 머리말에
에이전트 요청 규칙을 포함할지 여부를 결정하기 위해 AI가 읽는 내용입니다. 간결해야 하지만
규칙이 관련되는 시기를 AI가 이해할 수 있도록 충분히 유익합니다.
Angular 규칙: 전체 예
Angular는 정확한 규칙과 빠르게 진화하는 생태계를 갖춘 프레임워크입니다. 통로와 함께 독립형 구성 요소, 신호 및 새로운 제어 흐름 구문에 대해서는 AI가 코드를 생성하는 것이 필수적입니다. 이는 현대적인 모범 사례를 따릅니다. 다음은 Angular 프로젝트에 대한 전체 규칙 세트입니다.
---
description: Architettura e pattern generali del progetto Angular
alwaysApply: true
---
# Architettura Angular
## Versione e Stack
- Angular 19+ con standalone components
- TypeScript 5.7+ in strict mode
- Stato: Angular Signals (signal, computed, effect)
- HTTP: HttpClient con interceptor funzionali
- Routing: Lazy loading con loadComponent/loadChildren
## Struttura Cartelle
```
src/app/
core/ # Servizi singleton, guard, interceptor
shared/ # Componenti, pipe, direttive condivise
features/ # Feature modules (una cartella per feature)
feature-a/
components/
services/
models/
feature-a.routes.ts
layouts/ # Layout components (header, footer, sidebar)
```
## Principi
- NESSUN NgModule: tutto standalone
- Lazy loading per ogni feature route
- Servizi in core/ forniti in root (providedIn: 'root')
- Componenti condivisi in shared/ senza logica di business
- Un componente = un file .ts + .html + .css + .spec.ts
---
description: Regole per l'uso di Angular Signals e reattività
globs: ["**/*.component.ts", "**/*.service.ts"]
alwaysApply: false
---
# Angular Signals
## Stato Reattivo
- USA: signal() per stato locale del componente
- USA: computed() per valori derivati
- USA: effect() SOLO per side effects (logging, localStorage)
- NON USARE: BehaviorSubject per stato locale
- NON USARE: getter con logica complessa (usa computed)
## Input/Output Signal-based
- USA: input() e input.required() per gli input
- USA: output() per gli eventi
- NON USARE: @Input() e @Output() decorators (deprecati)
- USA: model() per two-way binding
## Esempio Corretto
```typescript
export class UserCardComponent {
// Input signal-based
readonly user = input.required<User>();
readonly showAvatar = input(true);
// Computed da input
readonly displayName = computed(() =>
`${this.user().firstName} ${this.user().lastName}`
);
// Output signal-based
readonly selected = output<User>();
onSelect(): void {
this.selected.emit(this.user());
}
}
```
## Anti-pattern da Evitare
```typescript
// SBAGLIATO: decoratori legacy
@Input() user!: User;
@Output() selected = new EventEmitter<User>();
// SBAGLIATO: BehaviorSubject per stato locale
private userSubject = new BehaviorSubject<User | null>(null);
```
---
description: Convenzioni per i test unitari Angular con Jest/Vitest
globs: ["**/*.spec.ts"]
alwaysApply: false
---
# Testing Angular
## Framework
- Test runner: Jest o Vitest (NO Karma/Jasmine)
- Asserzioni: expect() nativo
- Mocking: jest.mock() o vi.mock()
## Struttura Test
- Raggruppa con describe() per metodo/feature
- Naming: "should [expected behavior] when [condition]"
- AAA pattern: Arrange, Act, Assert
- Un assert per test (quando possibile)
## Componenti
- Usa TestBed.configureTestingModule con standalone: true
- Mock tutti i servizi iniettati
- Testa il rendering del template con fixture.debugElement
- Testa gli input/output signal-based con componentRef.setInput()
## Servizi
- Usa TestBed.inject() per ottenere il servizio
- Mock HttpClient con HttpClientTestingModule
- Testa tutti i path: successo, errore, edge case
- Verifica le chiamate HTTP con expectOne()
## Copertura Minima
- Servizi: 90%
- Componenti: 80%
- Utility: 95%
Python 규칙: 전체 예
Python은 정확한 철학(The Zen of Python)과 통합된 규칙(PEP 8)을 갖춘 언어입니다. Python 규칙은 이러한 규칙을 포착하고 프로젝트 세부 사항을 추가해야 합니다.
---
description: Convenzioni Python per il progetto backend
globs: ["**/*.py"]
alwaysApply: false
---
# Convenzioni Python
## Versione e Stile
- Python 3.12+
- Segui PEP 8 rigorosamente
- Type hints su TUTTE le funzioni e variabili di classe
- Usa f-string per la formattazione (mai .format() o %)
- Line length massimo: 100 caratteri
## Type Hints
```python
def get_user_by_id(user_id: int) -> User | None:
"""Recupera un utente per ID."""
...
def process_items(items: list[Item], *, limit: int = 100) -> list[Result]:
"""Processa una lista di item con limite opzionale."""
...
```
## Struttura Classi
- Usa dataclasses o Pydantic models per i dati
- Protocol per le interfacce (non ABC, salvo casi specifici)
- Metodi privati con prefisso _ (singolo underscore)
- Nessun metodo > 30 righe
## Import
- Ordine: stdlib, third-party, local (separati da riga vuota)
- Import assoluti (mai relativi con .)
- Usa `from __future__ import annotations` per type hints moderni
## Error Handling
- Cattura eccezioni specifiche (mai bare except)
- Usa custom exceptions per errori di dominio
- Logging strutturato con structlog
---
description: Pattern e convenzioni per le API FastAPI
globs: ["**/api/**/*.py", "**/routes/**/*.py", "**/endpoints/**/*.py"]
alwaysApply: false
---
# Pattern FastAPI
## Struttura Endpoint
```python
@router.get(
"/users/{user_id}",
response_model=UserResponse,
summary="Get user by ID",
responses={404: {"model": ErrorResponse}},
)
async def get_user(
user_id: int = Path(..., gt=0),
db: AsyncSession = Depends(get_db),
current_user: User = Depends(get_current_user),
) -> UserResponse:
"""Recupera un utente specifico per ID."""
user = await user_service.get_by_id(db, user_id)
if not user:
raise HTTPException(status_code=404, detail="User not found")
return UserResponse.model_validate(user)
```
## Convenzioni
- Usa Pydantic v2 per request/response models
- Dependency Injection per DB, auth, config
- Async per TUTTE le operazioni I/O
- Response models espliciti (mai dict generici)
- Validazione input con Field() e Path()
- HTTP status codes corretti (201 create, 204 delete, etc.)
## Error Handling
- HTTPException per errori HTTP standard
- Custom exception handlers per errori di dominio
- Formato errore standard: {"detail": "message", "code": "ERROR_CODE"}
React/Next.js 규칙: 전체 예
React 생태계는 서버 구성 요소, 앱 라우터, Actions가 포함된 React 19 등 끊임없이 진화하고 있습니다. 규칙은 현대적인 규칙을 수용하고 레거시 패턴을 피해야 합니다.
---
description: Convenzioni React e Next.js per il progetto frontend
globs: ["**/*.tsx", "**/*.jsx"]
alwaysApply: false
---
# React / Next.js Conventions
## Framework
- Next.js 15+ con App Router
- React 19+ con Server Components di default
- TypeScript strict mode
- Styling: Tailwind CSS v4
## Componenti
- Server Components per default (niente "use client" se non necessario)
- Client Components SOLO per interattivita (click, form, state)
- Named export per i componenti (non default export)
- Props tipizzate con interface (non type alias)
## Pattern Preferiti
```tsx
// Server Component (default)
interface UserProfileProps {
readonly userId: string;
}
export async function UserProfile({ userId }: UserProfileProps) {
const user = await getUser(userId);
return (
<section className="p-4">
<h2>{user.name}</h2>
<UserActions user={user} />
</section>
);
}
```
## State Management
- React useState/useReducer per stato locale
- Zustand per stato globale client-side
- Server Actions per mutazioni (form, POST)
- NON usare useEffect per fetch dati (usa Server Components)
## Anti-pattern
- NO default export per componenti
- NO useEffect per data fetching
- NO index.tsx come nome componente
- NO prop drilling > 3 livelli (usa context o composition)
백엔드 및 REST API에 대한 규칙
API는 프런트엔드와 백엔드 간의 계약입니다. 잘 정의된 규칙은 응답의 일관성을 보장합니다. 오류 처리 및 인증.
---
description: Convenzioni API REST per tutti gli endpoint
globs: ["**/controllers/**", "**/routes/**", "**/api/**"]
alwaysApply: false
---
# API REST Conventions
## URL Design
- Risorse in plurale: /users, /products, /orders
- Nesting massimo: 2 livelli (/users/{id}/orders)
- Verbi HTTP per le azioni: GET (read), POST (create), PUT (replace),
PATCH (update), DELETE (remove)
- Query params per filtering, sorting, pagination
## Response Format Standard
```json
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 150
}
}
```
## Error Response Format
```json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Email format is invalid",
"details": [
{ "field": "email", "message": "Must be a valid email address" }
]
}
}
```
## Status Codes
- 200: Success (GET, PUT, PATCH)
- 201: Created (POST)
- 204: No Content (DELETE)
- 400: Bad Request (validazione fallita)
- 401: Unauthorized (non autenticato)
- 403: Forbidden (non autorizzato)
- 404: Not Found
- 409: Conflict (duplicato, stato inconsistente)
- 422: Unprocessable Entity (logica di business)
- 500: Internal Server Error (mai esporre dettagli)
## Paginazione
- Usa cursor-based pagination per dataset grandi
- Offset-based per casi semplici
- Includi sempre: page, limit, total, hasNext
레거시 .cursorrules 파일에서 마이그레이션
이전 파일을 사용하는 경우 .cursorrules, 좋은 소식은 커서가 그것을 유지한다는 것입니다
이전 버전과의 호환성: 레거시 파일은 계속 작동합니다. 그러나 새로운 시스템으로 마이그레이션
.cursor/rules/ 조직 및 유연성 측면에서 상당한 이점을 제공합니다.
마이그레이션 전략
마이그레이션이 전부 아니면 전무한 작업일 필요는 없습니다. 다음 단계에 따라 점진적으로 진행할 수 있습니다.
- 디렉터리 만들기
.cursor/rules/당신의 프로젝트에서 - 카테고리 식별 당신의 파일에
.cursorrules: 일반적인 규칙, 언어, 테스트 패턴, 응답 스타일에 대한 규칙 - 각 카테고리 추출 파일에
.mdc적절한 머리말로 분리 - 올바른 유형을 할당하세요.: 항상 보편적인 규칙을 위해, 글로브로 자동 연결됨 언어별 규칙에 대해서는 상담원에게 전문 지식이 필요합니다.
- 머리 AI는 다양한 상황에서 새로운 규칙을 존중합니다.
- 제거하다 파일
.cursorrules마이그레이션에 만족할 때
.cursorrules과 .cursor/rules/ 간의 충돌
둘 다 존재하는 경우 커서는 두 파일을 모두 로드합니다. .cursorrules 그 파일은
.cursor/rules/. 이로 인해 중복되거나 모순되는 지침이 발생할 수 있습니다. 동안
마이그레이션, 섹션에 대한 의견 .cursorrules 새 파일로 추출하면
.mdc, 마이그레이션이 완료된 경우에만 기존 파일을 제거하세요.
고급 규칙 전략
고급 글로브 패턴
Glob 패턴은 규칙의 정확한 대상 지정을 위한 가장 강력한 도구입니다. 패턴은 다음과 같습니다. 실제 시나리오에 더 유용합니다.
# File specifici per tipo
**/*.component.ts # Tutti i componenti Angular
**/*.service.ts # Tutti i servizi Angular
**/*.spec.ts # Tutti i file di test
**/*.stories.tsx # Tutti gli Storybook stories
# Directory specifiche
src/app/core/** # Tutto nella directory core
src/app/features/**/*.ts # Solo TypeScript nelle features
# Combinazioni multiple
**/*.{ts,tsx} # TypeScript e TypeScript React
**/{api,routes}/**/*.py # File Python in api/ o routes/
# Esclusioni con negazione (in alcuni contesti)
!**/*.spec.ts # Escludi i file di test
!**/node_modules/** # Escludi node_modules
파일 유형에 대한 조건부 규칙
효과적인 전략은 파일의 컨텍스트에 따라 활성화되는 규칙을 만드는 것입니다. 예를 들어, 애플리케이션 논리 파일과 데이터베이스 마이그레이션 파일에 대해 다른 규칙을 가질 수 있습니다. 둘 다 Python 파일이지만.
---
description: Regole specifiche per file di migrazione Alembic
globs: ["**/alembic/versions/**/*.py", "**/migrations/**/*.py"]
alwaysApply: false
---
# Migrazioni Database (Alembic)
## Struttura
- Ogni migrazione deve avere upgrade() e downgrade()
- Commenta SEMPRE la motivazione della migrazione
- Usa batch operations per SQLite compatibility
## Naming
- Formato: YYYYMMDD_HHMM_descrizione_breve.py
- Descrizione in snake_case, max 50 caratteri
## Safety
- Mai DROP TABLE senza backup esplicito
- Mai ALTER COLUMN che rimuove dati senza migrazione dati
- Testa SEMPRE downgrade() prima di committare
규칙 구성성: 서로를 보완하는 규칙
규칙은 고립되지 않고 AI의 맥락에서 결합됩니다. 효과적인 전략과 디자인 규칙 서로를 보완하여 일관된 지침 시스템을 만듭니다.
예를 들어 일반 규칙에는 항상 규칙을, 규칙에는 자동 연결 규칙을 적용할 수 있습니다.
언어 사양 및 아키텍처 패턴에 대한 에이전트 요청 규칙. 일할 때
Angular 구성 요소에서 AI는 다음을 수신합니다: 일반 규칙(항상) + Angular 규칙
(글로브에서 자동 첨부 **/*.component.ts) + 아마도 아키텍처 규칙
(에이전트가 작업과 관련이 있다고 판단하는 경우)
자동으로 규칙 생성
Cursor에는 기존 코드베이스에서 규칙을 생성하는 내장 명령이 포함되어 있습니다.
/Generate Cursor Rules. 이 명령은 프로젝트를 분석하고 패턴을 식별합니다.
이미 사용 중인 규칙을 포착하는 초기 규칙 세트를 반복적으로 생성합니다.
명령을 사용하는 방법
- 커서의 채팅 패널 열기(
Cmd+L/Ctrl+L) - 유형
/Generate Cursor Rules - AI는 귀하의 코드베이스를 분석하고 일련의 규칙을 제안합니다.
- 제안된 규칙을 검토, 수정 및 디렉토리에 저장합니다.
.cursor/rules/
팁: 기존 코드베이스에서 시작
명령 /Generate Cursor Rules 특히 기존 프로젝트에 유용합니다.
규칙은 코드에 암시되어 있지만 문서화되어 있지는 않습니다. AI는 다음과 같은 패턴을 식별합니다.
구성 요소 구조, 이름 지정, 오류 처리 패턴을 파악하고 이를 명시적인 규칙으로 변환합니다.
결과를 최종 구성이 아닌 구체화할 시작점으로 고려하세요.
프롬프트를 통한 지원 생성
Cursor의 AI에게 도움을 요청하여 수동으로 규칙을 만들 수도 있습니다. 샘플 파일을 제공해 주세요. 당신의 이상적인 스타일을 표현하고 AI에게 관습을 추출하도록 요청하세요.
Analizza il file user.service.ts e genera un file .mdc per
.cursor/rules/ che catturi tutte le convenzioni che vedi:
- Pattern di gestione errori
- Struttura dei metodi
- Uso di tipi e interfacce
- Pattern di dependency injection
- Formato dei commenti e della documentazione
Il file deve essere Auto Attached per tutti i file *.service.ts
팀 작업 흐름: 공유 규칙
프로젝트 규칙의 가장 중요한 장점 중 하나는 git을 통해 공유할 수 있다는 것입니다. 이는 팀 조정과 새로운 개발자 온보딩을 위한 엄청난 가능성을 열어줍니다.
나눔 전략
디렉토리 .cursor/rules/ 다음과 같이 저장소에 커밋되어야 합니다.
.editorconfig, .eslintrc o tsconfig.json. 이 규칙
이는 프로젝트 정의의 일부가 되며 각 팀 구성원이 언제
커서를 사용하면 동일한 AI 지침을 받을 수 있습니다.
.cursor/
rules/
# Always Rules - Convenzioni universali
01-project-overview.mdc # Descrizione del progetto e stack
02-coding-standards.mdc # Standard di codice condivisi
03-git-workflow.mdc # Convenzioni git e PR
# Auto Attached - Per linguaggio/framework
angular-components.mdc # Regole componenti Angular
angular-services.mdc # Regole servizi Angular
angular-testing.mdc # Regole test Angular
css-conventions.mdc # Regole CSS/SCSS
api-endpoints.mdc # Regole API REST
# Agent Requested - Conoscenze specialistiche
database-schema.mdc # Schema e migrazioni DB
deployment-pipeline.mdc # Pipeline CI/CD
security-guidelines.mdc # Linee guida sicurezza
# Manual - Template e snippet
new-feature-template.mdc # Template nuova feature
bug-fix-checklist.mdc # Checklist per bug fix
code-review-criteria.mdc # Criteri per code review
규칙을 사용한 온보딩
프로젝트 규칙은 새로운 개발자의 온보딩 속도를 크게 높일 수 있습니다. 새로운 것 저장소를 복제하고 커서를 사용하기 시작한 팀원은 즉시 모든 저장소에 액세스할 수 있습니다. AI를 통한 프로젝트 컨벤션. 50페이지 분량의 온보딩 문서를 읽을 필요가 없습니다. 코드를 작성할 때마다 AI는 자동으로 올바른 규칙을 적용합니다.
공유 규칙의 이점
- 일관성: AI가 생성한 모든 코드는 상관없이 동일한 표준을 따릅니다. 개발자에 의해
- 빠른 온보딩: 새로운 개발자는 첫날부터 규정을 준수하는 코드를 생성합니다.
- 코드 검토 감소: 스타일과 관례에 대한 설명은 줄이고 논리에 더 중점을 둡니다.
- 실시간 문서: 규칙은 프로젝트와 함께 업데이트되는 실행 가능한 문서입니다.
- 제어된 진화: 규칙 변경은 다른 것과 마찬가지로 git 검토를 거칩니다. 변화
CLAUDE.md 및 기타 시스템과의 비교
커서의 규칙 시스템은 프로젝트 컨텍스트에 대해 AI를 교육하는 유일한 방법은 아닙니다.
클로드 코드는 파일을 사용합니다 CLAUDE.md, GitHub Copilot이 소개한
.github/copilot-instructions.md 및 윈드서핑 용도 .windsurfrules.
그들이 어떻게 비교되는지 봅시다.
AI 구성 시스템 비교
| 특성 | 커서 규칙 | 클로드.md | 부조종사 지침 |
|---|---|---|---|
| 여러 파일 | 예(.cursor/rules/) | 예(.claude/ 디렉터리) | 단일 파일 |
| 활성화 유형 | 4가지 유형(항상, 자동, 에이전트, 수동) | 항상 활성 + 메모리 | 항상 활성 |
| 지구본 패턴 | 예(프런트매터 글로브) | No | No |
| 힘내 공유 | Si | Si | Si |
| 사용자 수준 규칙 | 예(설정) | 예(~/.claude/) | 제한된 |
| 체재 | .mdc(YAML 머리말 + MD) | .md(순수 마크다운) | .md(순수 마크다운) |
| 자동 생성 | 예(/커서 규칙 생성) | 아니요(단, /init 사용 가능) | No |
가장 큰 차이점은 시스템이다. 조건부 활성화 커서의.
CLAUDE.md 및 Copilot 지침은 항상 활성화되어 있지만(모든 상호 작용에서 컨텍스트를 소비함)
커서를 사용하면 관련된 경우에만 규칙을 활성화할 수 있습니다. 프론트엔드가 포함된 풀스택 프로젝트에서
Angular, Python 백엔드 및 Terraform 인프라, Angular 규칙은 다음 경우에만 포함됩니다.
파일 작업 .component.ts, 관련 지침에 대한 귀중한 컨텍스트를 저장합니다.
Cursor의 또 다른 독특한 장점은 다음과 같습니다. 에이전트가 요청함. AI가 결정할 수 있다 업무에 따라 어떤 규칙을 자율적으로 참조하여 주문형 지식 시스템을 생성합니다. 불필요하게 컨텍스트를 소비하지 않고 제한 없이 확장할 수 있습니다.
완전한 실제 사례
이 섹션에서는 일반적인 시나리오에 대해 즉시 사용할 수 있는 규칙 컬렉션을 수집합니다.
각 예제는 완료되었으며 디렉터리에 직접 복사할 수 있습니다. .cursor/rules/.
규칙: BEM 및 사용자 정의 속성을 사용한 CSS 스타일
---
description: Convenzioni CSS con BEM naming e custom properties
globs: ["**/*.css", "**/*.scss"]
alwaysApply: false
---
# CSS Conventions
## Naming: BEM (Block-Element-Modifier)
- Block: .card, .nav, .form
- Element: .card__title, .card__body, .nav__link
- Modifier: .card--featured, .nav__link--active
## Custom Properties (Design Tokens)
- Colori: --color-primary, --color-surface, --color-text
- Spacing: --space-xs (4px), --space-sm (8px), --space-md (16px)
- Typography: --font-heading, --font-body
- Breakpoints: --bp-mobile (768px), --bp-tablet (1024px)
## Regole
- Mobile-first: min-width per media queries
- No !important (mai, salvo utility override)
- No nesting > 3 livelli in SCSS
- Usa logical properties (margin-inline, padding-block)
- Preferisci Grid e Flexbox (no float)
규칙: Docker 및 컨테이너화
---
description: Regole per Dockerfile e docker-compose
globs: ["**/Dockerfile*", "**/docker-compose*.yml", "**/.dockerignore"]
alwaysApply: false
---
# Docker Conventions
## Dockerfile
- Multi-stage build SEMPRE (build + runtime)
- Immagine base: usa versioni specifiche (node:20-alpine, non node:latest)
- USER non-root: crea e usa un utente applicativo
- COPY selettivo: prima package*.json, poi npm ci, poi il resto
- .dockerignore: escludi node_modules, .git, test, docs
## Esempio Struttura
```dockerfile
# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build
# Stage 2: Runtime
FROM node:20-alpine AS runtime
RUN addgroup -S app && adduser -S app -G app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER app
EXPOSE 3000
CMD ["node", "dist/main.js"]
```
## docker-compose
- Usa version "3.8" o superiore
- Health checks per tutti i servizi
- Named volumes per dati persistenti
- Environment variables via .env file (non inline)
규칙: 보안 및 인증
---
description: Linee guida di sicurezza per autenticazione, autorizzazione e protezione dati
alwaysApply: false
---
# Security Guidelines
## Autenticazione
- JWT con refresh token rotation
- Access token: breve durata (15 min)
- Refresh token: durata media (7 giorni), one-time use
- Password: bcrypt con salt rounds >= 12
- NESSUN segreto hardcoded nel codice
## Autorizzazione
- RBAC (Role-Based Access Control) come base
- Verifica permessi a livello di controller E service
- Principio del minimo privilegio: concedi solo ciò che serve
- Audit log per operazioni sensibili
## Input Validation
- Valida TUTTI gli input a livello di boundary (controller)
- Sanitizza HTML per prevenire XSS
- Query parametrizzate SEMPRE (mai concatenazione SQL)
- Rate limiting su tutti gli endpoint pubblici
## Headers di Sicurezza
- Content-Security-Policy
- X-Content-Type-Options: nosniff
- Strict-Transport-Security
- X-Frame-Options: DENY
규칙: 언어 간 오류 처리
---
description: Pattern di gestione errori consistente tra frontend e backend
alwaysApply: true
---
# Error Handling Pattern
## Principi
- Non ingoiare MAI un errore silenziosamente
- Log dettagliato server-side, messaggio user-friendly client-side
- Errori previsti: gestione esplicita con recovery
- Errori imprevisti: catch globale + logging + notifica
## Frontend (Angular/React)
- HttpClient: gestisci errori con catchError/try-catch
- Mostra toast/snackbar per errori utente
- Retry automatico per errori di rete (max 3 tentativi)
- Fallback UI per stati di errore (ErrorBoundary/error template)
## Backend (Node/Python)
- Custom exception classes per errori di dominio
- Global exception handler come middleware
- Structured logging: livello, timestamp, correlation-id, stack trace
- Non esporre MAI stack trace o dettagli interni al client
## Formato Standard
```
Log: [LEVEL] [TIMESTAMP] [CORRELATION-ID] [SERVICE] Message {context}
API: { "success": false, "error": { "code": "XXX", "message": "..." } }
```
모범 사례 및 일반적인 실수
피해야 할 실수
- 너무 많습니다. 항상: 모든 규칙이 항상인 경우 컨텍스트를 낭비하는 것입니다. AI 변수 이름을 바꾸라고 요청하는 경우에도 수천 개의 명령 토큰을 얻습니다.
- 규칙이 너무 모호함: “좋은 코드 작성”은 AI에 도움이 되지 않습니다. 구체적으로 설명하세요: "각각 명시적인 유형이 있는 최대 4개의 매개변수가 있는 함수"
- 모순되는 규칙: 한 규칙에 "클래스 사용"이 있고 다른 규칙에 "함수 사용"이 있으면 AI가 혼란스러워집니다. 규칙의 일관성을 검토하세요.
- 예시 부족: 구체적인 예가 없는 규칙은 다음과 같은 방식으로 따릅니다. 일관성이 없습니다. 항상 적어도 하나의 긍정적인 예와 하나의 부정적인 예를 포함하십시오.
- 규칙을 업데이트하지 마세요. 규칙은 프로젝트와 함께 발전해야 합니다. 마이그레이션하는 경우 Angular 17에서 19까지, 새로운 패턴을 반영하도록 규칙을 업데이트합니다.
효과적인 구성을 위한 체크리스트
- 보편적인 프로젝트 규칙으로 1-3 Always 규칙을 정의합니다.
- 프로젝트의 각 언어/프레임워크에 대한 자동 연결 규칙을 생성합니다.
- 전문 지식(데이터베이스, 배포, 보안)에 대한 에이전트 요청 규칙 추가
- 반복적인 템플릿 및 워크플로에 대한 수동 규칙 준비
- 모든 것을 커밋하세요.
.cursor/rules/그리고 그것을 팀에 전달하세요. - 스프린트 또는 릴리스마다 규칙을 검토하고 업데이트합니다.
- 미국
/Generate Cursor Rules새로운 프로젝트의 출발점으로
결론
커서의 규칙 시스템은 개발자 방식의 질적 도약을 나타냅니다. AI와 상호 작용합니다. 단순히 챗봇에게 지시를 내리는 것이 아닙니다. AI가 이해하고 적용할 수 있는 형식으로 팀 규칙을 성문화합니다. 자동으로.
네 가지 규칙 유형(항상, 자동 연결, 에이전트 요청, 수동)은 다음 수준을 제공합니다. 현재 다른 어떤 AI 도구도 제공하지 않는 세분성. 규칙을 활성화하는 기능 파일 형식에 따라 조건부로 에이전트 요청 타겟팅과 결합되어 품질 저하 없이 프로젝트 복잡성에 따라 확장되는 동적 지식 시스템 AI 성능.
가장 중요한 팁은? 지금 시작하세요, 간단하게 시작해 보세요. 항상 규칙 만들기 프로젝트의 가장 중요한 10가지 규칙을 사용하여 주요 언어를 선택하고 거기에서 반복합니다. 처음부터 완벽한 설정이 필요하지 않습니다. 규칙은 코드와 마찬가지로 프로젝트와 함께 발전합니다.
시리즈의 다음 기사에서는에이전트 모드: 작업을 위임하는 방법 전체 기능 리팩토링부터 테스트 스위트 생성까지 Cursor의 AI에 대한 컴플렉스 완료. 이 문서에서 구성한 규칙은 다음의 기초가 됩니다. 에이전트가 자신의 작품을 만들 것입니다.
추가 리소스
- 커서 공식 문서: docs.cursor.com/context/rules-for-ai
- 예시 저장소: github.com/cursor-rules-examples
- 지역 사회: forum.cursor.com에서 규칙을 공유하고 발견하세요
- 다음 기사: 에이전트 모드 - 명령으로 코드베이스 편집