Cursor-säännöt: Kuinka kirjoittaa .cursor/rules-tiedostoja, jotka todella toimivat

Cursor-säännöt: Kuinka kirjoittaa .cursor/rules-tiedostoja, jotka todella toimivat

Jokainen Cursorin käyttäjä törmää samaan seinään. Tekoäly tuottaa koodia, joka teknisesti toimii, mutta ignoroii projektisi käytänteitä, käyttää vääriä import-polkuja, vanhentuneita malleja tai rakentaa komponentteja täysin eri tavalla kuin muu koodikanta. Cursor-säännöt korjaavat tämän antamalla tekoälylle pysyvän kontekstin siitä, miten sinun projektisi toimii.

Mitä ovat Cursor-säännöt ja miksi ne ovat tärkeitä?

Cursor-säännöt ovat markdown-tiedostoja, jotka toimivat pysyvänä järjestelmäkehotteena, joka syötetään ennen jokaista tekoälyn vuorovaikutusta: keskustelua, automaattista täydennystä, koodin generointia – kaikkea. Ajattele niitä tekoälyn perehdytysdokumentteina. Sen sijaan, että korjaisit samoja virheitä jokaisessa sessiossa, kirjoitat ohjeen kerran, ja se jää voimaan.

Vanha lähestymistapa oli yksittäinen .cursorrules-tiedosto projektin juuressa. Se toimii edelleen, mutta se on vanhentunut. Nykyinen järjestelmä käyttää .cursor/rules/-hakemistoa, jossa on yksittäisiä .mdc (Markdown Cursor) -tiedostoja, joista kukin on rajattu tiettyihin tilanteisiin. Tämä on paljon parempi asetelma, koska et ahdä kaikkia ohjeita yhteen jättimäiseen tiedostoon, vaan jaat säännöt aihealueittain, ja Cursor lataa vain ne, jotka ovat relevantteja senhetkisen tekemisesi kannalta.

Jos olet työskennellyt tekoälytyökalujen kontekstitekniikan parissa, konsepti on tuttu: parempi syötekonteksti tuottaa huomattavasti parempaa tulosta. Säännöt ovat kontekstitekniikkaa koko kehitystyönkulkuasi varten.

Ensimmäisen sääntötiedoston luominen

Luo .cursor/rules/-hakemisto projektisi juureen:

mkdir -p .cursor/rules

Jokainen sääntö on .mdc-tiedosto, jossa on YAML-etumateriaali, jota seuraa markdown-sisältö. Tässä on runko:

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

Your instructions go here in plain markdown.

Kolme etumateriaalikenttää ohjaavat kaikkea:

Voit myös luoda sääntöjä suoraan Cursorissa kirjoittamalla chatissa /create-rule ja kuvailemalla, mitä haluat. Mutta niiden kirjoittaminen käsin antaa sinulle enemmän kontrollia.

Neljä sääntötyyppiä selitettynä

Se, miten sääntö aktivoituu, riippuu sen etumateriaalin asetuksista. Neljä tilaa, ja oikean valitseminen on tärkeää kontekstiikkunan budjetin kannalta.

Always Apply (Aina sovellettava)

---
alwaysApply: true
---

Ladataan jokaiseen tekoälypyyntöön. Käytä tätä säästeliäästi projektin laajuisiin perusasioihin, kuten teknologiapisteen määrittelyyn tai kriittisiin käytänteisiin, jotka pätevät kaikkialla. Jokainen aina päällä oleva sääntö syö tokeneita jokaisesta vuorovaikutuksesta, olipa se relevantti tai ei.

Auto-Attached (Glob-pohjainen)

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

Aktivoituu vain, kun muokkaat tiedostoja, jotka vastaavat glob-kuvioita. Tämä on työhevosena toimiva sääntötyyppi. React-komponenttien käytänteesi latautuvat, kun olet komponenttitiedostoissa, API-mallisi latautuvat, kun olet reittinkäsittelijöissä, ja testisääntösi latautuvat, kun kirjoitat testejä.

Agent-Requested (Älykäs)

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

Ei globeja, ei always-apply-asetusta, vain kuvaus. Cursorin agentti lukee kuvauksen ja päättää, onko sääntö relevantti nykyiselle tehtävälle. Jos pyydät sitä kirjoittamaan migraation, se ottaa tämän säännön käyttöön. Jos tyylittelet painiketta, se ohittaa sen. Tämä toimii yllättävän hyvin säännöille, jotka eivät mapituudu siististi tiedostopoluihin.

Manual (Manuaalinen)

---
---

