Cursor Rules -opas: Näin konfiguroit Cursorin projektiisi

Jos käytät Cursoria ilman rules-tiedostoja, jätät puolet sen tehosta käyttämättä.

Cursor Rules on kuin briiffi, jonka annat tekoälyavustajallesi: mitä teknologioita käytät, miten nimeät asioita, mitä konventioita noudatat ja mitä ei saa tehdä. Ilman sääntöjä Cursor arvaa -- ja arvaa usein väärin.

Tämä opas näyttää, miten Cursor 3:n rules-järjestelmä toimii ja miten rakennat tehokkaat säännöt omaan projektiisi.

Miten rules-järjestelmä toimii?

Cursor 3 käyttää .cursor/rules/-kansiota, jonne tallennat sääntötiedostoja .mdc-muodossa (MDC = Markdown Config). Jokainen tiedosto sisältää frontmatterin ja Markdown-muotoisen sääntösisällön.

Sääntöjä on kolmenlaisia:

1. Always Apply -- latautuu aina

Nämä säännöt latautuvat jokaiseen AI-keskusteluun automaattisesti. Käytä niitä yleisiin projektiohjeisiin.

---
description: Projektin yleisohjeet
alwaysApply: true
---

# Projektin säännöt

- Kieli: TypeScript, strict mode
- Framework: Next.js 15 (App Router)
- Tyylitys: Tailwind CSS v4
- Testaus: Vitest + Testing Library
- Käytä aina funktionaalisia komponentteja
- Ei class-komponentteja

2. Auto-Attached -- latautuu tiedostotyypin mukaan

Nämä säännöt aktivoituvat automaattisesti, kun työskentelet tiettyjen tiedostojen kanssa. Glob-pattern määrittää, milloin sääntö latautuu.

---
description: React-komponenttien säännöt
globs: ["**/*.tsx", "**/*.jsx"]
---

# React-komponentit

- PascalCase tiedostonimet (esim. UserProfile.tsx)
- Props-tyyppi aina erillisellä interfacella
- Käytä named exportia, ei default exportia
- Hooks-tiedostot: use-prefix (useAuth.ts)

3. Agent-Requested -- AI päättää milloin käyttää

Nämä säännöt eivät lataudu automaattisesti, mutta AI voi päättää käyttää niitä description-kentän perusteella.

---
description: Tietokantamigraatioiden säännöt Prismalle
---

# Prisma-migraatiot

- Aja aina `npx prisma generate` muutosten jälkeen
- Nimeä migraatiot kuvaavasti
- Älä muokkaa olemassa olevia migraatiotiedostoja

Kansiorakenne

Tyypillinen rules-kansio näyttää tältä:

.cursor/
  rules/
    project.mdc          # Yleisohjeet (alwaysApply)
    react.mdc            # React-säännöt (auto-attached *.tsx)
    api.mdc              # API-säännöt (auto-attached **/api/**)
    database.mdc         # Tietokantasäännöt (agent-requested)
    testing.mdc          # Testaussäännöt (auto-attached *.test.*)
    styling.mdc          # Tyylityssäännöt (auto-attached *.css)

Käytännön esimerkit: Next.js + React + TypeScript

Projektisääntö (alwaysApply)

---
description: Vibekoodaus-projektin yleisohjeet
alwaysApply: true
---

# Projekti: SaaS-sovellus

Tech stack:
- Next.js 15 (App Router, ei Pages Router)
- React 19
- TypeScript 5 (strict)
- Tailwind CSS v4
- Prisma + PostgreSQL
- Zod validointiin

## Konventiot

- Tiedostonimet: kebab-case (user-profile.tsx -> EI, UserProfile.tsx -> KYLLÄ komponenteille)
- Muuttujat ja funktiot: camelCase
- Tyypit ja interfacet: PascalCase
- Vakiot: UPPER_SNAKE_CASE
- Käytä path aliaseja: @/components, @/lib, @/app

## Kiellot

- ÄLÄ käytä any-tyyppiä
- ÄLÄ käytä var-avainsanaa
- ÄLÄ tee suoria DOM-manipulaatioita
- ÄLÄ käytä inline-tyylejä (käytä Tailwindia)
- ÄLÄ käytä require() -- käytä ES modules importia

API-reittien sääntö (auto-attached)

---
description: Next.js API-reittien säännöt
globs: ["src/app/api/**/*.ts"]
---

# API-reitit

- Käytä Route Handler -syntaksia (GET, POST, PUT, DELETE)
- Validoi request body Zodilla
- Palauta aina tyypitetty NextResponse
- Käsittele virheet try-catch-lohkolla
- Palauta sopivat HTTP-statuskoodit
- Logita virheet palvelinpuolella

## Esimerkki

