Pravidla Cursoru: Jak psát soubory .cursor/rules, které skutečně fungují

Pravidla Cursoru: Jak psát soubory .cursor/rules, které skutečně fungují

Každý uživatel Cursoru narazí na stejnou zeď. AI generuje kód, který technicky funguje, ale ignoruje konvence vašeho projektu, používá špatné cesty importů, zastaralé vzory a komponenty strukturované úplně jinak než zbytek vaší codebase. Pravidla Cursoru to řeší tím, že poskytují AI trvalý kontext o tom, jak funguje váš projekt.

Co jsou pravidla Cursoru a proč jsou důležitá?

Pravidla Cursoru jsou markdownové soubory, které fungují jako trvalý systémový prompt vkládaný před každou interakci s AI – chat, automatické doplňování, generování kódu, vše. Představte si je jako onboardingovou dokumentaci pro AI. Místo toho, abyste každou session opravovali stejné chyby, napíšete instrukci jednou a ta zůstane platná.

Starý přístup spočíval v jediném souboru .cursorrules v kořenovém adresáři projektu. To stále funguje, ale je to zastaralé. Současný systém využívá adresář .cursor/rules/ s jednotlivými soubory .mdc (Markdown Cursor), z nichž každý je určen pro specifické situace. Toto je mnohem lepší nastavení, protože nemusíte cpát všechny instrukce do jednoho obrovského souboru; pravidla rozdělujete podle oblasti působnosti a Cursor načítá pouze ta, která jsou relevantní pro to, co právě děláte.

Pokud jste pracovali s inženýrstvím kontextu pro AI nástroje, koncept vám bude známý: lepší vstupní kontext produkuje dramaticky lepší výstup. Pravidla jsou inženýrstvím kontextu pro celý váš vývojový workflow.

Nastavení vašeho prvního souboru s pravidly

Vytvořte adresář .cursor/rules/ v kořenovém adresáři projektu:

mkdir -p .cursor/rules

Každé pravidlo je soubor .mdc s YAML frontmatterem, za kterým následuje obsah v markdownu. Zde je kostra:

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

Your instructions go here in plain markdown.

Tři pole ve frontmatteru řídí vše:

Pravidla můžete vytvářet také přímo v Cursoru – napište /create-rule do chatu a popište, co chcete. Ruční psaní vám však poskytuje větší kontrolu.

Vysvětlení čtyř typů pravidel

Způsob aktivace pravidla závisí na jeho konfiguraci ve frontmatteru. Existují čtyři režimy a výběr toho správného je klíčový pro váš rozpočet kontextového okna.

Vždy aplikovat (Always Apply)

---
alwaysApply: true
---

Načítá se do každého jednotlivého požadavku AI. Používejte to střídmě, pro základní principy celého projektu, jako je deklarace technologického stacku nebo kritické konvence, které platí všude. Každé vždy zapnuté pravidlo spotřebovává tokeny z každé interakce, ať je relevantní, nebo ne.

Automaticky připojené (na základě globů)

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

Aktivuje se pouze tehdy, když upravujete soubory, které odpovídají glob vzorům. Toto je pracovní kůň mezi typy pravidel. Konvence pro komponenty Reactu se načtou, když jste v souborech komponent, vzory API se načtou, když pracujete s routovacími handlery, a pravidla pro testy se načtou při psaní testů.

Vyžádané agentem (Inteligentní)

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

Žádné globs, žádné always-apply, pouze popis. Agent Cursoru přečte popis a rozhodne, zda je pravidlo relevantní pro aktuální úkol. Pokud ho požádáte o napsání migrace, natáhne toto pravidlo. Pokud stylizujete tlačítko, přeskočí ho. To překvapivě dobře funguje pro pravidla, která se nedají snadno mapovat na cesty k souborům.

Manuální

---
---