Etumateriaalikenttiä ei ole asetettu (tai tyhjä etumateriaali). Nämä säännöt aktivoituvat vain, kun mainitset ne nimenomaisesti chatissa muodossa @säännön-nimi. Hyvä harvoin käytetyille mutta tärkeille ohjeille, kuten deployment-tarkistuslistoille tai refaktorointioppaille, joita tarvitset vain satunnaisesti.

Glob-kuviot, jotka todella toimivat

Globit määrittävät, mitkä tiedostot käynnistävät automaattisesti liitetyt säännöt. Jos saat ne väärin, sääntösi joko eivät koskaan laukea tai laukeavat kaikkialla. Tässä toimivat mallit:

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

Muutama sudenkuoppa käytännön kokemuksesta:

• src/* vastaa vain yhtä hakemistotasoa. Haluat lähes aina src/**/* rekursiivista vastaavuutta varten.
• *.js ei vastaa .jsx- tai .ts-tiedostoja. Ole eksplisiittinen tiedostopäätteiden suhteen.
• Globien on oltava YAML-lista. Aaltosuljesyntaksi kuten {src,lib}/**/*.ts voi epäonnistua hiljaa, pidä kiinni erillisistä listamerkinnöistä.
• !-etuliite sulkee pois kuvioita, mikä on hyödyllistä generoitujen tiedostojen tai legacy-koodin ignoroinnissa.

Käytännön sääntöesimerkkejä

Tässä teoria kohtaa todellisuuden. Nämä ovat sääntöjä, jotka voit pudottaa projektiin ja näet välittömästi parempaa tekoälyn tuotosta.

Projektin laajuinen perussääntö (Always Apply)

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

Pidä tämä alle 30 rivin pituisena. Se ladataan jokaisen pyynnön mukana, joten jokainen sana maksaa tokeneita.

React-komponenttisääntö (Auto-Attached)

---
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
// Hae suoraan komponentissa, ei useEffectia
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

### Python API -sääntö (Auto-Attached)

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

### Go Service -sääntö (Auto-Attached)

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

## Token-veron hallinta

Tässä on jotain, mitä useimmat Cursor-oppaat jättävät huomioimatta: jokainen kirjoittamasi sääntö maksaa tokeneita. Projekti, jossa on 20 aina päällä olevaa sääntöä, voi polttaa **yli 2 000 tokenia per pyyntö** pelkästään ohjeisiin, ennen kuin tekoäly edes katsoo koodiasi.

Sillä on merkitystä, koska Cursorin chat-konteksti on noin 20 000 tokenia vakiotilassa. Jos sääntösi syövät 25 % siitä, olet menettänyt neljännesosan tekoälyn "ajattelutilasta" varsinaista kysymystäsi varten. Huomaat heikompaa tuloksen laatua sääntöjen kasautuessa, erityisesti pidemmissä keskusteluissa.

Kolme periaatetta pitävät token-budjettisi kunnossa:

**1. Käytä auto-attached- ja agent-requested-sääntöjä aggressiivisesti.** Vain projektin teknologiapisteen määrittelyn tulisi olla aina päällä. Kaiken muun tulisi latautua ehdollisesti. Tuota React-komponenttisääntöä? Sen ei tarvitse olla kontektissa, kun kirjoitat SQL-migraatioita.

**2. Kirjoita tiiviisti, ei monisanaisesti.** Korvaa "On erittäin suositeltavaa, että kehittäjät käyttävät TypeScript-interfaceja eikä type-aliaksia määritellessään julkisia API-sopimuksia" muotoon "Suosi `interface` yli `type`:n julkisissa API:ssa." Tekoäly ei tarvitse vakuuttelua, se tarvitsee ohjeita.

**3. Sovella kolmen sääntöä.** Kodifioi malli säännöksi vasta sen jälkeen, kun tekoäly saa sen väärin kolme kertaa. Jos Cursor hoitaa nimeämiskäytänteesi oikein ilman sääntöä, jätä sääntö väliin. Jokainen tarpeeton sääntö on hukattua kontekstia.

Voit seurata tokenien käyttöä Cursorin chat-paneelin alareunan tilapalkissa. Varo, kun se lähestyy 100 %, se on signaalisi karsia sääntöjä.

## Sääntöjen organisointi oikeaan projektiin

Tuotantoprojekti tarvitsee tyypillisesti 5–8 sääntötiedostoa. Tässä on rakenne, joka toimii hyvin:

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

Commitoi kaikki versiohallintaan paitsi personal.mdc. Näin koko tiimisi saa saman tekoälykäyttäytymisen, mikä on koko pointti. Kuten yksi Cursor-forumin käyttäjä sanoo, hyvät säännöt tarkoittavat, että "hyväksyt enemmän ehdotuksia sellaisenaan, ja tuotos vastaa käytänteitäsi ensimmäisellä yrityksellä."

