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

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

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

Ако спецификацијата е нејасна, AI често ќе ги пополни празнините со уверливи стандардни решенија:

• вообичаени архитектонски обрасци
• генерички UI текови
• непотребни апстракции
• измислени претпоставки за тоа што треба да прави производот

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

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

1. Цел на производот

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

Лошо:

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

Подобро:

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

Целта му кажува на имплементаторот за што треба да оптимизира.

2. Граници на опсегот

Наведете што е во опсег, а што е надвор од опсегот.

Пример:

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

Ова го спречува асистентот да ја надуе малата задача во мини-платформа.

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/mk/spec-driven-development.md
• ../wiki/mk/demo-spec-alignment.md
• ../blog/mk/spec-driven-development-for-ai-projects.md