02 – Pravidla kurzoru: Konfigurace AI pro váš projekt
Každý developer má své vlastní konvence, architektonické vzory a standardy kvality. Když pracujete s lidský kolega, jsou tato pravidla sdělována prostřednictvím kontroly kódu, párového programování a dokumentace. Ale jak můžete sdělit stejná očekávání agentovi AI? Odezva kurzoru a Systém pravidel: výkonný a flexibilní mechanismus, který vám umožní instruovat AI, jak na to musí vygenerovat, upravit a zdůvodnit kód vašeho projektu.
V tomto článku prozkoumáme každý aspekt systému pravidel kurzoru: od jeho historického vývoje to advanced configuration strategies, passing through practical examples for Angular, React, Python, API backends a mnohem více. Nakonec budete mít všechny nástroje k tomu, abyste z Cursor AI udělali spolupracovníka respektujte konvence svého týmu, jako by je znali odjakživa.
Co se dozvíte v tomto článku
- Vývoj systému pravidel: od
.cursorrulesdo adresáře.cursor/rules/ - Čtyři typy pravidel: Vždy, Automaticky připojeno, Vyžádáno agentem a Ručně
- Rozdíl mezi pravidly uživatele a pravidly projektu a kdy použít jednotlivé typy
- Jak napsat efektivní pravidla s frontmatterem, globy a popisy
- Kompletní příklady pro Angular, React, Python, FastAPI a REST API
- Pokročilé strategie: podmíněná pravidla, dědičnost pravidel, automatické generování
- Týmový pracovní postup: sdílení přes git, onboarding a sdílené konvence
- Srovnání s CLAUDE.md a dalšími instrukčními systémy AI
Přehled vývojových sérií Cursor IDE a AI-Native
| # | Položka | Soustředit |
|---|---|---|
| 1 | Kompletní průvodce IDE pro kurzor | Kompletní přehled |
| 2 | Jste zde - Pravidla kurzoru | Vlastní nastavení AI |
| 3 | Režim agenta | Pokročilá automatizace |
| 4 | Režim plánu | Asistované plánování |
| 5 | Háčky a MCP | Rozšiřitelnost a integrace |
| 6 | Profesionální pracovní postupy | Nejlepší výrobní postupy |
Vývoj systému pravidel v kurzoru
Systém pravidel kurzoru prošel od svého prvního zavedení významným vývojem. Pochopení této historie je zásadní pro pochopení toho, proč je současný systém strukturován určitým způsobem a aby nedošlo k záměně mezi různými generacemi konfigurace.
První generace: soubor .cursorrules
V první implementaci Cursor podporoval jeden soubor .cursorrules v kořenovém adresáři projektu.
Tento soubor obsahoval pokyny ve volném textu, které byly vloženy do kontextu každé interakce AI.
Bylo to jednoduché a přímočaré: zapište si pravidla do souboru a AI se jimi bude řídit.
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
Tento přístup měl zjevné omezení: všechna pravidla skončila v jediném monolitickém souboru.
V komplexním projektu s rozhraním Angular, backendem Pythonu, infrastrukturou Docker a kanálem CI/CD,
soubor .cursorrules rychle se stal obrovským a bylo obtížné jej spravovat. Také všechna pravidla
byly vždy odeslány do AI, i když nebyly relevantní pro aktuální kontext.
Druhá generace: Pravidla projektu s .cursor/rules/
K vyřešení těchto omezení zavedl Cursor Pravidla projektu na základě
adresář .cursor/rules/. This new approach allows you to organize rules in separate files,
with structured metadata and conditional activation based on file patterns.
Adresář .cursor/rules/ a chtěl být zavázán k úložišti git, takže každý
členové týmu automaticky sdílejí stejné pokyny AI. Každý soubor v adresáři je soubor
.mdc (Markdown with Context), který obsahuje YAML frontmatter a tělo prohlášení v Markdown.
Proč .mdc a ne .md?
Formát .mdc (Markdown with Context) je proprietární rozšíření Cursor, které přidává
standardní strukturovaný frontmat Markdown. Frontmatter definuje metadata jako popis
pravidlo, vzory glob pro automatickou aktivaci a příznak alwaysApply. Kurzor interpretuje
tato metadata k rozhodnutí, kdy a jak použít každé pravidlo.
Čtyři typy pravidel
Moderní systém kurzoru definuje čtyři režimy aktivace pravidel, z nichž každý je určen konkrétní případ použití. Výběr správného typu je zásadní pro vyvážení relevance pokynů se spotřebou kontextu AI.
1. Vždy Pravidla
Pravidla typu Vždy jsou součástí každé interakce s AI, bez ohledu na to ze souboru, na kterém pracujete, nebo z vašeho požadavku. Jsou ideální pro univerzální konvence projekt, který je třeba vždy respektovat.
---
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
Pozor na kontextovou spotřebu
Pravidla vždy přijdou Vždy odeslány do AI, přičemž v každém z nich spotřebovávají tokeny kontextu interakce. Tento typ používejte pouze pro skutečně univerzální pravidla. Pokud se pravidlo vztahuje pouze na určité soubory nebo situace, preferujte Auto Attached nebo Agent Requested pro optimalizaci využití kontextu.
2. Automaticky připojená pravidla
Pravidla Automaticky připojeno se automaticky aktivují, když pracujete na odpovídajících souborech ke konkrétním vzorům glob. Jsou ideální pro pravidla specifická pro jazyk, rámec nebo typ souboru.
---
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)
Pole globs podporuje standardní vzory glob. Můžete použít jednoduché zástupné znaky jako *.ts
nebo složité vzory jako např {**/*.service.ts,**/*.guard.ts}. Když otevřete soubor
která odpovídá vzoru, je pravidlo automaticky zahrnuto do kontextu AI.
3. Pravidla požadovaná agentem
Pravidla Vyžádán agent jsou viditelné pro AI prostřednictvím jejich popisu, ale přicházejí zahrnuty do kontextu pouze tehdy, když agent rozhodne, že jsou relevantní pro aktuální úkol. Tento chlap a ideální pro specializovaná pravidla, která nejsou vždy potřebná, ale s nimiž musí být umělá inteligence schopna v případě potřeby konzultovat.
---
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
V tomto příkladu pravidlo nemá globs a má alwaysApply: false. AI uvidí pouze
popis "Pravidla pro vytváření a správu migrací databází s Prisma" a bude rozhodovat samostatně
zda zahrnout celý obsah pravidla, když úloha zahrnuje databázové operace. Tento přístup
a zvláště efektivní: AI má přístup ke katalogu odborných znalostí, aniž by plýtvalo kontextem
když nejsou potřeba.
4. Manuální pravidla
Pravidla Manuál nikdy nejsou automaticky zahrnuty. Musí být výslovně zmíněny
vývojářem pomocí reference @ruleName ve výzvě. Jsou užitečné pro šablony,
úryvky nebo pokyny, které chcete použít pouze v konkrétních situacích.
---
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
Chcete-li použít toto pravidlo, vývojář napíše něco jako: "Vytvořte novou funkci pro svůj uživatelský profil sledováním @new-feature-template". AI zahrne obsah pravidla do kontextu a vygeneruje kód podle šablony.
Souhrn typů pravidel
| Typ | Aktivace | Use Case | Kontext spotřeby |
|---|---|---|---|
| Vždy | Vždy v ceně | Univerzální designové konvence | Vysoká (vždy aktivní) |
| Automaticky připojeno | Vzor koule v souboru | Pravidla specifická pro jazyk/rámec | Střední (pouze příslušné soubory) |
| Vyžádán agent | AI se rozhoduje na základě popisu | Odborné znalosti na vyžádání | Nízká (pouze v případě potřeby) |
| Manuál | Explicitní volání s @jméno | Šablony, úryvky, vzácné pokyny | Minimum (pouze na vyžádání) |
Pravidla uživatele vs. Pravidla projektu
Kurzor rozlišuje dvě konfigurační úrovně: le Pravidla pro uživatele které platí pro všechny vaše projekty a Pravidla projektu které jsou specifické pro jediné úložiště. Understanding when to use one or the other is critical to an effective setup.
Pravidla uživatele: Vaše globální preference
Uživatelská pravidla jsou konfigurována v Cursor Settings > General > Rules for AI. Tato pravidla
definují vaše osobní preference, které zůstávají konstantní bez ohledu na projekt, na kterém pracujete.
Nejsou to soubory v úložišti: žijí v místní konfiguraci kurzoru.
## 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
Pravidla projektu: Konvence úložiště
Pravidla projektu jsou uložena v adresáři .cursor/rules/ projektu a jsou zavázány
v úložišti git. To znamená, že každý člen týmu, který klonuje úložiště, bude mít automaticky
stejné instrukce AI, zajišťující konzistenci při generování kódu.
Pravidla uživatele vs pravidla projektu: Kdy použít co
| čekám | Pravidla pro uživatele | Pravidla projektu |
|---|---|---|
| Košťata | Všechny projekty | Jediné úložiště |
| Pozice | Nastavení kurzoru | .cursor/rules/*.mdc |
| Sdílení | Pouze místní | Přes git (tým) |
| Přednost | Základna (přepsána projektem) | Vysoká (konkrétní podle kontextu) |
| Příklad | Jazyk, styl odezvy, obecné zásady | Rámec, architektura, specifické vzory |
La přednost Funguje to intuitivně: Pravidla projektu mají přednost před pravidly uživatele když dojde ke konfliktu. Pokud vaše pravidla uživatele říkají „použít třídy“, ale vaše pravidla projektu říkají „použít funkce“, AI se bude řídit pravidly projektu. To umožňuje každému projektu mít své vlastní konvence bez muset změnit globální preference.
Anatomie efektivního pravidla
Napsání pravidla, které umělá inteligence dokáže správně dodržovat, vyžaduje pozornost ke struktuře a srozumitelnosti a jednoduchost návodu. Dobře napsané pravidlo je rozdíl mezi AI, která generuje kód generické a AI, která generuje kód dokonale v souladu s vašimi standardy.
Struktura souboru .mdc
Každý soubor .mdc a skládá se ze dvou částí: Přední strana YAML ohraničený
--- e il tělo v Markdown se skutečnými pokyny.
---
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
Nejlepší postupy pro psaní účinných pravidel
Po konfiguraci stovek pravidel v reálných projektech jsem identifikoval pět základních principů které určují účinnost pravidla.
1. Buďte konkrétní, ne generická. Pravidlo, které říká „pište čistý kód“, je k ničemu. Pravidlo, které říká, že „každá funkce musí mít maximálně 4 parametry, každý s explicitním typem a JSDoc“ a ovladatelný AI.
2. Ukaž, ne jen řekni. Vždy uveďte alespoň jeden konkrétní příklad kódu, který respektovat pravidlo. Umělá inteligence se učí lépe z příkladů než z abstraktních popisů.
3. Definujte také anti-vzory. Výslovně uveďte, co NEDĚLAT. Pokud pravidlo říká „použij signály“, ale neříká „nepoužívej BehaviorSubject“, umělá inteligence by mohla tyto dva přístupy kombinovat.
4. Pravidlo, téma. Nevytvářejte monolitické soubory, které pokrývají vše. Rozdělte pravidla na oblast: jedno pravidlo pro testování, jedno pro CSS, jedno pro architekturu. To usnadňuje údržbu a umožňuje selektivní aktivaci prostřednictvím globs.
5. Napište popis s ohledem na AI. Pole description ve frontmatteru
a co AI čte, aby se rozhodla, zda zahrnout pravidlo Agent Requested. Musí to být stručné, ale
dostatečně informativní, aby umělá inteligence mohla pochopit, kdy je pravidlo relevantní.
Pravidla pro Angular: Kompletní příklad
Angular je rámec s přesnými konvencemi a rychle se vyvíjejícím ekosystémem. S průchodem pro samostatné komponenty, signály a novou syntaxi řídicího toku je nezbytné, aby AI generovala kód která se řídí moderními osvědčenými postupy. Zde je kompletní sada pravidel pro projekt 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%
Pravidla pro Python: Kompletní příklad
Python je jazyk s přesnou filozofií (The Zen of Python) a konsolidovanými konvencemi (PEP 8). Pravidla pro Python musí tyto konvence zachytit a přidat specifika projektu.
---
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"}
Pravidla pro React/Next.js: Kompletní příklad
Ekosystém React se neustále vyvíjí: Serverové komponenty, App Router, React 19 s akcemi. Pravidla musí zachycovat moderní konvence a vyhýbat se zastaralým vzorům.
---
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)
Pravidla pro Backend a REST API
API jsou smlouvou mezi frontendem a backendem. Dobře definovaná pravidla zaručují konzistenci odpovědí, při zpracování chyb a ověřování.
---
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
Migrace ze staršího souboru .cursorrules
Pokud používáte starý soubor .cursorrules, dobrou zprávou je, že si jej Cursor ponechá
zpětná kompatibilita: starší soubor nadále funguje. Nicméně migrujte na nový systém
.cursor/rules/ nabízí významné výhody z hlediska organizace a flexibility.
Migrační strategie
Migrace nemusí být operace typu všechno nebo nic. Můžete postupovat postupně podle následujících kroků.
- Vytvořte adresář
.cursor/rules/ve vašem projektu - Určete kategorie ve vašem souboru
.cursorrules: obecné konvence, pravidla pro jazyk, testovací vzor, styl odezvy - Extrahujte každou kategorii v souboru
.mdcoddělené s příslušným frontmatrem - Přiřaďte správné typy: Vždy pro univerzální konvence, Auto Attached with globs pro pravidla specifická pro daný jazyk je vyžadován agent pro odborné znalosti
- Hlava že AI respektuje nová pravidla v různých kontextech
- Odstranit soubor
.cursorruleskdyž jste s migrací spokojeni
Konflikt mezi .cursorrules a .cursor/rules/
Pokud jsou přítomny oba, kurzor načte oba soubory .cursorrules že soubory v
.cursor/rules/. To může způsobit duplicitní nebo protichůdné pokyny. Během
migrace, komentujte sekce v .cursorrules jak je rozbalíte do nových souborů
.mdca odeberte starší soubor pouze po dokončení migrace.
Pokročilé strategie pravidel
Pokročilé vzory globusů
Vzory globusů jsou nejmocnějším nástrojem pro přesné zacílení pravidel. Zde jsou vzory užitečnější pro scénáře reálného světa.
# 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
Podmíněná pravidla pro typ souboru
Efektivní strategií je vytvořit pravidla, která se aktivují na základě kontextu souboru. např. můžete mít jiná pravidla pro soubory migrace databáze než pro soubory aplikační logiky, i když jsou oba soubory 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
Skládání pravidel: Pravidla, která se vzájemně doplňují
Pravidla nejsou izolovaná: jsou kombinována v kontextu AI. Efektivní strategie a pravidla designu které se vzájemně doplňují a vytvářejí ucelený systém instrukcí.
Můžete mít například pravidlo Always pro obecné konvence, pravidlo Auto Attached pro
specifikace jazyka a pravidlo Agent Requested pro architektonické vzory. Když pracujete
na úhlové komponentě AI obdrží: obecné konvence (vždy) + úhlová pravidla
(Automaticky připojeno z glob **/*.component.ts) + případně architektonická pravidla
(pokud je agent považuje za relevantní pro daný úkol).
Generovat pravidla automaticky
Cursor obsahuje vestavěný příkaz pro generování pravidel z vaší stávající kódové základny:
/Generate Cursor Rules. Tento příkaz analyzuje váš projekt, identifikuje vzory
opakující se a generuje počáteční sadu pravidel, která zachycují již používané konvence.
Jak používat příkaz
- Otevřete panel chatu kurzoru (
Cmd+L/Ctrl+L) - Typ
/Generate Cursor Rules - AI bude analyzovat vaši kódovou základnu a navrhne sadu pravidel
- Zkontrolujte, upravte a uložte navrhovaná pravidla do adresáře
.cursor/rules/
Tip: Začněte ze stávající kódové základny
Příkaz /Generate Cursor Rules a zvláště užitečné pro stávající projekty, kde
konvence jsou implicitní v kódu, ale nejsou zdokumentovány. Umělá inteligence identifikuje vzory jako
struktura komponent, pojmenování, vzory zpracování chyb a přemění je na explicitní pravidla.
Výsledek považujte za výchozí bod, který je třeba upřesnit, nikoli za definitivní konfiguraci.
Asistovaná generace s výzvou
Pravidla můžete také vytvořit ručně tak, že požádáte AI kurzoru, aby vám pomohla. Poskytněte prosím vzorový soubor která představuje váš ideální styl a požádejte AI, aby extrahovala konvence.
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
Týmový pracovní postup: Sdílená pravidla
Jednou z nejvýznamnějších výhod Project Rules je možnost jejich sdílení přes git. To otevírá obrovské možnosti pro týmové sladění a přijímání nových vývojářů.
Strategie sdílení
Adresář .cursor/rules/ by měl být odevzdán do úložiště jako
.editorconfig, .eslintrc o tsconfig.json. Tato pravidla
stávají se součástí definice projektu a zajišťují, aby každý člen týmu, kdy
použijte kurzor, získejte stejné pokyny 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
Registrace s pravidly
Pravidla projektu mohou výrazně urychlit nástup nových vývojářů. Nový Člen týmu, který naklonuje úložiště a začne používat kurzor, bude mít okamžitě přístup ke všem projektové konvence prostřednictvím AI. Nemusíte číst 50stránkový vstupní dokument: kdykoli napíšete kód, AI automaticky použije správné konvence.
Výhody sdílených pravidel
- Konzistence: Veškerý kód vygenerovaný umělou inteligencí se bez ohledu na to řídí stejnými standardy ze strany vývojáře
- Rychlý nástup: Noví vývojáři vytvářejí vyhovující kód od prvního dne
- Snížení kontroly kódu: Méně komentářů ke stylu a konvencím, více se zaměřte na logiku
- Živá dokumentace: Pravidla jsou spustitelná dokumentace, která se aktualizuje s projektem
- Řízená evoluce: Změny konvencí procházejí kontrolou git jako cokoli jiného změnit
Srovnání s CLAUDE.md a jinými systémy
Systém pravidel kurzoru není jediným způsobem, jak vzdělávat umělou inteligenci o kontextu projektu.
Claude Code používá soubor CLAUDE.md, GitHub Copilot představil
.github/copilot-instructions.md a využití windsurfingu .windsurfrules.
Podívejme se, jak se porovnávají.
Porovnání konfiguračních systémů AI
| Charakteristický | Pravidla kurzoru | CLAUDE.md | Pokyny pro druhého pilota |
|---|---|---|---|
| Více souborů | Ano (.cursor/rules/) | Ano (.claude/ adresář) | Jediný soubor |
| Typy aktivace | 4 typy (vždy, automaticky, agent, ručně) | Vždy aktivní + paměť | Vždy aktivní |
| Vzory zeměkoule | Ano (frontmatter globs) | No | No |
| Sdílení Git | Si | Si | Si |
| Pravidla na uživatelské úrovni | Ano (Nastavení) | Ano (~/.claude/) | Omezený |
| Formát | .mdc (přední strana YAML + MD) | .md (čistý Markdown) | .md (čistý Markdown) |
| Automatické generování | Ano (/Vygenerovat pravidla kurzoru) | Ne (ale /init k dispozici) | No |
Nejvýraznějším rozdílem je systém podmíněná aktivace kurzoru.
Zatímco instrukce CLAUDE.md a Copilot jsou vždy aktivní (spotřebovávají kontext při každé interakci),
Kurzor umožňuje aktivovat pravidla pouze tehdy, když jsou relevantní. V full-stack projektu s frontendem
Angular, backend Python a infrastruktura Terraform, pravidla Angular budou zahrnuta pouze tehdy, když
pracovat na souborech .component.ts, čímž se uloží cenný kontext pro relevantní pokyny.
Další jedinečnou výhodou Cursoru je typ Vyžádán agent. AI může rozhodnout autonomně, která pravidla konzultovat na základě úkolu, čímž se vytvoří znalostní systém na vyžádání, který škálovat bez omezení bez zbytečného konzumování kontextu.
Kompletní praktické příklady
V této části shromažďujeme sbírku pravidel připravených k použití pro běžné scénáře.
Každý příklad je kompletní a lze jej zkopírovat přímo do vašeho adresáře .cursor/rules/.
Pravidlo: Styl CSS s BEM a uživatelskými vlastnostmi
---
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)
Pravidlo: Docker a kontejnerizace
---
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)
Pravidlo: Zabezpečení a ověřování
---
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
Pravidlo: Cross-Luage Error Handling
---
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": "..." } }
```
Osvědčené postupy a běžné chyby
Chybám, kterým je třeba se vyhnout
- Vždy příliš mnoho: Pokud jsou všechna vaše pravidla Vždy, plýtváte kontextem. AI získá tisíce tokenů instrukcí, i když požádáte o přejmenování proměnné
- Pravidla jsou příliš nejasná: „Napsat dobrý kód“ AI nepomůže. Buďte konkrétní: "Funkce s až 4 parametry, každý s explicitním typem"
- Protichůdná pravidla: Pokud jedno pravidlo říká „použít třídy“ a jiné „použít funkce“, AI je zmatená. Zkontrolujte pravidla pro konzistenci
- Nedostatek příkladů: Pravidla bez konkrétních příkladů jsou dodržována způsobem nekonzistentní. Vždy uveďte alespoň jeden pozitivní a jeden negativní příklad
- Neaktualizujte pravidla: Pravidla se musí vyvíjet s projektem. Pokud migrujete z Angular 17 na 19, aktualizujte pravidla, aby odrážela nové vzory
Kontrolní seznam pro efektivní konfiguraci
- Definujte 1-3 Vždy pravidla s univerzálními projektovými konvencemi
- Vytvořte automaticky připojená pravidla pro každý jazyk/rámec v projektu
- Přidat pravidla požadovaná agentem pro odborné znalosti (databáze, nasazení, zabezpečení)
- Připravte ruční pravidla pro opakující se šablony a pracovní postupy
- Vše odevzdat
.cursor/rules/a sdělit to týmu - Zkontrolujte a aktualizujte pravidla při každém sprintu nebo vydání
- USA
/Generate Cursor Rulesjako výchozí bod pro nové projekty
Závěry
Systém pravidel kurzoru představuje kvalitativní skok ve způsobu vývojářů komunikovat s AI. Nejde jen o zadávání pokynů chatbotovi: jde o to kodifikovat týmové konvence do formátu, kterému umělá inteligence porozumí a použije jej automaticky.
Čtyři typy pravidel (vždy, automaticky připojeno, vyžádán agent, ručně) nabízejí úroveň granularity that no other AI tool currently provides. Schopnost aktivovat pravidla podmíněně na základě typu souboru v kombinaci s cílením Agent Requested vytvoří a dynamický znalostní systém, který se přizpůsobuje složitosti projektu bez degradace Výkon AI.
Nejdůležitější rada? Začněte hned, začněte jednoduše. Vytvořte pravidlo Vždy s 10 nejdůležitějšími konvencemi vašeho projektu přidejte pravidlo Auto Attached pro hlavním jazykem a odtud iterovat. Nepotřebujete dokonalé nastavení od prvního dne: pravidla se vyvíjejí s projektem, stejně jako kód.
V dalším článku série prozkoumámeRežim agenta: jak delegovat úkoly komplexů až po AI Cursoru, od refaktorování celých funkcí až po generování testovacích sad kompletní. Pravidla, která jsme nakonfigurovali v tomto článku, se stanou základem agent bude stavět své dílo.
Další zdroje
- Oficiální dokumentace kurzoru: docs.cursor.com/context/rules-for-ai
- Příklad úložiště: github.com/cursor-rules-examples
- Společenství: forum.cursor.com sdílet a objevovat pravidla
- Další článek: Režim agenta – Upravte kódovou základnu pomocí příkazu