Jos työskentelet muiden tekoälykoodaustyökalujen kanssa Cursorin rinnalla, konseptit siirtyvät suoraan. Claude Code käyttää CLAUDE.md-tiedostoa, GitHub Copilotilla on ohjetiedostoja, ja Windsurfilla on oma muotonsa, mutta taustalla oleva periaate on identtinen.

Miten sääntöjen prioriteetti toimii

Kun useampi sääntö koskee samaa tiedostoa, Cursor noudattaa selkeää hierarkiaa:

Tiimin säännöt ovat saatavilla Team- ja Enterprise-suunnitelmissa. Ne asetetaan Cursorin dashboardissa ylläpitäjien toimesta ja niitä valvotaan koko organisaatiossa, yksittäiset kehittäjät eivät voi kytkeä niitä pois päältä.

Projektin sääntöjen sisällä, jos kaksi sääntöä koskee samaa tiedostoa ja ovat ristiriidassa, käyttäytyminen ei ole tiukasti määritelty. Käytännössä myöhemmin ladatut säännöt tendevoivat saada etusijan. Tiedostojen numerointi (001-base.mdc, 002-components.mdc) antaa sinulle ennustettavan järjestyksen.

Yleiset virheet ja niiden korjaaminen

Luettuani kymmeniä yhteisön ketjuja ja testattuani sääntöjä projekteissa, nämä ovat virheitä, jotka kompastuttavat ihmisiä useimmin:

Liian epämääräisten sääntöjen kirjoittaminen. "Kirjoita siistiä koodia" ei kerro tekoälylle mitään. "Käytä nimettyjä exportteja, ei default exportteja. Rakenna komponentit seuraavasti: importit, tyypit, funktio, alikomponentit" antaa sille toimittavaa ohjetta.

Kaiken asettaminen always-apply-tilaan. Ensimmäinen vaistosi on asettaa alwaysApply: true jokaiseen sääntöön. Vastusta sitä. Auditoi sääntösi neljännesvuosittain, jos sinulla on enemmän kuin 2–3 aina päällä olevaa sääntöä, hukkaat todennäköisesti tokeneita.

Sääntöjen testaamisen unohtaminen. Säännön kirjoittamisen jälkeen avaa relevantti tiedosto ja pyydä Cursoria generoimaan jotain, jonka pitäisi noudattaa sääntöä. Jos se ei tee niin, glob-kuviosi saattaa olla väärä, tai ohje ei ole tarpeeksi selkeä.

Anti-patternien dokumentoimatta jättäminen. Tekoälyn kertominen siitä, mitä tehdä, on puoli työtä. Toinen puolisko on kertoa sille, mitä ei pidä tehdä. Sisällytä jokaiseen sääntöön "ÄLÄ koskaan tee näin" -osio, jossa on eksplisiittisiä esimerkkejä väärästä lähestymistavasta.

UI:n sääntötallennusten ignorointi. Tunnettu bugi saa sääntömuokkaukset katoamaan. Jos muutokset katoavat, sulje Cursor kokonaan, valitse "Override" tallentamattomien muutosten ponnahdusikkunassa ja avaa uudelleen.

Cursor-säännöt vs CLAUDE.md vs AGENTS.md

Cursor ei ole ainoa työkalu, joka käyttää ohjetiedostoja. Tässä on vertailu muodoista niille, jotka työskentelevät useiden tekoälykoodausassistenttien parissa:

Cursorin etu on granulaarisuus. CLAUDE.md ja AGENTS.md ovat yksinkertaisempia, ne lataavat kaiken aina. Cursor antaa sinun ladata oikeat säännöt oikeaan aikaan, mikä on tärkeää, kun ohjesarjasi kasvaa yli muutaman sadan rivin.

Syvällisempää katsausta siihen, miten konteksti muokkaa tekoälyn tuotosta näissä työkaluissa, kontekstitekniikkaoppaamme purkaa periaatteet, jotka pätevät riippumatta siitä, mitä editoria käytät.

FAQ

Onko .cursorrules vanhentunut?

