Vibekoodaus-promptien kirjoittaminen: käytännön opas

Vibekoodauksessa ei kirjoiteta koodia. Kirjoitetaan ohjeita, joista koodi syntyy. Ja se, miten nuo ohjeet muotoilee, ratkaisee lopputuloksen laadun enemmän kuin mikään muu yksittäinen tekijä.

Olet ehkä kokeillut Cursoria tai Claude Codea ja todennut, että välillä tekoäly tuottaa täydellistä koodia ja välillä täyttä sotkua. Ero ei yleensä johdu työkalusta. Se johtuu promptista.

Hyvällä promptilla saat toimivan komponentin ensimmäisellä yrityksellä. Huonolla promptilla käyt läpi kymmenen iteraatiokierrosta ja päädyt silti korjaamaan koodia käsin. Tämä opas näyttää konkreettisesti, miten kirjoitat prompteja, jotka oikeasti toimivat vibekoodauksessa.

Jos promptaaminen on sinulle täysin uusi asia, lue ensin pikaopas promptaamiseen. Tässä postauksessa mennään syvemmälle nimenomaan vibekoodauksen näkökulmasta -- käytännön esimerkkien ja toistuvien patternien kautta.

Hyvän promptin anatomia

Tehokas vibekoodausprompt koostuu neljästä osasta: konteksti, tehtävä, rajoitteet ja tuloksen muoto.

Konteksti kertoo tekoälylle, missä ympäristössä työskennellään. Mikä on tech stack, mikä on projektin rakenne, mitä on jo olemassa.

Tehtävä on se, mitä haluat tekoälyn tekevän. Yksi selkeä asia kerrallaan.

Rajoitteet rajaavat ratkaisutilaa. Mitä kirjastoja saa tai ei saa käyttää, miten virhetilanteet käsitellään, minkälaista tyyliä noudatetaan.

Tuloksen muoto kertoo, minkä muotoista outputtia odotat. Yksittäinen funktio, kokonainen komponentti, vai pelkkä suunnitelma.

Tässä esimerkki, jossa kaikki neljä osaa ovat mukana:

Konteksti: Next.js 15 -projekti, App Router, TypeScript, Tailwind CSS.
Tehtävä: Luo hakukomponentti, joka suodattaa blogipostauksia otsikon perusteella.
Rajoitteet: Käytä client componenttia. Ei ulkoisia kirjastoja. Debounce 300ms.
Tuloksen muoto: Yksi SearchBar.tsx-tiedosto, joka exporttaa default-komponentin.

Vertaa tätä promptiin "tee hakutoiminto" ja ymmärrät, miksi rakenne ratkaisee.

Sinun ei tarvitse aina kirjoittaa kaikkia neljää osaa eksplisiittisesti. Mutta mitä useampi osa on mukana, sitä vähemmän tekoäly joutuu arvailemaan. Ja jokainen arvaus on mahdollisuus mennä väärään suuntaan.

Huono vs. hyvä prompti

Paras tapa oppia on nähdä konkreettisia esimerkkejä. Tässä viisi ennen/jälkeen-paria, joissa huono prompti on muokattu toimivaksi.

Esimerkki 1 -- Uusi komponentti

Huono:

Tee lomake

Hyvä:

Luo React-lomakekomponentti (TypeScript), jossa on kentät: nimi (teksti, pakollinen),
sähköposti (email, pakollinen) ja viesti (textarea, valinnainen). Käytä
React Hook Formia validointiin. Näytä virheviestit kenttien alla punaisella.
Submittaessa kutsu /api/contact POST-endpointtia ja näytä onnistumisviesti.
Tailwind CSS -tyylit.

Ensimmäinen prompti jättää kaiken arvailujen varaan. Minkälainen lomake? Mitä kenttiä? Mikä validointi? Mihin data lähetetään? Tekoäly tekee valinnan jokaisessa kohdassa, ja todennäköisyys, että se arvaa kaikki oikein, on hyvin pieni.

Toinen prompti kertoo tarkat kentät, validoinnin, kirjaston, tyylit ja mitä tapahtuu submitissa. Tekoälylle ei jää juuri mitään arvattavaa.

Esimerkki 2 -- Virheen korjaus

Huono:

Tämä ei toimi, korjaa

Hyvä:

Saan tämän virheen Next.js-projektissa:

Error: Hydration failed because the initial UI does not match
what was rendered on the server.

Virhe tulee UserMenu-komponentissa, joka näyttää käyttäjän nimen.
Komponentti käyttää useSessionia next-authista. Virhe ilmenee vain
tuotantobuildin jälkeen, devissä toimii.

Miten korjaan hydration mismatchin?

