Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Dizajn: Slučajevi upotrebe i alati

Lekcija 3 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Kreni od očekivanja, a ne od API-ja
  2. Popis slučajeva upotrebe
  3. Isključi i dokumentiraj to
  4. Od slučajeva upotrebe do alata
  5. Ugovor svakog alata
  6. Opisi napisani da budu odabrani
  7. Sigurnosne napomene
  8. Plan koji služi kao plan testiranja
  9. Ključne točke

Lekcija je ponovno napisana 3. studenog 2026. na temelju OpenAI-jevih stranica dokumentacije Brainstorm plugin use cases i Define tools. Prethodna lekcija instalirala je nepostojeći paket @openai/apps-sdk i manifest chatgpt-app.json; instalacija stvarnih alata (službeni MCP SDK-ovi) odvija se u Lekciji 4. Izvori: Brainstorm plugin use cases · Define tools.

Kreni od očekivanja, a ne od API-ja

OpenAI-jeva dokumentacija savjetuje da počneš graditi dodatak prije nego što napišeš ijednu liniju koda: tako da navedeš što će ljudi od njega očekivati. Naziv dodatka, opis, vještine, alati i proizvod na koji se nadovezuje – sve to stvara očekivanja; tvoja implementacija mora ih ispuniti ili imati namjeran razlog zašto to ne čini.

Zamisli nekoga tko je instalirao tvoj dodatak bez čitanja dokumentacije. Što će ga pitati da učini? Da bi to saznao, osloni se na zadatke koje tvoji korisnici već obavljaju u tvom proizvodu, na zahtjeve za podršku, upite za pretraživanje, zahtjeve za nove funkcije, rječnik koji koriste i privremena rješenja koja ih prisiljavaju da kopiraju podatke iz jednog alata u drugi. Zabilježi izravne zahtjeve koji imenuju dodatak i neizravne zahtjeve koji navode samo cilj: dodatak za upravljanje projektima mora jednako dobro obraditi „Prikaži Acme ploču za lansiranje“ kao i „Što koči lansiranje?“.

Nemoj ograničiti ovaj popis samo na ono što tvoj API već radi. Prvo navedi očekivanja, a zatim ih usporedi s onim što možeš sigurno i pouzdano pružiti.

Popis slučajeva upotrebe

Za svaki slučaj upotrebe OpenAI preporučuje odgovoriti na sedam pitanja:

PoljePitanje
CiljŠto osoba pokušava postići?
Primjeri zahtjevaKako bi to formulirali, izravno ili neizravno?
Očekivani ishodŠto bi interakciju učinilo uspješnom?
Potreban kontekstKoje su informacije, pristup računu ili prethodno stanje potrebni?
MogućnostJe li vještina dovoljna ili je potreban MCP alat?
Granica sigurnostiMože li ovo otkriti podatke, modificirati stanje, potrošiti novac ili utjecati na treću stranu?
OdlukaPrva verzija, kasnija verzija ili namjerno isključenje?

Grupiraj zahtjeve koji dijele isti cilj: „Navedi moje otvorene zadatke“, „Što moram učiniti danas?“ i „Prikaži zakašnjele poslove“ vjerojatno pripadaju istom slučaju upotrebe pregleda zadataka, ali s različitim filtrima.

Zatim provjeri pokrivenost. Svaki odabrani slučaj upotrebe mora imati potpun put od zahtjeva do rezultata; operacije pisanja moraju uključivati autorizaciju i potvrdu; a dodatak mora znati kako reći što ne radi, nudeći pritom koristan sljedeći korak. Dodatak koji ti omogućuje stvaranje projekata, ali ne i njihovo nabrajanje, pregled ili uređivanje, obećava više nego što isporučuje: ili ga dovrši ili suzi njegovu pozicioniranost.

Isključi i dokumentiraj to

Ne moraš implementirati sve, ali svako veće isključenje zaslužuje razlog: neprihvatljiv rizik za sigurnost ili privatnost, API koji to ne može pouzdano podržati, neprovjerive dozvole, zavaravajući rezultati zbog nedostatka informacija ili opseg prve verzije jasno naveden u popisu dodataka. Zabilježi ove odluke: one informiraju ograničenja vještina, opise alata, odbijanja, testove i tekst javnog popisa.

