Zasady Cursora: Jak pisać pliki .cursor/rules, które naprawdę działają

Zasady Cursora: Jak pisać pliki .cursor/rules, które naprawdę działają

Każdy użytkownik Cursora natrafia na tę samą ścianę. AI generuje kod, który technicznie działa, ale ignoruje konwencje Twojego projektu, używa złych ścieżek importu, przestarzałych wzorców, a komponenty są zorganizowane zupełnie inaczej niż reszta codebase'u. Zasady Cursora naprawiają to, dostarczając AI trwały kontekst dotyczący tego, jak działa Twój projekt.

Czym są zasady Cursora i dlaczego mają znaczenie?

Zasady Cursora to pliki markdown, które działają jako stały systemowy prompt wstrzykiwany przed każdą interakcją z AI – czatem, autouzupełnianiem, generowaniem kodu, wszystkim. Traktuj je jak dokumentację onboardingową dla AI. Zamiast poprawiać te same błędy podczas każdej sesji, piszesz instrukcję raz i ona zostaje.

Stare podejście polegało na użyciu pojedynczego pliku .cursorrules w katalogu głównym projektu. To wciąż działa, ale jest przestarzałe. Obecny system wykorzystuje katalog .cursor/rules/ z indywidualnymi plikami .mdc (Markdown Cursor), z których każdy jest przypisany do konkretnych sytuacji. Jest to znacznie lepsze rozwiązanie, ponieważ nie musisz upychać wszystkich instrukcji w jednym gigantycznym pliku – dzielisz zasady według zagadnień, a Cursor ładuje tylko te, które są istotne dla tego, co robisz w danej chwili.

Jeśli pracowałeś z inżynierią kontekstu dla narzędzi AI, koncepcja jest znajoma: lepszy kontekst wejściowy daje dramatycznie lepsze wyniki. Zasady to inżynieria kontekstu dla całego procesu developmentu.

Konfiguracja pierwszego pliku z zasadami

Utwórz katalog .cursor/rules/ w katalogu głównym projektu:

mkdir -p .cursor/rules

Każda zasada to plik .mdc zawierający frontmatter YAML, a następnie treść w formacie markdown. Oto szkielet:

---
description: "When this rule should apply"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Your instructions go here in plain markdown.

Trzy pola we frontmatterze kontrolują wszystko:

Możesz także tworzyć zasady bezpośrednio w Cursorze – wpisz /create-rule w czacie i opisz, czego chcesz. Jednak ręczne pisanie daje większą kontrolę.

Wyjaśnienie czterech typów zasad

Sposób aktywacji zasady zależy od jej konfiguracji we frontmatterze. Istnieją cztry tryby, a wybór właściwego ma kluczowe znaczenie dla Twojego budżetu okna kontekstowego.

Zawsze stosuj (Always Apply)

---
alwaysApply: true
---

Ładowane do każdego pojedynczego żądania AI. Używaj tego oszczędnie, dla fundamentalnych kwestii projektowych, takich jak deklaracja stosu technologicznego lub krytyczne konwencje obowiązujące wszędzie. Każda zasada „zawsze włączona” zużywa tokeny z każdej interakcji, niezależnie od tego, czy jest istotna.

