Как проверить спецификацию, написанную ИИ:чек-лист до начала работы агента.

Почему спецификациям от ИИ нужна другая проверка

Человек, пишущий спецификацию, обычно оставляет пробелы там, где не уверен. Модель пишет гладкий текст обо всём, включая то, что она угадала. Поэтому привычных признаков слабой спецификации, расплывчатых формулировок и очевидных дыр, нет, а проблемы спрятаны в уверенных предложениях. Проверяйте то, о чём спросил бы хороший автор.

Чек-лист

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.

Вопросы о проверке спецификаций, написанных ИИ

Другие вопросы