Како написати спецификацију коју AI може да прати

Сажетак

Овај водич објашњава како да напишете спецификацију производа или функционалности тако да имплементација уз помоћ AI остане усклађена са стварним циљевима производа, уместо да склизне ка генеричком излазу.

Зашто је то важно

AI може брзо да генерише код, али најбоље ради када задатак има јасне границе.

Ако је спецификација нејасна, AI ће празнине често попунити уверљивим подразумеваним изборима:

• уобичајеним архитектонским обрасцима
• генеричким токовима корисничког интерфејса
• непотребним апстракцијама
• измишљеним претпоставкама о томе шта производ треба да ради

Такав излаз може деловати углађено, а ипак бити погрешан.

Шта корисна спецификација за AI треба да садржи

1. Сврху производа

Реците зашто функционалност постоји.

Лоше:

Додај форму за књигу.

Боље:

Додај образац за брзи унос који омогућава донатору да за неколико секунди каталогизује један физички примерак књиге док стоји поред полице или кутије.

Сврха имплементатору јасно показује шта треба да оптимизује.

2. Границе обима

Наведите шта је у обиму, а шта ван обима.

Пример:

• у обиму: фотографија корице, унос ISBN-а, локација складиштења, сачувај и настави
• ван обима: OCR, синхронизација у облаку, ток институционалног прегледа

То спречава асистента да мали задатак непотребно претвори у мини платформу.

3. Захтевано понашање

Наведите правила о којима нема преговарања.

Примери из приступа Let Books:

• ручни ток рада мора да функционише без AI-ја
• непотпуни подаци морају бити дозвољени
• физички примерци морају остати одвојени од библиографских записа
• кориснички видљиво понашање мора остати локализабилно

Ова правила су важнија од стила имплементације.

4. Понашање при грешци и резервно понашање

Решења која генерише AI често оптимизују срећан пут. Добра спецификација објашњава шта се дешава када опциони системи закажу.

Пример:

• ако претрага метаподатака не успе, ручни унос остаје доступан
• ако је OCR искључен, унос и даље ради
• ако валидација извоза не успе, корисник добија јасан извештај уместо тихог делимичног увоза

5. Критеријуми прихватања

Напишите услов успеха у видљивим терминима.

Пример:

1. корисник бира кутију
2. корисник уноси или скенира ISBN
3. корисник може да сачува чак и ако ниједан провајдер метаподатака не одговори
4. књига се појављује на изабраној локацији

Критеријуми прихватања дају прегледаоцима и AI системима стабилан циљ.

Шта треба избегавати

• нејасне циљеве као што је „побољшај UX“
• детаље имплементације без сврхе производа
• помешане будуће идеје представљене као тренутне захтеве
• скривене претпоставке о улогама корисника или квалитету података
• спецификације које садрже само називе, а не описују ток рада

Практичан образац за писање

Користите ову сажету структуру када пишете спецификацију функционалности.

1. проблем
2. корисник и контекст
3. ток рада у обиму
4. ставке ван обима
5. захтевана правила
6. резервно понашање
7. критеријуми прихватања
8. напомене за верификацију

Како се ово мапира на Let Books

Репозиторијум већ приказује овај образац на више нивоа:

• AGENTS.md дефинише сврху производа, токове рада и критеријуме прихватања
• AGENTS-Implementation.md дефинише тактичка ограничења испоруке
• README.md раздваја тренутно стање од будућег правца

Тај слојевити приступ је користан јер AI ради боље када су правила и памћење о производу записани јасно и прегледно.

Вежба

Узмите једну функционалност Let Books, као што је скенирање QR кода кутије или увоз одлука из Excel-а, и напишите једнострану спецификацију користећи горњу структуру.

Затим замолите помоћника за кодирање да је имплементира.

После тога прегледајте излаз у односу на спецификацију пре него што прегледате стил кода. Тај редослед је важан.

Даље читање

• ../spec-driven-content-program.md
• ../wiki/sr-Cyrl/spec-driven-development.md
• ../wiki/sr-Cyrl/demo-spec-alignment.md
• ../blog/sr-Cyrl/spec-driven-development-for-ai-projects.md