Virheen korjaamiseen tekoäly tarvitsee kolme asiaa: virheilmoituksen, kontekstin ja tiedon siitä, milloin virhe toistuu.

Esimerkki 3 -- Refaktorointi

Huono:

Paranna tätä koodia

Hyvä:

Refaktoroi alla oleva funktio. Ongelmat: se on 85 riviä pitkä,
sisältää toistuvaa logiikkaa ja error handling puuttuu kokonaan.

Haluan:
- Pilko pienempiin funktioihin (max 20 riviä per funktio)
- Lisää try-catch ja palauta selkeät virheilmoitukset
- Poista toistuva koodi omiin apufunktioihin
- Säilytä sama julkinen API (funktionimi ja parametrit)

[koodi tähän]

Pelkkä "paranna" ei kerro mitä pitäisi parantaa. Kun listat konkreettiset ongelmat ja halutun lopputuloksen, saat kohdennettuja muutoksia.

Esimerkki 4 -- Uusi feature olemassa olevaan koodiin

Huono:

Lisää dark mode

Hyvä:

Lisää dark mode -tuki olemassa olevaan Next.js-sovellukseen.

Nykytilanne: Sovellus käyttää Tailwind CSS:ää. Värit on kovakoodattu
(bg-white, text-black jne.). Teemaa ei voi vaihtaa.

Haluan:
1. Tailwindin dark:-prefixin käyttöönotto
2. ThemeToggle-komponentti, joka vaihtaa light/dark-tilan
3. Teemavalinta tallennetaan localStorageen
4. Käyttäjän järjestelmäasetus tunnistetaan oletukseksi (prefers-color-scheme)

Aloita konfiguraatiosta (tailwind.config) ja näytä sitten ThemeToggle-komponentti.

Oleellista on kertoa, mikä on nykytilanne, mitä haluat, ja missä järjestyksessä asiat kannattaa toteuttaa.

Esimerkki 5 -- Testien kirjoittaminen

Huono:

Kirjoita testejä

Hyvä:

Kirjoita yksikkötestit calculatePrice-funktiolle Vitestillä.
Funktio ottaa parametreina: basePrice (number), quantity (number)
ja discountCode (string | undefined).

Testaa ainakin:
- Normaali hinta ilman alennuskoodia
- Hinta alennuskoodilla "SUMMER20" (20% alennus)
- Virheellinen alennuskoodi palauttaa normaalin hinnan
- quantity 0 palauttaa 0
- Negatiivinen quantity heittää virheen

Mitä tarkemmin kerrot testattavat skenaariot, sitä hyödyllisemmät testit saat. Ilman spesifejä skenaarioita tekoäly kirjoittaa tyypillisesti vain happy path -testejä ja jättää reunatapaukset huomiotta.

Prompt-patternit, jotka toimivat

Vibekoodauksessa tietyt prompt-rakenteet toistuvat. Kun opit tunnistamaan ne, promptien kirjoittaminen nopeutuu huomattavasti. Tässä neljä patternia, jotka kannattaa opetella.

"Build from scratch" -pattern

Kun rakennat jotain uutta tyhjästä, tämä rakenne toimii lähes aina. Kerro mitä rakennat, millä teknologioilla, mitä vaadit ja mitä rajoituksia on:

Rakenna [komponentti/feature/sovellus].

Tech stack: [teknologiat]
Vaatimukset:
- [vaatimus 1]
- [vaatimus 2]
- [vaatimus 3]

Ei saa käyttää: [rajaukset]
Tiedostorakenne: [miten haluat koodin organisoitavan]

"Refactor this" -pattern

Refaktoroidessa kerro aina miksi ja mitä haluat lopputulokseksi:

Refaktoroi alla oleva koodi.

Ongelmat:
- [ongelma 1]
- [ongelma 2]

Haluttu lopputulos:
- [tavoite 1]
- [tavoite 2]

Rajoitteet:
- [mitä ei saa muuttaa]

[koodi]

"Debug this error" -pattern

Virheenkorjauksessa liitä aina virheilmoitus ja konteksti:

Saan seuraavan virheen:

[virheilmoitus kokonaisuudessaan]

Konteksti:
- Projekti: [tech stack]
- Tiedosto: [missä virhe ilmenee]
- Milloin: [milloin virhe toistuu]
- Mitä olen jo kokeillut: [aiemmat yritykset]

"Add feature" -pattern

Olemassa olevaan koodiin lisätessä kerro nykytilanne ensin. Tämä on kriittistä, koska tekoäly ei tiedä mitä olet jo rakentanut, ellei sinä kerro:

Lisää [feature] olemassa olevaan [komponenttiin/sovellukseen].

Nykytilanne: [mitä on jo olemassa]
Haluttu muutos: [mitä haluat lisätä]
Vaikutukset: [mihin muihin osiin muutos vaikuttaa]