\`\`\`typescript
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const schema = z.object({ name: z.string().min(1) });

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const data = schema.parse(body);
    // ... logiikka
    return NextResponse.json({ success: true }, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ error: error.errors }, { status: 400 });
    }
    console.error('API error:', error);
    return NextResponse.json({ error: 'Internal error' }, { status: 500 });
  }
}
\`\`\`

Testaussääntö (auto-attached)

---
description: Testauksen säännöt
globs: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
---

# Testaus

- Käytä Vitestiä (ei Jest)
- React-komponentit: @testing-library/react
- Testaa käyttäjän näkökulmasta, ei implementaatiota
- Nimeä testit suomeksi: describe('Kirjautuminen', ...)
- Mockkaa ulkoiset riippuvuudet, älä tietokantaa suoraan

Projektisäännöt vs. käyttäjäsäännöt

| | Projektisäännöt | Käyttäjäsäännöt | |---|---|---| | Sijainti | .cursor/rules/ | Settings > General > Rules | | Jakaminen | Git-repon kautta tiimille | Vain sinulle | | Prioriteetti | Korkeampi | Matalampi | | Käyttö | Projektikohtaiset konventiot | Henkilökohtaiset mieltymykset |

Käyttäjäsäännöt ovat hyviä asioille, jotka haluat kaikkiin projekteihin:

- Vastaa aina suomeksi
- Selitä muutokset ennen koodin kirjoittamista
- Käytä selkeitä muuttujanimiä
- Kommentoi monimutkaiset loogikat

Projektisäännöt ovat spesifejä tälle projektille: teknologiapino, konventiot, arkkitehtuuripäätökset.

Cursor Rules vs. CLAUDE.md

Jos olet käyttänyt Claude Codea, tunnet CLAUDE.md-tiedoston. Cursor Rules tekee saman asian, mutta eri tavalla:

| | CLAUDE.md | Cursor Rules | |---|---|---| | Muoto | Yksi Markdown-tiedosto | Useita .mdc-tiedostoja | | Lataus | Aina kokonaan | Valikoivasti (globs, alwaysApply) | | Kontekstin käyttö | Vie aina tilaa kontekstista | Lataa vain tarvittavat säännöt | | Organisointi | Yksi pitkä tiedosto | Modulaariset teemat |

Cursor Rules -lähestymistapa on tehokkaampi kontekstin kannalta. Kun työskentelet React-komponentin kanssa, latautuvat vain React-säännöt. Tietokantasäännöt eivät vie turhaan konteksti-ikkunan tilaa.

Toisaalta CLAUDE.md on yksinkertaisempi -- yksi tiedosto, ei mitään konfiguraatiota. Jos projektisi on pieni, CLAUDE.md-tyylinen lähestymistapa voi riittää.

Vinkkejä tehokkaisiin sääntöihin

1. Pidä säännöt lyhyinä. Jokainen sääntö vie konteksti-ikkunan tilaa. Kirjoita vain oleelliset asiat.

2. Käytä esimerkkejä. "Nimeä komponentit PascalCasella" on hyvä. Esimerkki UserProfile.tsx on parempi.

3. Kerro miksi, ei vain mitä. "Käytä Server Componenteja oletuksena, koska ne pienentävät bundle-kokoa" on parempi kuin pelkkä "Käytä Server Componenteja".

4. Päivitä säännöllisesti. Kun projektin konventiot muuttuvat, päivitä säännöt. Vanhentuneet säännöt ovat pahempia kuin ei sääntöjä.

5. Committaa repoon. Lisää .cursor/rules/ versionhallintaan, niin koko tiimi hyötyy samoista säännöistä.

Nopea aloitus

Jos haluat aloittaa heti, luo nämä kaksi tiedostoa:

.cursor/rules/project.mdc -- projektin yleisohjeet:

---
description: Projektin yleisohjeet
alwaysApply: true
---

[Kirjoita tähän teknologiapinosi, konventiosi ja kiellot]

.cursor/rules/components.mdc -- komponenttisäännöt:

---
description: React-komponenttien säännöt
globs: ["src/components/**/*.tsx"]
---

[Kirjoita tähän komponenttien nimeäminen, rakenne ja patternt]

Aloita näistä ja lisää sääntöjä sitä mukaa, kun huomaat AI:n tekevän vääriä oletuksia.

Yhteenveto

Cursor Rules on yksinkertainen mutta tehokas järjestelmä, jolla ohjaat Cursorin AI-avustajaa tuottamaan juuri sellaista koodia kuin projektisi vaatii. Modulaarinen rakenne pitää säännöt siistinä ja kontekstin tehokkaana.

Kolme asiaa muistiin:

1. AlwaysApply projektin yleisohjeille -- teknologiat, konventiot, kiellot
2. Auto-Attached tiedostotyyppikohtaisille säännöille -- React, API, testit
3. Committaa repoon -- koko tiimi hyötyy

Lue myös: Cursor-opas ja Cursorin pikanäppäimet.