Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Suunnittelu: Käyttötapaukset ja työkalut

Oppitunti 3 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Aloita odotuksista, älä rajapinnasta
  2. Käyttötapausinventaario
  3. Jätä pois ja dokumentoi se
  4. Käyttötapauksista työkaluihin
  5. Jokaisen työkalun sopimus
  6. Kuvaukset kirjoitettu valittavaksi
  7. Turvallisuusmerkinnät
  8. Suunnitelma, joka toimii testisuunnitelmana
  9. Keskeiset asiat

Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026 OpenAI:n Brainstorm plugin use cases - ja Define tools -dokumentaation perusteella. Edellinen oppitunti asensi olematonta @openai/apps-sdk-pakettia ja chatgpt-app.json-manifestia; varsinaisten työkalujen (viralliset MCP SDK:t) asennus tapahtuu oppitunnilla 4. Lähteet: Brainstorm plugin use cases · Define tools.

Aloita odotuksista, älä rajapinnasta

OpenAI:n dokumentaatio kehottaa aloittamaan liitännäisen rakentamisen ennen kuin kirjoitat ainuttakaan koodiriviä: listaamalla, mitä ihmiset odottavat siltä. Liitännäisen nimi, kuvaus, taidot, työkalut ja tuote, johon se kiinnittyy, luovat kaikki odotuksia; toteutuksesi on täytettävä ne, tai sinulla on oltava harkittu syy olla tekemättä niin.

Kuvittele henkilö, joka on asentanut liitännäisesi lukematta sen dokumentaatiota. Mitä hän pyytää sitä tekemään? Saadaksesi selville, amenna tehtävistä, joita käyttäjäsi jo suorittavat tuotteessasi, tukipyyntöjen, hakukyselyiden, ominaisuuspyyntöjen, heidän käyttämänsä sanaston sekä kiertoteiden, jotka pakottavat heidät kopioimaan dataa työkalusta toiseen. Huomioi suorat pyynnöt, joissa mainitaan liitännäisen nimi, ja epäsuorat pyynnöt, joissa ilmoitetaan vain tavoite: projektinhallintaliitännäisen on käsiteltävä ”Näytä Acmen julkaisutaulu” samalla tavalla kuin ”Mikä estää julkaisun?”.

Älä rajoita tätä inventaariota siihen, mitä rajapintasi jo tekee. Listaa odotukset ensin ja vertaa niitä sitten siihen, mitä voit tarjota turvallisesti ja luotettavasti.

Käyttötapausinventaario

Jokaista käyttö tapausta varten OpenAI suosittelee vastaamaan seitsemään kysymykseen:

KenttäKysymys
TavoiteMitä henkilö yrittää saavuttaa?
EsimerkkipyynnötMiten hän muotoilisi sen, suoraan tai epäsuorasti?
Odotettu lopputulosMikä tekisi vuorovaikutuksesta onnistuneen?
Vaadittu kontekstiMitä tietoja, tilikäyttöoikeuksia tai aiempaa tilaa tarvitaan?
KykyRiittääkö taito, vai tarvitaanko MCP-työkalu?
TurvarajaVoisiko se paljastaa dataa, muuttaa tilaa, kuluttaa rahaa tai vaikuttaa kolmanteen osapuoleen?
PäätösEnsimmäinen versio, myöhemmin vai tarkoituksellinen poisjättäminen?

Ryhmittele pyynnöt, joilla on sama tavoite: ”Listaa avoimet tehtäväni”, ”Mitä minun pitää tehdä tänään?” ja ”Näytä myöhässä olevat työt” kuuluvat todennäköisesti samaan tehtävien katselmuskäyttötapaukseen eri suodattimilla.

Varmista sitten kattavuus. Jokaisella valitulla käyttötapauksella on oltava täydellinen polku pyynnöstä tulokseen; kirjoitusoperaatioiden on sisällettävä valtuutus ja vahvistus; ja liitännäisen on osattava kertoa, mitä se ei tee, tarjoten samalla hyödyllisen seuraavan askeleen. Liitännäinen, jonka avulla voit luoda projekteja mutta et listata, tarkastella tai muokata niitä, lupaa enemmän kuin mitä se toimittaa: joko viimeistele se tai rajaa sen kohdistusta.

Jätä pois ja dokumentoi se

Sinun ei tarvitse toteuttaa kaikkea, mutta jokainen merkittävä poisjättäminen ansaitsee syyn: hyväksymätön turvallisuus- tai tietosuojariski, rajapinta, joka ei tue sitä luotettavasti, varmennettavat käyttöoikeudet puuttuvat, harhaanjohtavat tulokset puuttuvien tietojen vuoksi tai ensimmäisen version laajuus, joka on ilmoitettu selkeästi liitännäisen listauksessa. Kirjaa nämä päätökset: ne ohjaavat taitorajoituksia, työkalukuvauksia, kieltäytymisiä, testejä ja julkista listaus tekstiä.

Käyttötapauksista työkaluihin