Huomaa, että jokaisessa patternissa on sama perusidea: anna tekoälylle tarpeeksi tietoa, jotta sen ei tarvitse arvata. Patternit ovat vain tapoja jäsentää tuo tieto selkeästi.

Konteksti on kuningas

Promptin sisältö on tärkeää, mutta vibekoodauksessa kontekstin antaminen on vielä tärkeämpää. Tekoäly ei näe projektiasi, ellei sinä näytä sitä.

Cursorissa voit viitata tiedostoihin suoraan @-syntaksilla. Käytä sitä ahkerasti:

@components/Header.tsx @lib/auth.ts

Lisää Header-komponenttiin kirjautumispainike, joka käyttää
auth.ts:n signIn-funktiota.

Kun Cursor näkee molemmat tiedostot, se ymmärtää olemassa olevat tyypit, funktiot ja rakenteet. Ilman tiedostoviittauksia se arvaa, ja arvaukset menevät usein pieleen.

Claude Codessa konteksti toimii eri tavalla. Claude Code pääsee käsiksi koko projektirakenteeseen, mutta voit silti ohjata sitä:

Katso src/lib/api/ -kansio ja sen nykyinen rakenne. Lisää uusi
endpoint src/app/api/users/route.ts, joka noudattaa samaa patternia
kuin olemassa olevat endpointit.

Tärkeintä on, että kerrot tekoälylle, mitä tiedostoja ja rakenteita sen pitäisi katsoa ennen kuin se alkaa koodaamaan.

Hyvä nyrkkisääntö: jos promptissasi viitataan johonkin olemassa olevaan koodiin, liitä se mukaan tai viittaa siihen. Tekoäly ei osaa lukea ajatuksiasi, mutta se osaa lukea koodiasi -- kunhan näytät sen.

Kontekstin antamiseen liittyy myös tärkeä rajaus: älä anna liikaa kontekstia. Jos liität mukaan 20 tiedostoa, tekoäly saattaa hämmentyä siitä, mikä on oleellista. Valitse 2--4 relevanteinta tiedostoa ja mainitse ne eksplisiittisesti.

Iteratiivinen promptaaminen

Yksi suurimmista virheistä on yrittää saada kaiken valmiiksi yhdellä megapromptilla. 500 sanan prompti, jossa kuvaat kokonaisen sovelluksen, tuottaa harvoin toimivaa lopputulosta.

Parempi strategia on edetä askel kerrallaan. Ajattele sitä kuin keskustelua: annat ohjeen, katsot tuloksen, tarkennat ja jatkat.

Vaihe 1 -- Suunnitelma. Pyydä ensin suunnitelmaa, älä koodia.

Suunnittele autentikointijärjestelmä Next.js-sovellukseen.
NextAuth.js, Google- ja GitHub-kirjautuminen, PostgreSQL-tietokanta.
Älä kirjoita koodia vielä. Kerro tiedostorakenne ja toteutusjärjestys.

Vaihe 2 -- Toteutus palasissa. Toteuta yksi osa kerrallaan.

Hyvä suunnitelma. Aloitetaan vaiheesta 1: NextAuth-konfiguraatio.
Luo src/lib/auth.ts tiedosto suunnitelman mukaisesti.

Vaihe 3 -- Tarkistus ja korjaus. Tarkista jokainen osa ennen seuraavaan siirtymistä.

Tämä näyttää hyvältä, mutta session callback ei sisällä
käyttäjän roolia. Lisää role-kenttä sessioniin ja päivitä tyypit.

Iteratiivisessa lähestymistavassa jokainen vaihe on helpompi tarkistaa ja korjata. Yhden virheen löytäminen 20 rivin muutoksesta on paljon helpompaa kuin 200 rivin muutoksesta.

Toinen iteratiivisen promptaamisen etu on, että voit muuttaa suuntaa kesken kaiken. Jos vaiheessa 2 huomaat, että arkkitehtuuri ei toimi, voit palata suunnitelmaan ilman, että menetät kaikkea tehtyä työtä.

Käytännössä iteratiivinen promptaaminen tarkoittaa myös sitä, että jokainen promptisi on lyhyempi ja helpompi kirjoittaa. Sen sijaan, että yrität kuvata kaiken kerralla, keskityt aina yhteen asiaan. Tämä tekee koko prosessista vähemmän kuormittavaa.

Kieli: suomi vai englanti?

Vibekoodauksessa kielivalinta on käytännön kysymys, ei periaatekysymys. Molemmat kielet toimivat, mutta eri tilanteissa toinen on selkeästi parempi vaihtoehto.

