Определите проблему
Пример кода — фактическое утверждение о полях, значениях, порядке и поведении. Синтетический пример опасен, когда правдоподобные значения начинают обещать поведение продукта, которое никто не проверял и не гарантировал.
Выберите рабочую модель
Генерируйте внутри известных ограничений, уменьшая пространство для правдоподобных, но несуществующих свойств. Сначала получайте форму примера из известных схем или fixtures, а ИИ используйте только для подачи внутри этих ограничений.
Встройте в процесс
Проверяйте вне модели: тестами, парсерами, схемами, реальным выполнением или независимым ревьюером. Выдуманные имена и данные должны быть явно условными, чтобы читатель не принял их за реальные endpoints, accounts, limits или compatibility claims.
Проверьте результат
Особенно строго проверяйте ошибки: вымышленный error заставит пользователя обрабатывать поведение, которого нет. Исполняемые примеры запускайте автоматически, остальные вручную сверяйте с реальным окружением до публикации.
Сохраните сопровождаемость
Только проверенный пример становится обычной сопровождаемой документацией независимо от способа создания черновика. Если пример невозможно подтвердить, лучше упростить или удалить его: неполный правдивый пример безопаснее красивого вымышленного контракта.
Практический разбор
Проверьте «Синтетические примеры: полезный черновик и опасное доказательство» на контролируемой выборке до включения в рабочий процесс. Возьмите десять коротких фрагментов документации, правильное состояние которых вам уже известно: актуальные, устаревшие, неоднозначные и намеренно ошибочные. Дайте модели только разрешённую информацию, не меняйте инструкцию между запусками и фиксируйте не только удачные ответы, но и уверенные ошибки.
Разберите результат как редактор:
- отделяет ли модель факты от предположений;
- сохраняет ли терминологию и ограничения продукта;
- выдумывает ли недостающие сведения или скрывает неопределённость;
- может ли человек увидеть, что именно изменилось и почему.
Важен не вопрос «умеет ли модель писать гладкий текст», а вопрос «делает ли процесс ошибку видимой до публикации». Автоматизация заслуживает доверия, когда её границы, входные данные и точки человеческой проверки можно воспроизвести.
Короткий редакционный чек-лист
- Определите проблему. Пример кода — фактическое утверждение о полях, значениях, порядке и поведении.
- Выберите рабочую модель. Генерируйте внутри известных ограничений, уменьшая пространство для правдоподобных, но несуществующих свойств.
- Встройте в процесс. Проверяйте вне модели: тестами, парсерами, схемами, реальным выполнением или независимым ревьюером.
- Проверьте результат. Особенно строго проверяйте ошибки: вымышленный error заставит пользователя обрабатывать поведение, которого нет.