Žádná pole ve frontmatteru nejsou nastavena (nebo je frontmatter prázdný). Tato pravidla se aktivují pouze tehdy, když je explicitně zmíníte pomocí @nazev-pravidla v chatu. Dobré pro zřídka používané, ale důležité instrukce, jako jsou kontrolní seznamy nasazení nebo průvodce refaktoringem, které potřebujete jen občas.

Glob vzory, které skutečně fungují

Globy určují, které soubory spustí automaticky připojená pravidla. Pokud je nastavíte špatně, vaše pravidla buď nikdy nezafungují, nebo budou spuštěna všude. Zde je to, co funguje:

# 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/**"]

Několik úskalí z reálného používání:

• src/* matchuje pouze jednu úroveň adresáře. Téměř vždy chcete src/**/* pro rekurzivní matchování.
• *.js nebude matchovat soubory .jsx nebo .ts. Buďte explicitní ohledně přípon.
• Globs musí být YAML seznam. Syntaxe se složenými závorkami jako {src,lib}/**/*.ts může selhat tiše, držte se raději samostatných položek seznamu.
• Prefix ! vylučuje vzory, což je užitečné pro ignorování generovaných souborů nebo legacy kódu.

Praktické příklady pravidel

Zde se teorie setkává s realitou. Toto jsou pravidla, která můžete vložit do projektu a okamžitě uvidíte lepší výstupy od AI.

Základní pravidlo pro celý projekt (Vždy aplikovat)

---
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

Udržujte toto pod 30 řádky. Načítá se s každým požadavkem, takže každé slovo stojí tokeny.

Pravidlo pro React komponenty (Automaticky připojené)

---
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
// Fetch přímo v komponentě, žádné 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

### Pravidlo pro Python API (Automaticky připojené)

```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"}

### Pravidlo pro Go služby (Automaticky připojené)

```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
}

## Správa tokenové daně

Zde je něco, co většina průvodců Cursoru přeskočí: každé pravidlo, které napíšete, stojí tokeny. Projekt s 20 vždy zapnutými pravidly může spálit **2 000+ tokenů na požadavek** jen na instrukce, než se AI vůbec podívá na váš kód.

To je důležité, protože kontext chatu v Cursoru má v standardním režimu zhruba 20 000 tokenů. Pokud vaše pravidla snědí 25 % z toho, přišli jste o čtvrtinu „myšlenkového prostoru“ AI pro vaši skutečnou otázku. Všimnete si horší kvality výstupů, jak se pravidla hromadí, zejména v delších konverzacích.

Tři principy udržují váš tokenový rozpočet zdravý:

**1. Agresivně používejte automaticky připojená a agentem vyžádaná pravidla.** Pouze deklarace technologického stacku by měla být vždy zapnutá. Všechno ostatní by se mělo načítat podmíněně. To pravidlo pro React komponenty? Nepotřebuje být v kontextu, když píšete SQL migrace.

**2. Pište hutně, ne upovídaně.** Nahraďte „Důrazně se doporučuje, aby vývojáři používali TypeScript rozhraní místo aliasů typů při definování veřejných API kontraktů“ za „Preferujte `interface` před `type` pro veřejná API.“ AI nepotřebuje přesvědčování, potřebuje instrukce.

**3. Aplikujte pravidlo tří.** Kodifikujte vzor jako pravidlo až poté, co ho AI třikrát pokazí. Pokud Cursor již zvládá vaše konvence pojmenování správně bez pravidla, pravidlo vynechejte. Každé zbytečné pravidlo je plýtvání kontextem.

Využití tokenů můžete sledovat ve stavovém řádku v dolní části chatového panelu Cursoru. Sledujte, zda se blíží ke 100 %, to je signál k prořezání.

## Organizace pravidel pro reálný projekt

Produkční projekt obvykle potřebuje 5–8 souborů s pravidly. Zde je struktura, která dobře funguje:

