---
title: "Prompt-tyyliopas"
description: "Näin kirjoitat ja muokkaat ThunderPhone-puheagentin promptia: ohjeet, promptin tarkistukset ja niiden havaintojen viittaamat tunnukset."
---

{/*
  LUOTU TIEDOSTO: älä muokkaa käsin.
  Lähde: api/agents/prompt_style_guide.md
  Luo uudelleen: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  CI luo tämän sivun uudelleen ja epäonnistuu, jos poikkeamia havaitaan
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh).
*/}

<Note>
  Tämä on ohje, jota [kehote-arviointi](/api-reference/agents#review-a-prompt) käyttää kehotteen tarkistamiseen ja jonka
  tunnuksiin alla sen havainnot viittaavat. [MCP-palvelimeen](/fi/guides/thunderphone-mcp-server) yhdistetyt koodausagentit
  lukevat saman tekstin resurssina
  `thunderphone://guides/prompt-style`. Katso mallit ja esimerkit
  [kehoteoppaasta](/fi/guides/prompting).
</Note>

Tämä opas on kaikille, jotka kirjoittavat tai muokkaavat puheagentin kehotetta: rakentajassa työskentelevälle henkilölle, Copilotille tai API:n kautta työskentelevälle koodausagentille. Kehote-arviointityökalu käyttää tätä arviointiperusteenaan ja viittaa sen ohjetunnuksiin (P1, W2 ja niin edelleen).

Soittaja kuulee agentin kerran puhenopeudella eikä voi vierittää takaisin. Agentti lukee kehotteen jokaisella
vuorolla ja noudattaa sen sanamuotoa tarkasti. Nämä molemmat seikat ohjaavat kaikkea alla olevaa.

## Rakenne

**P1. Kirjoita se kuten ihminen perehdyttäisi uuden vastaanottovirkailijan.** Lyhyt aloitus kertoo, kuka agentti on ja kenen puolesta
se toimii. Puhelu etenee sitten tapahtumajärjestyksessä: miten se alkaa, mitä selvitetään, mitä vahvistetaan,
miten se päättyy. Jokainen sääntö on siinä puhelun osassa, johon se liittyy. Lukijan pitäisi voida kysyä jokaisesta
kappaleesta: ”olisiko tätä yritystä johtava henkilö voinut kirjoittaa tämän?” Selvitettävät asiat kattavat sen, mitä yritys tarvitsee pyynnön käsittelemiseksi,
eivät vain sen, kuka soittaa ja miten hänet tavoittaa.

**P2. Selkeät otsikot, niiden alla tekstiä.** Otsikot kuten "Kuka olet", "Puhelu", "Tiedot" ja "Ohjaaminen eteenpäin"
auttavat. Konemainen rakenne ei auta: numeroidut sääntökäsikirjat, camelCase- tai koodimaiset otsikot, pitkät ajatusviivalla alkavat
sääntöluettelot, työkalujen viiteosio alussa sekä ristiviittaukset kuten "katso alla kohta 4". Luettelot sopivat tiedoille,
joita agentti hakee (aukioloajat, hinnat, osoite).

**P3. Puhetapa kerran, lyhyesti.** Se, miten agentti puhuu koko puhelun ajan (lyhyet ensimmäisen persoonan
vuorot, lämmin sävy, selkeät sanat; katso S2), mahtuu yhteen lyhyeen kappaleeseen lähellä alkua. Kaikki yhteen vaiheeseen liittyvä on
siinä vaiheessa.

**P4. Tiedot erillään toiminnasta.** Aukioloajat, hinnat, sijainnit, käytännöt ja muut tiedot kuuluvat kehotteen
tieto-osioon tai tietopankkiin, eivät hajalleen puhelun kulkuun. Pitkät luettelot ja usein kysytyt kysymykset kuuluvat tietopankkiin.
Agentti saa kertoa vain sille annettuja tietoja.

## Sisältö

**C1. Periaatteet ja faktat, ei käsikirjoituksia.** Kuvaa, mitä agentti pyrkii saavuttamaan ja mitä sen on
tiedettävä. Jätä pois haarat kuten "jos soittaja sanoo X, sano Y", ennakoituihin kysymyksiin laaditut
käsikirjoitetut vastaukset ja valmiit repliikit. Määritetty avaustervehdys on ainoa käsikirjoitettu elementti.

**C2. Korjaus ilmaisee yleisen periaatteen.** Kun kehotteen muutos vastaa havaittuun epäonnistumiseen, muutos lisää
yleisen periaatteen tai puuttuvan faktan, ei korjausta vain kyseistä tapausta varten. Epäonnistuneen puhelun
yksityiskohdat (sen nimet, numerot ja tarkat sanat) eivät kuulu kehotteeseen.

**C3. Poistaminen on lisäämistä parempi.** Kun epäonnistuminen johtuu olemassa olevasta säännöstä, joka on liian
tarkka, liian laaja tai huonosti sijoitettu, muuta tai poista sääntö sen sijaan, että lisäät sen viereen
vastasäännön.

**C4. Asetukset ratkaisevat jotkin asiat, ei kehote.** Seuraavat ovat agentin asetuksia, ja niitä koskeva
kehiteteksti jätetään huomiotta tai se on ristiriidassa niiden kanssa: mitä sanotaan työkalun suorittamisen aikana
(työkalun aloitusrepliikki, täyteilmaukset), hiljaisuuden tarkistukset ja hiljaisuuden jälkeinen viimeinen toiminto,
toiston tahti, kielen vaihtamisen tyyli, tallennusilmoitus sekä se, puhuuko agentti vai soittaja ensin. Suuntaa
kehote lopputulokseen ("vahvista sähköpostiosoite ennen sen tallentamista") ja määritä asetus. Avaustervehdys
itsessään kirjoitetaan kehotteeseen.

**C5. Esimerkit ovat repliikkejä, jotka agentti sanoo.** Agentti kopioi esimerkkien sanamuodon lähes sanasta
sanaan, joten jokainen esimerkki on kokonainen, luonteva puhuttu lause, ja muutama vaihteleva esimerkki on yhtä
parempi. Esittele ne esimerkkeinä ("Voisit esimerkiksi sanoa ..."), älä vaadittuna repliikkinä. Katkaistut
tunnisteet, kuten "Onko edelleen oikein?", kuulostavat puhuttuina töksähtäviltä.

**C6. Ei esimerkkejä omien asiakkaidemme puheluista.** Esimerkit kuvaavat tilanteen tyyppiä yleisellä tasolla tai
käyttävät keksittyä yritystä.

**C7. Kehote on soittajia varten, ei toteutusta koskeva.** Soittajat kuulevat kaiken, mitä kehotteessa sanotaan, kun se on käytössä, joten siihen ei sisällytetä toteutusta, testausta tai vaatimustenmukaisuuden tilaa koskevia huomautuksia ("tämä versio on testausta varten", "TEST" varauksen nimessä, "kunnes sopimukset on allekirjoitettu"). Siihen ei myöskään sisällytetä vastuuvapautuslausekkeita, vastuunrajoituksia tai loppuyhteenvetoja, joita yritys ei ole pyytänyt, kuten sitä, mitä suunnitelman hyväksyminen ei tarkoita, tai yhteenvetoa siitä, mitä ei ole vielä vahvistettu. Agentti vastaa siihen, mitä soittaja kysyi, ja lopettaa; yritys lisää varauman halutessaan. Puuttuva tieto tai järjestelmärajoitus kirjoitetaan sen mukaisesti, mitä agentti tekee ("hintojen osalta tarjoa takaisinsoittoa toimistolta"), ei huomautuksena siitä, ettei tietoa annettu, tai siitä, miten pyynnöt kirjataan, eikä luonnostelusta jää mitään ylimääräistä, kuten irrallista nimeä tai otsikkoa.

## Sanamuoto

**W1. Kerro, mitä tehdään, selkeästi ja kerran.** Ilmaise haluttu toiminta tavallisilla sanoilla annettavana ohjeena: "Lue
tilausnumero takaisin numero kerrallaan, jotta soittaja voi korjata sen." Sano se kerran siinä kohdassa, jossa se pätee.

**W2. Ei korostuksia.** Ei TÄRKEÄÄ-, HUOMAUTUS- tai KRIITTINEN-otsikoita, ei isoilla kirjaimilla kirjoitettuja
sanoja tehosteeksi, ei huutomerkkejä, ei "Huono:"- ja "Hyvä:"-pareja eikä lohkoja siitä, mitä ei pidä tehdä.
Myös tehostamiseen käytetyt sanat, kuten "ei koskaan", "aina" ja "täytyy", kuuluvat tähän. Korostus vetää mallin
huomion yhteen sääntöön ja heikentää sen suoriutumista puhelun muissa osissa. Kun agentti sivuuttaa ohjeen, tee
ohjeesta selkeämpi, tarkempi tai paremmin sijoitettu, älä painokkaampi.

**W3. Korjaa toiminnan aiheuttava rakenne.** Ennen kuin lisäät säännön jotakin agentin tekemää asiaa vastaan,
etsi sanamuoto tai rakenne, joka johtaa siihen: malli, jonka malli täyttää kirjaimellisesti, termi, jolla on kaksi
merkitystä, tai jos-muuten-haara, jonka nopea malli tulkitsee väljästi. Muuta sitä.

**W4. Tarkka on yleistä parempi.** "Tarjoa kaksi aikaisinta vapaata aikaa ja kysy sitten, kumpi sopii" on parempi
kuin "auta ajanvarauksessa". Epämääräiset ohjeet tuottavat epämääräistä toimintaa.

**W5. Tarkista se ennen kuin kysyt siitä.** Kun soittaja mainitsee asian, jonka vain luku -hakutyökalu voi tarkistaa (tuotteen,
tilauksen tai olemassa olevan varauksen), agentti tarkistaa sen soittajan käyttämillä sanoilla ja esittää jatkokysymyksen vain,
jos tulos sitä edellyttää. "Tarkista soittajan nimeämän tuotteen varastotilanne ja kerro, mitä löydät" toimii paremmin kuin
"selvitä merkki, koko ja variantti ja tarkista sitten varastotilanne": agentti, jota kehotetaan ensin selvittämään, jatkaa
kyselyä eikä tarkistusta koskaan tehdä. Tämä koskee vain hakuja. Ennen kuin käytät työkalua, joka varaa, muuttaa, peruuttaa tai
tallentaa jotain, agentti vahvistaa silti tiedot soittajalta.

## Puhe

**S1. Yksi kysymys vuoroa kohti, ja kysymys päättää vuoron.** Kaikki kysymyksen jälkeen sanottu puhuu soittajan
vastauksen päälle. Sijoita mahdollinen selitys ennen kysymystä.

**S2. Lyhyet vuorot kokonaisina puhuttuina lauseina.** Käytä yhtä tai kahta lyhyttä lausetta, ellei soittaja pyydä lisätietoja.
Puhuttuja vaihtoehtoja on vain muutama. Lyhyt tarkoittaa vähäsanaista, ei katkonaisia ilmauksia: agentti puhuu kuten hyvä
vastaanottovirkailija puhelimessa, kokonaisilla lauseilla ensimmäisessä persoonassa, esimerkiksi "Varaan sen sinulle nyt" tai
"Merkitsin sinulle ajan maanantaille kello kymmeneksi." Muistiinpanotyyliset katkelmat ("Varaan sen sinulle.", "Valmis.",
"Merkitty.") kuulostavat puhuttuina töksähtäviltä, ja sähköpostimaiset ilmaukset ("Huomioi, että ...", "Ystävällisesti ...",
"Toivottavasti tästä on apua") kuulostavat luetuilta eivätkä puhutuilta. Kehotteen puhetapaa käsittelevässä kappaleessa tämä
pyydetään selkeästi, esimerkiksi: "Pidä jokainen vuoro yhden tai kahden lauseen mittaisena ja puhu ensimmäisessä persoonassa,
kuten vastaanottovirkailija puhelimessa."

**S3. Kirjoita korvalle.** Vältä agentin sanomissa asioissa Markdownia, symboleja ja merkintätapoja, jotka ääni
lukee oudosti (kauttaviivat, &-merkit, "@", ".com", tuhaterottimet ja välilyönnittömät puhelinnumerot). Faktat ja
arvot, jotka agentti välittää työkalulle, kuten sähköpostiosoite tai tilinumero, säilyvät tarkassa kirjallisessa
muodossaan; kun jokin niistä täytyy myös sanoa ääneen, lisää sen viereen ääntämistapa sen sijaan, että kirjoittaisit
sen uudelleen. Kirjoita, miten epätavalliset nimet tai lyhenteet lausutaan, ja kuuntele uudet termit agentin äänellä
ennen niiden säilyttämistä.

**S4. Vahvista tiedot, joiden virheellisyys olisi kallista.** Numerot, sähköpostiosoitteet, osoitteet ja koodit toistetaan siinä muodossa,
jossa ne annettiin, kerran, vastauksessa heti sen jälkeen, kun soittaja on antanut ne, ja ennen seuraavaa kysymystä, yksi arvo
kutakin toistoa kohden. Oletusarvoisesti nimi hyväksytään sellaisena kuin se sanotaan ilman toistoa, ja agentti pyytää sen
oikeinkirjoitusta vain, jos se on epätavallinen tai epäselvä, ja pyytää sitä vain kerran. Kun yritys tarvitsee nimen täsmällisenä,
esimerkiksi tietojensa täsmäyttämiseksi tai kyseiselle nimelle tehtävää varausta varten, kehote kertoo tämän ja agentti tavuttaa
nimen takaisin. Toisto antaa soittajalle mahdollisuuden korjata arvon, ei ole este: soittaja, joka vastaa seuraavalla tiedolla tai
jatkaa korjaamatta sitä, on hyväksynyt sen, eikä hyväksyttyä arvoa kysytä uudelleen. Poikkeus on puhelinnumero, johon yritys
soittaa tai lähettää tekstiviestin: sen toisto päättää vuoron ja odottaa soittajan vastausta. Kehote, jossa pyydetään lukemaan
numerot numero kerrallaan, nimeää vain tällä tavoin luettavat arvot (puhelinnumeron, koodin); talonumero, hinta, kellonaika tai
päivämäärä sanotaan samalla tavalla kuin ihmiset ne sanovat. Kehote kertoo, mitä vahvistetaan; alusta rytmittää toiston.

## Iterointi

**I1. Testaa ennen kuin pidät muutoksen.** Toista agentin kehitysaineisto muokatussa luonnoksessa ja vertaa sitä
nykyiseen versioon: mitkä esimerkit muutos korjasi ja mitkä se rikkoi. Lue vastaukset niin kuin soittaja kuulisi ne.
Kaikki, minkä soittaja huomaisi, on ongelma eikä yksityiskohta.

**I2. Pitojoukko tarkistetaan kerran.** Säädä vain kehitysaineiston perusteella. Aja testiaineisto, kun muutos on valmis, ja
raportoi sen tulos sellaisena kuin se on. Testitulosten näkemisen jälkeen tehty muutos tarvitsee uudet testiesimerkit.

**I3. Refaktoroi, kun paikkauksia kertyy.** Kehote, johon on kertynyt paljon pieniä korjauksia, ajautuu pois P1:stä: säännöt
toistuvat, ovat ristiriidassa tai ovat kaukana vaiheesta, jota ne ohjaavat. Kirjoita se silloin uudelleen tähän muotoon säilyttäen kaikki sen pyytämät toimintatavat.
Luettele jokainen toimintatapa säilytettynä, yhdistettynä, uudelleenmuotoiltuna tai poistettuna, äläkä poista mitään hiljaa. Toista kehitysaineisto ennen ja jälkeen; refaktoroinnin tulee muuttaa sanamuotoa, ei toimintaa.

**I4. Tarkista määritykset ennen kehotetta.** Kaikki virheet eivät johdu kehotteesta: tavattujen
kirjainten kuuleminen väärin on kuuntelurajoitus (kokeile Plus-kuuntelua), hidas vastaus voi johtua älykkyys- tai kuuntelutasosta tai endpointing-asetuksesta. Sulje määrityksiin liittyvät syyt pois ennen tekstin uudelleenkirjoittamista.
