Kā uzrakstīt labu specifikāciju AI aģentam

Rakstot specifikāciju AI aģentam, lielākā kļūda nav tehniska, tā ir domāšanas kļūda. Mēs bieži domājam: “Jo vairāk paskaidrošu, jo labāk.” Taču ar valodas modeļiem tas strādā citādi. Ja iedod pārāk daudz nestrukturētas informācijas, modelis sāk ignorēt daļu prasību vai sajauc prioritātes. Laba specifikācija nav gara. Tā ir skaidra, strukturēta un fokusēta.

Strādājot ar rīkiem kā Claude Code vai Gemini CLI, ļoti ātri kļūst skaidrs, AI nav maģija. Tas ir jaudīgs, bet tas ir jāvada.

Zemāk, praktiska, sabalansēta pieeja ar vienkāršiem piemēriem.

1. Sāc ar skaidru mērķi, nevis ar tehniskām detaļām

Specifikācijai jāsākas ar “kāpēc” un “ko”, nevis ar “kā”.

Tā vietā, lai rakstītu:

Izveido React aplikāciju ar Node backend un PostgreSQL.

Sāc šādi:

Izveido web aplikāciju, kur lietotāji var pievienot un atzīmēt uzdevumus kā izpildītus. Datiem jāsaglabājas arī pēc pārlādes.

Šis formulējums nosaka mērķi. Tehnoloģijas var pievienot nākamajā solī.

Kad mērķis ir skaidrs, vari lūgt AI izveidot detalizētāku plānu. Šajā brīdī tu joprojām kontrolē virzienu, bet ļauj modelim strukturēt detaļas.

2. Strukturē dokumentu — AI mīl skaidras sadaļas

AI daudz labāk strādā ar strukturētu tekstu nekā ar brīvu aprakstu. Iedomājies, ka raksti instrukciju ļoti burtiskam kolēģim.

Vienkārša struktūra var izskatīties šādi:

## Mērķis
Vienkārša uzdevumu aplikācija.

## Funkcijas
- Pievienot uzdevumu
- Atzīmēt kā izpildītu
- Dzēst uzdevumu

## Komandas
npm test
npm run build

## Robežas
- Nekad nekomitē .env failus
- Pirms datubāzes maiņas pajautā

Nav jābūt 20 sadaļām. Bet dažas skaidras nodaļas jau būtiski uzlabo rezultātu.

Balstoties uz GitHub analīzi, tieši skaidras komandas, testēšana un robežas ir tās lietas, kas visvairāk palīdz aģentiem darboties pareizi.

3. Nesaliec visu vienā gigantiskā promptā

Ja projekts ir lielāks par pāris failiem, necenties visu izdarīt vienā reizē.

Slikts piemērs:

Izveido pilnu aplikāciju ar autentifikāciju, API, UI un testiem.

Labāks variants:

  1. “Izveido datu modeli uzdevumiem.”
  2. “Tagad izveido API endpoint uzdevuma pievienošanai.”
  3. “Tagad izveido vienkāršu UI saraksta attēlošanai.”

Katrs solis ir konkrēts un pārskatāms. Tas uzlabo kvalitāti un samazina kļūdu skaitu.

4. Definē robežas (ļoti svarīgi)

AI ne vienmēr zina, kur beidzas droša darbība un sākas riskanta.

Vienkārša trīs līmeņu sistēma strādā lieliski:

Vienmēr dari:

  • palaid testus pirms commit

Pajautā vispirms:

  • pirms jaunu bibliotēku pievienošanas

Nekad nedari:

  • nekomitē slepenās atslēgas
  • nerediģē node_modules

Šāda skaidrība novērš daudz problēmu.

5. Iekļauj nelielu pašpārbaudi

Vari prompta beigās pievienot vienu teikumu:

Pēc ieviešanas pārbaudi, vai visas prasības no šīs specifikācijas ir izpildītas.

Tas bieži liek modelim pašam pamanīt, ja kaut kas ir aizmirsts.

6. Neaizmirsti savu pieredzi

Ja tu zini, ka:

  • konkrēta bibliotēka rada problēmas,
  • jāizmanto konkrēts arhitektūras princips,
  • jāievēro uzņēmuma standarti, tad

uzraksti to. AI neuzminēs tavas iekšējās vadlīnijas.

Specifikācija ir vieta, kur tu ieliec savu domāšanu. AI tikai izpilda.

7. Uztver specifikāciju kā dzīvu dokumentu

Specifikācija nav statiska. Ja prasības mainās, atjaunini to un tikai tad pielāgo kodu.

Piemēram:

Atjauninājums: uzdevumiem jāpievieno prioritāte (low, medium, high).

Šī viena rindkopa var būtiski mainīt datu modeli un UI. Ja to nepievienosi specifikācijai, AI turpinās balstīties uz veco versiju.

Noslēgumā

Laba AI specifikācija:

  • sākas ar skaidru mērķi,
  • ir strukturēta, bet ne pārlieku sarežģīta,
  • sadala darbu mazākos posmos,
  • definē robežas,
  • iekļauj nelielu kvalitātes kontroli,
  • tiek regulāri atjaunināta.

Domā par AI kā ļoti ātru, bet burtisku junior izstrādātāju. Ja uzdevums ir skaidrs, rezultāts būs labs. Ja instrukcijas ir haotiskas, rezultāts būs haotisks.

Jo labāka specifikācija, jo mazāk “kāpēc tas tā izdarīja?” brīžu vēlāk. 🚀