```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)

Commitněte vše do version controlu kromě personal.mdc. Tím zajistíte, že celý tým dostane stejné chování AI, což je celý smysl. Jak říká jeden uživatel fóra Cursoru, dobrá pravidla znamenají, že „přijímáte více návrhů tak, jak jsou, s výstupem odpovídajícím vašim konvencím na první pokus.“

Pokud pracujete s jinými AI nástroji pro kódování vedle Cursoru, koncepty se přímo přenášejí. Claude Code používá CLAUDE.md, GitHub Copilot má instrukční soubory a Windsurf má svůj vlastní formát, ale underlying princip je identický.

Jak funguje priorita pravidel

Když se na stejný soubor vztahuje více pravidel, Cursor dodržuje jasnou hierarchii:

Týmová pravidla jsou dostupná na plánech Team a Enterprise. Jsou nastavena v dashboardu Cursoru administrátory a vynucována v celé organizaci, jednotliví vývojáři je nemohou vypnout.

V rámci projektových pravidel, pokud se dvě pravidla vztahují na stejný soubor a jsou v konfliktu, chování není striktně definováno. V praxi mají tendenci mít přednost pravidla načtená později. Číslování vašich souborů (001-base.mdc, 002-components.mdc) vám poskytuje předvídatelné pořadí.

Běžné chyby a jak je opravit

Po přečtení desítek komunitních vláken a testování pravidel napříč projekty jsou toto chyby, které lidem nejčastěji dělají problémy:

Psaní příliš vágních pravidel. „Pište čistý kód“ AI nic neřekne. „Používejte named exports, ne default exports. Strukturovat komponenty jako: importy, typy, funkce, sub-komponenty“ jí dá něco akčního.

Nastavení everything na always-apply. Vaším prvním instinktem je nastavit alwaysApply: true na každém pravidle. Odolejte tomu. Auditujte svá pravidla čtvrtletně, pokud máte více než 2–3 vždy zapnutá pravidla, pravděpodobně plýtváte tokeny.

Zapomenutí testovat pravidla. Po napsání pravidla otevřete relevantní soubor a požádejte Cursor, aby vygeneroval něco, co by mělo následovat toto pravidlo. Pokud tak neučiní, váš glob vzor může být špatný nebo instrukce není dostatečně jasná.

Nedokumentování anti-vzorů. Říkat AI, co má dělat, je polovina práce. Říkat jí, co nedělat, je ta druhá polovina. Do každého pravidla zahrňte sekci „NIKDY nedělejte toto“ s explicitními příklady špatného přístupu.

Ignorování ukládání pravidel v UI. Známá chyba způsobuje, že úpravy pravidel zmizí. Pokud změny zmizí, zcela zavřete Cursor, v popupu neuložených změn zvolte „Override“ a znovu otevřete.

Pravidla Cursoru vs CLAUDE.md vs AGENTS.md

Cursor není jediný nástroj, který používá instrukční soubory. Zde je porovnání formátů pro každého, kdo pracuje napříč více AI asistenty pro kódování:

Výhodou Cursoru je granularita. CLAUDE.md a AGENTS.md jsou jednodušší, načítají všechno vždy. Cursor vám umožňuje načítat správná pravidla ve správný čas, což je důležité, jakmile vaše sada instrukcí přesáhne několik stovek řádků.

Pro hlubší pohled na to, jak kontext tvaruje výstup AI napříč těmito nástroji, náš průvodce inženýrstvím kontextu rozebírá principy, které platí bez ohledu na to, který editor používáte.

FAQ

Je .cursorrules zastaralý?

Ano. Jediný soubor .cursorrules v kořenovém adresáři projektu stále funguje, ale Cursor doporučuje migraci na soubory .cursor/rules/*.mdc. Nový formát podporuje glob vzory, podmíněné načítání a lepší organizaci. Migrujte rozdělením vašeho monolitického souboru na cílená pravidla.

Jakou příponu souboru bych měl použít, .mdc nebo .md?

Použijte .mdc pro soubory, které obsahují YAML frontmatter (description, globs, alwaysApply). Plain .md soubory také fungují v adresáři rules, ale nepodporují metadata frontmatteru, která umožňují podmíněné načítání.

Kolik pravidel by měl projekt mít?

Pět až osm je ideální počet pro většinu projektů. Jedno vždy zapnuté základní pravidlo, tři až čtyři automaticky připojená pravidla scopeovaná podle typu souboru a jedno nebo dvě manuální pravidla pro speciální úkoly. Více než 10 pravidel obvykle znamená, že některá lze konsolidovat nebo odstranit.

Ovlivňují pravidla Cursoru autocomplete a tab completion?

Pravidla se aplikují na chat a interakce s agenty. Uživatelská pravidla se neaplikují na inline editace (Cmd/Ctrl+K) a pravidla obecně neovlivňují návrhy Cursor Tab autocomplete. Jsou nejefektivnější v chatu a sessions Composeru.

Mohu sdílet pravidla napříč více projekty?

Ano, prostřednictvím funkce Remote Rules v Cursoru. Přejděte na Cursor Settings > Rules, Commands, vyberte „Remote Rule (GitHub)“ a vložte URL repozitáře. Pravidla se automaticky synchronizují při aktualizaci zdrojového repo. Alternativně udržujte shared rules repo a symlinkujte ho do každého projektu.

Jaká je maximální doporučená délka pravidla?

Dokumentace Cursoru navrhuje udržovat jednotlivá pravidla pod 500 řádky. V praxi cílte na méně než 100 řádků na pravidlo. Kratší pravidla se snáze udržují a stojí méně tokenů. Pokud pravidlo přesáhne 150 řádků, rozdělte ho na dvě cílená pravidla.

Fungují pravidla se všemi AI modely v Cursoru?

Pravidla fungují s každým modelem, který Cursor podporuje – Claude, GPT-4o, Gemini a další. Pravidla jsou injektována jako kontext na systémové úrovni bez ohledu na to, který model jste vybrali. Chování modelu se může lišit, ale samotná pravidla jsou model-agnostická.

Jak debugovat pravidlo, které nefunguje?

Nejprve ověřte, že glob vzor matchuje váš soubor – otevřete soubor a zkontrolujte, zda se pravidlo objeví v panelu kontextu. Za druhé, otestujte přímou otázkou, která by měla pravidlo spustit. Za třetí, zkuste dočasně nastavit alwaysApply: true, abyste potvrdili, že samotný obsah pravidla funguje. Pokud ano, problém je ve vašem glob vzoru.

Měl bych commitovat .cursor/rules do git?

Rozhodně. Celý smysl projektových pravidel je konzistence napříč týmem. Commitněte vše v .cursor/rules/ kromě souborů s osobními preferencemi. Přidejte personal.mdc do .gitignore pro individuální nastavení, která by se neměla aplikovat na všechny.

Mohu používat pravidla Cursoru alongside MCP serverů?

Ano, a vzájemně se dobře doplňují. Pravidla definují, jak by AI měla psát kód, zatímco MCP servery dávají AI přístup k externím nástrojům a datům. Pravidlo může říkat „vždy používej náš interní API klient“, zatímco MCP server umožňuje AI skutečně dotazovat toto API během vývoje.

Pokud jsou AI funkce na vašem roadmapě, to je naše specialita: tým pro AI integrace společnosti Techsy převádí LLM systémy z prototypu do produkce. Chcete druhý názor na váš stack? Získejte bezplatnou konzultaci.

Zdroje

• Dokumentace pravidel Cursoru
• Trigger.dev, Jak psát skvělá pravidla pro Cursor
• Fórum Cursoru, Osvědčené postupy pro MDC pravidla a troubleshooting
• Peakvance, Průvodce pravidly Cursoru: Tokenová daň
• awesome-cursor-rules-mdc na GitHubu