Kā uzrakstīt specifikāciju, ar kuru AI aģents tiešām var strādāt

Ar AI aģentu bieži gadās viena un tā pati problēma: uzdevums cilvēkam šķiet pašsaprotams, bet rezultāts aiziet pavisam citā virzienā. Parasti specifikācijā vienkārši palicis pārāk daudz vietas minējumiem.

Garāks apraksts pats par sevi nepalīdz. Dažas skaidras prasības, pārbaudes komandas un robežas parasti ir vērtīgākas par piecām rindkopām ar projekta priekšvēsturi.

Sāc ar rezultātu, nevis tehnoloģiju sarakstu

Šāds uzdevums pasaka, ko izmantot, bet nepasaka, ko uzbūvēt:

Izveido React lietotni ar Node backend un PostgreSQL.

Labāk vispirms aprakstīt rezultātu:

Izveido tīmekļa lietotni, kurā lietotājs var pievienot uzdevumu, atzīmēt to kā izpildītu un izdzēst. Uzdevumiem jāsaglabājas arī pēc lapas pārlādes.

Pēc tam vari norādīt tehnoloģijas, esošo projekta struktūru un ierobežojumus. Šādā secībā aģents saprot, kam tehniskais risinājums ir paredzēts, nevis tikai mehāniski saliek kopā nosauktos rīkus.

Dod aģentam pārskatāmu darba karti

Specifikācijai nav vajadzīgas divdesmit sadaļas. Nelielam uzdevumam pietiek ar šādu struktūru:

## Mērķis
Pievienot esošajai lietotnei uzdevumu sarakstu.

## Prasības
- Lietotājs var pievienot uzdevumu.
- Lietotājs var atzīmēt uzdevumu kā izpildītu.
- Dati saglabājas pēc lapas pārlādes.

## Pārbaude
npm test
npm run build

## Robežas
- Nepievieno jaunas bibliotēkas bez saskaņošanas.
- Nemaini autentifikācijas kodu.
- Nekad nekomitē `.env` failu.

Svarīgākais te nav Markdown sintakse. Aģents atsevišķi redz vēlamo rezultātu, veidu, kā darbu pārbaudīt, un vietas, kurās tam nevajadzētu improvizēt.

Lielu darbu sadali pārbaudāmos posmos

“Izveido visu lietotni” ir ērts teikums, taču slikta darba vienība. Ja vienlaikus top datu modelis, API, saskarne un testi, kļūdu ir grūtāk pamanīt un vēl grūtāk saprast, kurā brīdī risinājums aizgāja greizi.

Praktiskāka secība būtu:

1. izveidot un pārbaudīt datu modeli;
2. pievienot vienu API galapunktu;
3. izveidot vienkāršu saskarni;
4. palaist testus un pārbaudīt visas prasības.

Katram posmam jābūt pietiekami mazam, lai tā rezultātu var apskatīt pirms nākamā soļa. Tas nenozīmē, ka aģents jāvada pa vienai koda rindai. Tam vienkārši vajag skaidrus kontrolpunktus.

Pasaki, ko drīkst darīt bez jautāšanas

AI aģents nevar uzminēt, kuras izmaiņas tavā projektā ir ikdienišķas un kuras — riskantas. To ir vērts uzrakstīt tieši:

• vienmēr palaid testus pirms darba pabeigšanas;
• pajautā pirms jaunas bibliotēkas vai datubāzes migrācijas pievienošanas;
• nekad nerediģē ģenerētos failus un neievieto repozitorijā slepenās atslēgas.

Šīs robežas ir īpaši svarīgas, ja aģents ne tikai piedāvā kodu, bet arī izpilda komandas un maina failus.

Definē, ko nozīmē “gatavs”

Frāze “pabeidz funkciju” katram var nozīmēt ko citu. Labāka pabeigšanas prasība ir konkrēta:

Darbs ir gatavs, kad visi trīs lietotāja scenāriji darbojas, esošie testi iziet un npm run build beidzas bez kļūdām. Beigās salīdzini rezultātu ar katru specifikācijas prasību.

Ja ir svarīgs pārlūka atbalsts, piekļūstamība vai vizuāls rezultāts, arī tam jābūt pārbaudāmo lietu sarakstā. “Izskatās labi” nav pārbaude. “Saskarni var lietot ar tastatūru” jau ir daudz tuvāk tai.

Atjaunini specifikāciju kopā ar prasībām

Ja uzdevumiem vēlāk parādās prioritāte, nepasaki to tikai nākamajā čata ziņā. Pievieno izmaiņu pašai specifikācijai:

Katram uzdevumam ir prioritāte: low, medium vai high. Esošajiem uzdevumiem noklusējuma vērtība ir medium.

Citādi drīz rodas divas patiesības: dokumentā ir vecā prasība, sarunā — jaunā. Aģents var izmantot abas, un rezultāts būs tikpat paredzams kā izstrāde ar divām atšķirīgām specifikācijām.

Es specifikāciju uztveru kā īsu vienošanos par rezultātu: ko būvējam, kā zināsim, ka tas darbojas, un kur aģentam jāapstājas un jāpajautā. Ja šīs trīs lietas ir skaidras, aģentam atliek mazāk minēt un vairāk izdarīt.