Automatycznie dołączane (oparte na wzorcach glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Aktywuje się tylko wtedy, gdy edytujesz pliki pasujące do wzorców glob. To jest podstawowy typ zasady. Twoje konwencje komponentów React ładują się, gdy pracujesz nad plikami komponentów, wzorce API ładują się w handlerach tras, a zasady testów – gdy piszesz testy.

Żądane przez agenta (Inteligentne)

---
description: "Database migration patterns using Drizzle ORM"
alwaysApply: false
---

Brak wzorców glob, brak always-apply, tylko opis. Agent Cursora odczytuje opis i decyduje, czy zasada jest istotna dla bieżącego zadania. Jeśli poprosisz go o napisanie migracji, pobierze tę zasadę. Jeśli stylizujesz przycisk, pominie ją. Działa to zaskakująco dobrze dla zasad, które nie mapują się neatly na ścieżki plików.

Ręczne

---
---

Żadne pola we frontmatterze nie są ustawione (lub frontmatter jest pusty). Te zasady aktywują się tylko wtedy, gdy jawnie wspomnisz o nich za pomocą @nazwa-zasady w czacie. Dobre dla rzadko używanych, ale ważnych instrukcji, takich jak listy kontrolne wdrożeń lub przewodniki refaktoryzacyjne, których potrzebujesz tylko okazjonalnie.

Wzorce glob, które naprawdę działają

Wzorce glob określają, które pliki uruchamiają zasady automatycznie dołączane. Jeśli źle je ustawisz, Twoje zasady albo nigdy nie zadziałają, albo będą odpalać się wszędzie. Oto co działa:

# All TypeScript files in src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Only component files
globs: ["**/components/**/*.tsx"]

# Python files, excluding tests
globs: ["**/*.py", "!**/test_*.py"]

# Multiple specific directories
globs: ["src/api/**", "src/services/**"]

Kilka pułapek z rzeczywistego użycia:

• src/* dopasowuje tylko jeden poziom katalogów. Prawie zawsze chcesz użyć src/**/* dla dopasowania rekursywnego.
• *.js nie dopasuje plików .jsx ani .ts. Bądź precyzyjny co do rozszerzeń.
• Wzorce glob muszą być listą YAML. Składnia z nawiasami klamrowymi, taka jak {src,lib}/**/*.ts, może cicho zawieść – trzymaj się oddzielnych wpisów na liście.
• Prefiks ! wyklucza wzorce, co jest przydatne do ignorowania generowanych plików lub legacy code.

Praktyczne przykłady zasad

To moment, w którym teoria spotyka się z rzeczywistością. Są to zasady, które możesz wrzucić do projektu i natychmiast zobaczyć lepsze wyniki od AI.

Globalna zasada bazowa projektu (Zawsze stosuj)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Trzymaj to poniżej 30 linii. Jest ładowane z każdym żądaniem, więc każde słowo kosztuje tokeny.

Zasada komponentu React (Automatycznie dołączane)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Pobieraj dane bezpośrednio w komponencie, bez useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Zasada API Python (Automatycznie dołączane)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Zasada serwisu Go (Automatycznie dołączane)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Zarządzanie podatkiem tokenowym

Oto coś, co pomija większość przewodników po Cursorze: każda napisana zasada kosztuje tokeny. Projekt z 20 zawsze włączonymi zasadami może spalić **ponad 2000 tokenów na żądanie** tylko na instrukcjach, zanim AI nawet spojrzy na Twój kod.

Ma to znaczenie, ponieważ kontekst czatu Cursora wynosi około 20 000 tokenów w standardowym trybie. Jeśli Twoje zasady zjadają 25% tego limitu, tracisz ćwierć „przestrzeni myślowej” AI na Twoje faktyczne pytanie. Zauważysz gorszą jakość outputu, gdy zasady się mnożą, szczególnie w dłuższych rozmowach.

Trzy zasady utrzymują zdrowy budżet tokenów:

**1. Agresywnie używaj zasad automatycznie dołączanych i żądanych przez agenta.** Tylko deklaracja stosu technologicznego projektu powinna być zawsze włączona. Wszystko inne powinno ładować się warunkowo. Ta zasada komponentu React? Nie musi być w kontekście, gdy piszesz migracje SQL.

**2. Pisz zwięźle, nie rozwlekle.** Zastąp „Zdecydowanie zaleca się, aby programiści używali interfejsów TypeScript zamiast aliasów typów przy definiowaniu kontraktów publicznego API” stwierdzeniem „Preferuj `interface` zamiast `type` dla publicznych API”. AI nie potrzebuje perswazji, potrzebuje instrukcji.

**3. Stosuj Zasadę Trzech.** Koduj wzorzec jako zasadę dopiero po tym, jak AI popełni błąd trzy razy. Jeśli Cursor już poprawnie obsługuje Twoje konwencje nazewnictwa bez zasady, pomiń ją. Każda niepotrzebna zasada to zmarnowany kontekst.

Możesz monitorować użycie tokenów na pasku statusu na dole panelu czatu Cursora. Obserwuj, czy zbliża się do 100% – to sygnał, że czas na porządki.

## Organizacja zasad w prawdziwym projekcie

Projekt produkcyjny zazwyczaj wymaga 5–8 plików z zasadami. Oto struktura, która sprawdza się dobrze:

```text
.cursor/rules/
  base.mdc            # Tech stack, always-apply (< 30 lines)
  components.mdc      # React/Vue patterns, glob to component dirs
  api.mdc             # Backend conventions, glob to API dirs
  database.mdc        # ORM patterns, glob to models/migrations
  testing.mdc         # Test conventions, glob to test files
  deployment.mdc      # CI/CD patterns, manual trigger
  personal.mdc        # Your preferences (gitignored)

Zacommituj wszystko do kontroli wersji oprócz personal.mdc. Dzięki temu cały zespół otrzymuje takie samo zachowanie AI, a o to właśnie chodzi. Jak mówi jeden z użytkowników forum Cursora, dobre zasady oznaczają, że „akceptujesz więcej sugestii takimi, jakie są, a output zgodny z Twoimi konwencjami otrzymujesz za pierwszym razem”.

Jeśli pracujesz z innymi narzędziami do kodowania AI obok Cursora, koncepcje przenoszą się bezpośrednio. Claude Code używa CLAUDE.md, GitHub Copilot ma pliki instrukcji, a Windsurf ma własny format, ale zasada nadrzędna jest identyczna.

Jak działa priorytet zasad

Gdy wiele zasad dotyczy tego samego pliku, Cursor stosuje jasną hierarchię:

Zasady zespołowe są dostępne w planach Team i Enterprise. Są ustawiane w dashboardzie Cursora przez administratorów i wymuszane w całej organizacji – indywidualni deweloperzy nie mogą ich wyłączyć.

W obrębie zasad projektu, jeśli dwie zasady dotyczą tego samego pliku i są sprzeczne, zachowanie nie jest ściśle zdefiniowane. W praktyce zasady ładowane później mają tendencję do przejmowania priorytetu. Numerowanie plików (001-base.mdc, 002-components.mdc) zapewnia przewidywalną kolejność.

Częste błędy i jak je naprawić

Po przeanalizowaniu dziesiątek wątków społecznościowych i przetestowaniu zasad w różnych projektach, oto błędy, które najczęściej sprawiają problemy:

Pisanie zbyt ogólnych zasad. „Pisz czysty kod” nic nie mówi AI. „Używaj eksportów nazwanych, nie domyślnych. Strukturyzuj komponenty jako: importy, typy, funkcja, podkomponenty” daje coś, co można wykonać.

Ustawianie wszystkiego jako always-apply. Twoim pierwszym instynktem jest ustawienie alwaysApply: true dla każdej zasady. Oprzyj się temu. Audytuj swoje zasady kwartalnie; jeśli masz więcej niż 2–3 zawsze włączone zasady, prawdopodobnie marnujesz tokeny.

Zapominanie o testowaniu zasad. Po napisaniu zasady otwórz odpowiedni plik i poproś Cursora o wygenerowanie czegoś, co powinno przestrzegać tej zasady. Jeśli tego nie robi, Twój wzorzec glob może być błędny lub instrukcja niewystarczająco jasna.

Niedokumentowanie antywzorców. Poinformowanie AI, co ma robić, to połowa sukcesu. Poinformowanie jej, czego nie robić, to druga połowa. Dołącz sekcję „NIGDY nie rób tego” do każdej zasady z wyraźnymi przykładami złego podejścia.

Ignorowanie zapisu zasad w UI. Znany błąd powoduje znikanie edycji zasad. Jeśli zmiany znikają, całkowicie zamknij Cursor, wybierz „Override” (Nadpisz) w wyskakującym oknie niezapisanych zmian i otwórz ponownie.

Zasady Cursora vs CLAUDE.md vs AGENTS.md

Cursor nie jest jedynym narzędziem używającym plików instrukcji. Oto porównanie formatów dla osób pracujących z wieloma asystentami kodowania AI:

Zaletą Cursora jest granularność. CLAUDE.md i AGENTS.md są prostsze – ładują wszystko zawsze. Cursor pozwala ładować odpowiednie zasady we właściwym czasie, co ma znaczenie, gdy zestaw instrukcji przekracza kilkaset linii.

Aby uzyskać głębszy wgląd w to, jak kontekst kształtuje output AI w tych narzędziach, nasz przewodnik po inżynierii kontekstu omawia zasady mające zastosowanie niezależnie od używanego edytora.

FAQ

Czy .cursorrules jest przestarzałe?

Tak. Pojedynczy plik .cursorrules w katalogu głównym projektu wciąż działa, ale Cursor zaleca migrację do plików .cursor/rules/*.mdc. Nowy format obsługuje wzorce glob, warunkowe ładowanie i lepszą organizację. Migruj, dzieląc monolityczny plik na skupione zasady.

Jakiego rozszerzenia pliku powinienem używać, .mdc czy .md?

Używaj .mdc dla plików zawierających frontmatter YAML (opis, wzorce glob, alwaysApply). Zwykłe pliki .md również działają w katalogu zasad, ale nie obsługują metadanych frontmatteru, które umożliwiają warunkowe ładowanie.

Ile zasad powinien mieć projekt?

Pięć do ośmiu to optymalna liczba dla większości projektów. Jedna zawsze włączona zasada bazowa, trzy do czterech zasad automatycznie dołączanych, ograniczonych typem pliku, oraz jedna lub dwie zasady ręczne do specjalnych zadań. Więcej niż 10 zasad zwykle oznacza, że niektóre można scalić lub usunąć.

Czy zasady Cursora wpływają na autouzupełnianie i uzupełnianie tabulatorem?

Zasady dotyczą czatu i interakcji z agentem. Zasady użytkownika nie dotyczą edycji inline (Cmd/Ctrl+K), a zasady generalnie nie wpływają na sugestie autouzupełniania Cursor Tab. Są najbardziej skuteczne w sesjach czatu i Composera.

Czy mogę udostępniać zasady między wieloma projektami?

Tak, poprzez funkcję Remote Rules w Cursorze. Przejdź do Cursor Settings > Rules, Commands, wybierz „Remote Rule (GitHub)” i wklej URL repozytorium. Zasady synchronizują się automatycznie po aktualizacji źródłowego repo. Alternatywnie, utrzymuj współdzielone repo z zasadami i twórz symlinki do każdego projektu.

Jaka jest maksymalna zalecana długość zasady?

Dokumentacja Cursora sugeruje utrzymywanie indywidualnych zasad poniżej 500 linii. W praktyce celuj w poniżej 100 linii na zasadę. Krótsze zasady są łatwiejsze w utrzymaniu i kosztują mniej tokenów. Jeśli zasada przekracza 150 linii, podziel ją na dwie skupione zasady.

Czy zasady działają ze wszystkimi modelami AI w Cursorze?

Zasady działają z każdym modelem obsługiwanym przez Cursora: Claude, GPT-4o, Gemini i innymi. Zasady są wstrzykiwane jako kontekst systemowy niezależnie od wybranego modelu. Zachowanie modelu może się różnić, ale same zasady są agnostyczne wobec modelu.

Jak debugować zasadę, która nie działa?

Po pierwsze, sprawdź, czy wzorzec glob pasuje do Twojego pliku – otwórz plik i sprawdź, czy zasada pojawia się w panelu kontekstu. Po drugie, przetestuj za pomocą bezpośredniego pytania, które powinno uruchomić zasadę. Po trzecie, spróbuj tymczasowo ustawić alwaysApply: true, aby potwierdzić, że sama treść zasady działa. Jeśli tak, problem leży we wzorcu glob.

Czy powinienem commitować .cursor/rules do gita?

Zdecydowanie tak. Całym celem zasad projektu jest spójność w całym zespole. Commituj wszystko w .cursor/rules/ oprócz plików z preferencjami osobistymi. Dodaj personal.mdc do .gitignore dla indywidualnych ustawień, które nie powinny dotyczyć wszystkich.

Czy mogę używać zasad Cursora wraz z serwerami MCP?

Tak, i uzupełniają się one dobrze. Zasady definiują, jak AI powinno pisać kod, podczas gdy serwery MCP dają AI dostęp do zewnętrznych narzędzi i danych. Zasada może mówić „zawsze używaj naszego wewnętrznego klienta API”, podczas gdy serwer MCP pozwala AI faktycznie odpytywać to API podczas developmentu.

Jeśli funkcje AI są na Twojej mapie drogowej, to nasza specjalność: zespół integracji AI Techsy przeprowadza systemy LLM od prototypu do produkcji. Chcesz drugą opinię na temat swojego stosu? Umów bezpłatną konsultację.

Źródła

• Dokumentacja zasad Cursora
• Trigger.dev, Jak pisać świetne zasady Cursora
• Forum Cursora, Najlepsze praktyki i rozwiązywanie problemów z zasadami MDC
• Peakvance, Przewodnik po zasadach Cursora: Podatek tokenowy
• awesome-cursor-rules-mdc na GitHubie