Käytä englantia koodiin liittyvissä prompteissa. Tekoälymallit on koulutettu valtavilla määrillä englanninkielistä koodia ja dokumentaatiota. Englanninkielinen prompti tuottaa tyypillisesti tarkempia tuloksia, erityisesti kun kyse on spesifeistä kirjastoista tai frameworkeista.

Create a custom React hook useDebounce that takes a value and
a delay in milliseconds. Return the debounced value. Include
TypeScript generics for the value type.

Käytä suomea kun selität liiketoimintalogiikkaa, käyttäjätarinoita tai haluat koodikommentteja suomeksi.

Tee tilausjärjestelmän yhteenvetosivu. Käyttäjä näkee tilauksensa:
tuotteet, hinnat, alennukset ja toimituskulut. Yhteenveto näyttää
loppusumman ALV:n kanssa ja ilman. Tekstit suomeksi.

Sekoittaminen on ok. Käytännössä monet vibekoodaajat kirjoittavat promptin suomeksi mutta käyttävät teknisiä termeja englanniksi. Tämä toimii hyvin:

Lisää React Query -hook, joka hakee käyttäjän tilaukset
/api/orders-endpointista. Käytä useQuery:a ja lisää staleTime
5 minuuttiin. Error boundary -käsittely mukaan.

Yksi käytännön vinkki: jos huomaat, että suomenkielinen prompti tuottaa outoa koodia tai väärinymmärryksiä, kokeile samaa promptia englanniksi. Erityisesti harvinaisempien kirjastojen kanssa englanti toimii luotettavammin, koska koulutusdata on painottunut englanninkieliseen koodiin.

Muista myös, että kielivalinta vaikuttaa koodikommentteihin ja muuttujanimiin. Jos haluat suomenkieliset kommentit, mainitse se erikseen. Muuten tekoäly kirjoittaa kommentit samalla kielellä kuin prompti.

Yleisimmät promptivirheet

Liian epämääräinen. "Tee siisti UI" ei kerro mitään. Kerro mitä elementtejä, minkälainen layout, mitkä värit.

Liian pitkä ilman rakennetta. Viiden kappaleen proosapromptissa tekoäly kadottaa oleellisen. Käytä luettelomerkkejä ja selkeitä otsikoita. Promptin ei tarvitse olla lyhyt, mutta sen pitää olla jäsennelty.

Konteksti puuttuu. Prompti puhuu "olemassa olevasta komponentista", mutta komponenttia ei ole liitetty mukaan. Viittaa aina tiedostoihin tai liitä relevantti koodi. Tämä on erityisen yleinen virhe, kun käytät selainpohjaista tekoälyä kuten ChatGPT:tä, jolla ei ole pääsyä projektiisi.

Monta asiaa kerralla. "Lisää autentikointi, tee dashboard ja optimoi suorituskyky" on kolme erillistä tehtävää. Tee ne erikseen.

Edellisen tuloksen sivuuttaminen. Jos tekoäly tuotti jotain, joka ei vastaa odotuksiasi, kerro tarkalleen mikä oli pielessä. "Ei, tee uudestaan" ei auta. "Napit ovat liian pieniä mobiilissa ja värit eivät vastaa designia" auttaa.

Oletukset ilman tarkistusta. Tekoäly saattaa käyttää vanhentunutta API:a tai väärää kirjastoversiota. Tarkista aina generoitu koodi ennen kuin ajat sen. Erityisesti import-lauseet ja pakettiversion kannattaa käydä läpi.

Liian suuri kerralla. "Rakenna minulle kokonainen verkkokauppa" on liian laaja yhdelle promptille. Pilko se osiin: ensin tietokantarakenne, sitten tuotelistaus, sitten ostoskori, ja niin edelleen. Jokainen osa on oma promptinsa.

Seuraavat askeleet

Promptien kirjoittaminen on taito, joka kehittyy harjoittelemalla. Kukaan ei kirjoita täydellisiä prompteja ensimmäisellä kerralla. Aloita yksinkertaisista prompteista, lisää rakennetta vähitellen ja opi jokaisesta iteraatiosta.

Tärkeintä on sisäistää perusperiaate: mitä vähemmän tekoälyn tarvitsee arvata, sitä paremman tuloksen saat. Konteksti, selkeys ja rajaukset ovat aina tärkeämpiä kuin promptin pituus tai hienot muotoilut.

Valmiita promptipohjia eri tilanteisiin löydät promptimallisivulta. Jos promptaaminen on vielä tuore aihe, lue myös pikaopas promptaamiseen.

Promptit toimivat parhaiten, kun tunnet myös työkalusi. Tutustu Cursorin oppaaseen jos käytät editoripohjaista vibekoodausta, tai Claude Coden oppaaseen jos haluat terminaalipohjaisen työkalun.