Od slučajeva upotrebe do alata

Alat mora služiti korisničkom cilju. Nemoj samo kopirati svoj interni API kakav jest. Za svaki odabrani slučaj upotrebe napiši očekivani ishod, navedi potrebne informacije, identificiraj čitanja, pisanja i vanjske radnje, grupiraj ono što čini koherentnu radnju – i odvoji ono što se razlikuje po dozvolama, riziku ili potrebi za potvrdom.

OpenAI-jev primjer za dodatak za projekte:

  • list_projects za pronalaženje projekata;
  • get_project za ispitivanje jednog projekta;
  • create_project za stvaranje novog;
  • update_project za modificiranje detalja;
  • archive_project za promjenu stanja s visokim posljedicama.

Čitanja i pisanja su odvojeni kako bi model i korisnik mogli razlikovati konzultacije od modificiranja.

Ugovor svakog alata

PoljeDefinicija
NazivStabilan identifikator usmjeren na radnju
NaslovSažeta, ljudima čitljiva radnja
OpisKorisnikov cilj i uvjeti koji bi trebali pokrenuti alat
Shema ulazaObavezni i opcionalni parametri, vrste, dopuštene vrijednosti, ograničenja
Shema izlazaStrukturirana polja koja model može pregledati i ponovno upotrijebiti
AutorizacijaRačun, uloga ili pristup koje poslužitelj mora provjeriti
NuspojavePodaci ili vanjsko stanje koje alat može modificirati
NeuspjesiPogreške koje model može objasniti ili od kojih se može oporaviti

Tri pravila dopunjuju ovu tablicu. Eksplicitni ulazi: nemoj se oslanjati na model da pogodi ID ili opseg računa. Ponovno upotrebljivi izlazi: vrati stabilne ID-ove i dovoljno informacija za sljedeći poziv. Čisti izlazi: bez tajni, pristupnih tokena, interne dijagnostike ili nepotrebnih osobnih podataka.

Opisi napisani da budu odabrani

Model odabire alate na temelju njihovog opisa: opiši korisnikovu namjeru, a ne implementaciju. Dobar opis govori što alat radi, kada ga koristiti, kako se razlikuje od susjednih alata i koja su njegova ograničenja ili preduvjeti. Izbjegavaj one koji ponavljaju naziv alata ili koriste interni žargon koji tvoji korisnici ne poznaju.

Sigurnosne napomene

Svaki alat nosi napomene postavljene na temelju njegovog stvarnog ponašanja:

  • readOnlyHint je true samo ako alat ne može modificirati nikakvo stanje;
  • destructiveHint je true ako alat može proizvesti nepovratan ili teško poništiv rezultat;
  • openWorldHint je true ako alat pristupa javnom internetu ili otvorenim vanjskim entitetima, čak i ako je samo za čitanje, poput web pretraživanja. Privatni, ograničeni račun ili radni prostor nije „otvoren“ samo zato što je hostiran negdje drugdje.

Napomene pomažu ChatGPT-u i Codexu da odaberu odgovarajuću razinu potvrde, ali ne zamjenjuju autorizaciju na strani poslužitelja, validaciju ulaza ili potvrdu za važne radnje.

Plan koji služi kao plan testiranja

Zadrži popis i plan alata: oni postaju tvoj popis za provjeru. Dodaj izravne, neizravne, granične i izvan-opsega zahtjeve te provjeri ponaša li se gotovi dodatak kako se očekuje za svaki od njih. Također potraži alate koji ne služe nijednom dokumentiranom slučaju upotrebe, nedostajuća čitanja prije pisanja i opise koji su previše slični i koji bi mogli zbuniti model.

Ključne točke

  • Kreni od onoga što će korisnici očekivati, a zatim usporedi s onim što možeš sigurno pružiti
  • Popis od sedam pitanja po slučaju upotrebe, uključujući namjerna isključenja
  • Jedan alat po koherentnoj radnji; čitanja i pisanja su odvojeni
  • Jedan ugovor po alatu: naziv, naslov, opis, sheme, autorizacija, nuspojave, neuspjesi
  • Napomene (readOnlyHint, destructiveHint, openWorldHint) slijede stvarno ponašanje i ne zamjenjuju autorizaciju