Kyllä. Yksittäinen .cursorrules-tiedosto projektin juuressa toimii edelleen, mutta Cursor suosittelee siirtymistä .cursor/rules/*.mdc-tiedostoihin. Uusi muoto tukee glob-kuvioita, ehdollista latausta ja parempaa organisointia. Migroi jakamalla monoliittinen tiedostosi fokusoituihin sääntöihin.

Mitä tiedostopäätettä minun pitäisi käyttää, .mdc vai .md?

Käytä .mdc:tä tiedostoille, jotka sisältävät YAML-etumateriaalia (description, globs, alwaysApply). Tavalliset .md-tiedostot toimivat myös sääntöhakemistossa, mutta ne eivät tue etumateriaalin metadataa, joka mahdollistaa ehdollisen latauksen.

Kuinka monta sääntöä projektissa pitäisi olla?

Viisi–kahdeksan on makea piste useimmille projekteille. Yksi aina päällä oleva perussääntö, kolme–neljä auto-attached-sääntöä rajattuna tiedostotyypin mukaan ja yksi tai kaksi manuaalista sääntöä erikoistehtäviä varten. Enemmän kuin 10 sääntöä tarkoittaa yleensä, että joitakin voidaan yhdistää tai poistaa.

Vaikuttavatko Cursor-säännöt automaattiseen täydennykseen ja tab-täydennykseen?

Säännöt vaikuttavat chattiin ja agenttivuorovaikutuksiin. Käyttäjän säännöt eivät vaikuta inline-muokkauksiin (Cmd/Ctrl+K), ja säännöt eivät yleensä vaikuta Cursor Tab -automaattisen täydennyksen ehdotuksiin. Ne ovat tehokkaimpia chatissa ja Composer-sessioissa.

Voinko jakaa sääntöjä useiden projektien kesken?

Kyllä, Cursorin Remote Rules -ominaisuuden kautta. Siirry kohtaan Cursor Settings > Rules, Commands, valitse "Remote Rule (GitHub)" ja liitä repositoryn URL. Säännöt synkronoituvat automaattisesti, kun lähdekoodivarasto päivittyy. Vaihtoehtoisesti ylläpidä jaettua sääntörepoa ja linkitä se symlinkillä jokaiseen projektiin.

Mikä on suositeltu säännön enimmäispituus?

Cursorin dokumentaatio ehdottaa yksittäisten sääntöjen pitämistä alle 500 rivin. Käytännössä tavoittele alle 100 riviä per sääntö. Lyhyemmät säännöt ovat helpompia ylläpitää ja maksavat vähemmän tokeneita. Jos sääntö ylittää 150 riviä, jaa se kahteen fokusoituun sääntöön.

Toimivatko säännöt kaikkien Cursorin tekoälymallien kanssa?

Säännöt toimivat jokaisen Cursorin tukeman mallin kanssa: Claude, GPT-4o, Gemini ja muut. Säännöt syötetään järjestelmätason kontekstina riippumatta siitä, minkä mallin olet valinnut. Mallin käyttäytyminen voi vaihdella, mutta säännöt itsessään ovat malliriippumattomia.

Kuinka debuggaan sääntöä, joka ei toimi?

Ensinnäkin, varmista, että glob-kuvio vastaa tiedostoasi, avaa tiedosto ja tarkista, näkyykö sääntö kontekstipaneelissa. Toiseksi, testaa suoralla kysymyksellä, jonka pitäisi laukaista sääntö. Kolmanneksi, kokeile asettaa alwaysApply: true väliaikaisesti vahvistaaksesi, että säännön sisältö itsessään toimii. Jos se toimii, ongelma on glob-kuviossasi.

Pitäisikö minun commitoida .cursor/rules gitiin?

Ehdottomasti. Koko projektisääntöjen pointti on tiimin laajuinen johdonmukaisuus. Commitoi kaikki .cursor/rules/-hakemistossa oleva paitsi henkilökohtaiset mieltymystiedostot. Lisää personal.mdc tiedostoon .gitignore yksittäisille asetuksille, jotka eivät pitäisi päteä kaikkiin.

Voinko käyttää Cursor-sääntöjä MCP-palvelimien rinnalla?

Kyllä, ja ne täydentävät toisiaan hyvin. Säännöt määrittelevät, miten tekoälyn pitäisi kirjoittaa koodia, kun taas MCP-palvelimet antavat tekoälylle pääsyn ulkoisiin työkaluihin ja dataan. Sääntö voi sanoa "käytä aina sisäistä API-asiakastamme", kun taas MCP-palvelin antaa tekoälyn todella kysyä tuolta API:lta kehityksen aikana.

Jos tekoälyominaisuudet ovat tiekartallasi, se on erikoisalamme: Techsyn AI-integraatiotiimi vie LLM-järjestelmät prototyypistä tuotantoon. Haluatko toisen mielipiteen pinostasi? Hanki ilmainen konsultaatio.

Lähteet

• Cursor Rules Documentation
• Trigger.dev, How to Write Great Cursor Rules
• Cursor Forum, MDC Rules Best Practices and Troubleshooting
• Peakvance, Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub