Як перевірити специфікацію, написану ШІ:чек-лист до початку роботи агента.

Чому специфікаціям від ШІ потрібна інша перевірка

Людина, що пише специфікацію, зазвичай лишає прогалини там, де не впевнена. Модель пише гладкий текст про все, зокрема про те, що вона вгадала. Тому звичних ознак слабкої специфікації, розпливчастих формулювань і очевидних дір, немає, а проблеми сховані в упевнених реченнях. Перевіряйте те, про що спитав би хороший автор.

Чек-лист

1. Обсяг: чи розв'язує вона те, про що ви просили?

   Порівняйте перший абзац зі своїм запитом. Шукайте розв'язання іншої задачі та функції, про які ніхто не просив.

2. Не-цілі: чого вона не робитиме?

   У специфікації без не-цілей немає меж. Додайте зайве, чого ви не хочете.

3. Припущення: що вона вгадала?

   Шукайте «імовірно», «напевно» і все, що подано як факт про код чи дані, яких вона могла не читати. Попросіть указати файли.

4. Крайні випадки: що буде, якщо щось піде не так?

   Порожній ввід, дуже великий ввід, немає прав, немає мережі, двоє користувачів одночасно, та сама дія двічі.

5. Дані: що зберігається, змінюється чи видаляється?

   Поля, формати, хто може їх читати і що буде з наявними записами.

6. Міграції: як переносяться старі дані?

   Зміні схеми потрібні порядок кроків, план на випадок збою на півдорозі та можливість безпечно запустити її двічі.

7. Інтерфейси: що ще зачіпається?

   API, екрани, завдання, чужий код. Усе, що специфікація змінює, але не перелічує, потім стане сюрпризом.

8. Безпека й приватність: хто що може робити?

   Нові права, нові дані, що йдуть із системи, секрети в логах.

9. Тести: як ви дізнаєтеся, що це працює?

   Кожній вимозі має відповідати перевірка. Якщо вимогу не можна протестувати, перепишіть її.

10. Випуск і відкат: як це скасувати?

    Прапорець, поетапний випуск, шлях назад. «Виправимо вперед» — не план.

11. Відкриті питання: хто їх вирішує?

    Чесна специфікація перелічує, чого не знає. Якщо питань немає, будьте підозріливі.

Коментар, який працює

Розпливчастий відгук дає розпливчасте переписування. Хороший коментар рев'ю вказує на одне місце, каже, що не так і що ви хочете натомість:

> The export runs when the user taps Export.

Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.

Тримайте коментарі окремо від тексту специфікації, щоб файл лишався чистим, і збирайте їх пакетом: спершу прочитайте всю специфікацію, потім коментуйте, щоб агент переписав її один раз, а не десять.

Цикл рев'ю

1. Спершу прочитайте від початку до кінця

   Перш ніж коментувати, переконайтеся, що розумієте весь план.

2. Коментуйте точні місця

   Одна проблема — один коментар.

3. Нехай агент виправить

   Він виправляє кожен коментар і видає нову версію.

4. Дивіться, що змінилося, а не весь документ

   Читайте відмінності. Виправлення може зламати те, що було гаразд.

5. Схвалюйте, лише коли чек-лист чистий

   Тоді нехай будує, спираючись на пронумеровані вимоги.

Той самий чек-лист працює, коли один агент перевіряє специфікацію іншого. Попросіть рев'юера відповідати на кожен пункт цитатою зі специфікації.

Як це зробити в DotMD

Усе це можна зробити просто на сторінці. У DotMD ви виділяєте місце й пишете до нього коментар; коментарі зберігаються в DotMD, а не у файлі. Агент їх виправляє та надсилає документ знову, а перегляд змін показує старий текст червоним і новий зеленим, щоб ви приймали їх по одному. Налаштування описано в статті рев'ю ШІ-специфікацій. Читання безкоштовне; про рев'ю див. ціни.

Часті помилки

• Перевірка стилю, а не суті. Охайна специфікація все одно може бути хибною.
• Схвалення за обсяг. Довжина — не охоплення.
• Пропуск не-цілей і відкату, двох розділів, які моделі найчастіше пишуть скупо.
• Правка коду замість специфікації. Якщо план хибний, спершу виправте його.
• Немає другого погляду. Після правок агента перевірте diff.

Питання про перевірку специфікацій, написаних ШІ

Інші запитання