Työkalun on palveltava käyttäjän tavoitetta. Älä vain kopioi sisäistä rajapintaasi sellaisenaan. Jokaista valittua käyttö tapausta varten kirjoita odotettu lopputulos, listaa vaaditut tiedot, tunnista luku-, kirjoitus- ja ulkoiset toiminnot, ryhmittele ne, jotka muodostavat yhtenäisen toiminnon – ja erota ne, jotka eroavat käyttöoikeuksien, riskin tai vahvistustarpeen perusteella.

OpenAI:n esimerkki projektiliitännäiselle:

  • list_projects projektien löytämiseen;
  • get_project yhden tarkasteluun;
  • create_project uuden luomiseen;
  • update_project yksityiskohtien muokkaamiseen;
  • archive_project suurivaikutteiseen tilanmuutokseen.

Luku- ja kirjoitusoperaatiot on erotettu, jotta malli ja käyttäjä voivat erottaa kuulemisen muokkaamisesta.

Jokaisen työkalun sopimus

KenttäMääritä
NimiVakaa, toimintasuuntautunut tunniste
OtsikkoTiivis, ihmiselle luettava toiminto
KuvausKäyttäjän tavoite ja ehdot, jotka pitäisi laukaista työkalu
SyöteskeemaVaaditut ja valinnaiset parametrit, tyypit, sallitut arvot, rajat
TulosteskeemaJäsennellyt kentät, joita malli voi tarkastella ja käyttää uudelleen
ValtuutusTili, rooli tai pääsy, joka palvelimen on varmistettava
SivuvaikutuksetData tai ulkoinen tila, jonka työkalu voi muuttaa
VirheetVirheet, joita malli voi selittää tai joista se voi palautua

Kolme sääntöä täydentää tätä taulukkoa. Eksplisiittiset syötteet: älä luota malliin arvatakseen tunnisteita tai tilin laajuutta. Uudelleenkäytettävät tulosteet: palauta vakaita tunnisteita ja tarpeeksi tietoa seuraavaa kutsua varten. Siistit tulosteet: ei salaisuuksia, käyttöoikeustokeneja, sisäisiä diagnostiikkatietoja tai tarpeetonta henkilökohtaista dataa.

Kuvaukset kirjoitettu valittavaksi

Malli valitsee työkalut niiden kuvauksen perusteella: kuvaile käyttäjän aikomusta, älä toteutusta. Hyvä kuvaus kertoo, mitä työkalu tekee, milloin sitä käytetään, miten se eroaa naapureistaan ja mitkä ovat sen rajat tai edellytykset. Vältä kuvauksia, jotka toistavat työkalun nimen tai käyttävät sisäistä jargonia, jota käyttäjäsi eivät tunne.

Turvallisuusmerkinnät

Jokainen työkalu sisältää merkintöjä, jotka asetetaan sen todellisen käyttäytymisen perusteella:

  • readOnlyHint on true vain, jos työkalu ei voi muuttaa mitään tilaa;
  • destructiveHint on true, jos työkalu voi tuottaa peruuttamattoman tai vaikeasti peruttavan tuloksen;
  • openWorldHint on true, jos työkalu käyttää julkista internetiä tai avoimia ulkoisia entiteettejä, vaikka se olisi vain lukuoperaatio kuten verkkohaku. Yksityinen, rajattu tili tai työtila ei ole “avoin” vain siksi, että se on isännoitu muualla.

Merkinnät auttavat ChatGPT:tä ja Codexia valitsemaan oikean vahvistustason, mutta ne eivät korvaa palvelinpuolen valtuutusta, syötteen validointia tai vahvistusta tärkeissä toiminnoissa.

Suunnitelma, joka toimii testisuunnitelmana

Pidä inventaario ja työkalusuunnitelma tallessa: niistä tulee tarkistuslistasi. Lisää suoria, epäsuoria, reunatapauksiin liittyviä ja aihealueen ulkopuolisia pyyntöjä, ja varmista, että valmis liitännäinen käyttäytyy odotetusti jokaisessa tapauksessa. Etsi myös työkaluja, jotka eivät palvele mitään dokumentoitua käyttö tapausta, puuttuvia lukuoperaatioita ennen kirjoitusoperaatioita sekä kuvauksia, jotka ovat liian lähellä toisiaan ja saattavat sekoittaa mallia.

Keskeiset asiat

  • Aloita siitä, mitä käyttäjät odottavat, ja vertaa sitten siihen, mitä voit tarjota turvallisesti
  • Seitsemän kysymyksen inventaario kutakin käyttö tapausta kohden, mukaan lukien tarkoitukselliset poisjättämiset
  • Yksi työkalu kutakin yhtenäistä toimintoa kohden; luku- ja kirjoitusoperaatiot erotettu
  • Yksi sopimus työkalua kohden: nimi, otsikko, kuvaus, skeemat, valtuutus, sivuvaikutukset, virheet
  • Merkinnät (readOnlyHint, destructiveHint, openWorldHint) seuraavat todellista käyttäytymistä eivätkä korvaa valtuutusta