Можно ли доверять документации, которую сгенерировал кодовый агент?

#В чём именно проблема

Документация, написанная человеком, несёт неявный сигнал: кто-то счёл это достойным своего времени и что-то об этом знал. Она часто неверна, и у её неверности есть фактура — она устарела или расплывчата там, где автор был не уверен.

У сгенерированной документации такой фактуры нет. Она равномерно уверенна, равномерно подробна и равномерно хорошо написана — независимо от того, прочитано ли лежащее в основе утверждение из кода или выведено из соглашения об именовании. Расплывчатости, сигнализирующей о неуверенности, нет, потому что неуверенности не было в письме — она была в знании.

#Как проверить её за час

1. Возьмите пять проверяемых фраз

   Конкретных: «платежи повторяются трижды», «выгрузка идёт в 02:00», «аутентификация по bearer-токену, который выдаёт витрина». Не «система модульная».

   Фраза, которую нельзя проверить, не утверждение, а украшение, и её надо удалить, а не проверять.

2. Сверьте каждую с кодом

   Откройте файл. Прочитайте строки. По каждой запишите: верно, неверно или сказать нельзя.

3. Оцените

   Пять из пяти верны: вероятно, стоит держать и стоит перепроверить после следующего крупного изменения. Три-четыре: держите, пометьте как непроверенное и проверьте остальное. Две и меньше: это гипотеза, а не документ.

4. Проверьте пустоты

   О чём она не упоминает? Задачи по расписанию, внешние интеграции и обработка сбоев — три вещи, которые сгенерированная документация чаще всего опускает целиком, потому что в читанном ею коде они наименее заметны.

1. «Неудачные платежи повторяются трижды.»
   → ВЕРНО.  app/Jobs/SettlePayment.php:22  $tries = 3

2. «Повторы используют экспоненциальную задержку.»
   → СКАЗАТЬ НЕЛЬЗЯ. Задержка нигде не настроена. По умолчанию
     во фреймворке она может быть экспоненциальной; документ
     подаёт это как факт.

3. «Все API-эндпоинты требуют аутентификации.»
   → НЕВЕРНО.  Два маршрута в routes/api.php находятся вне
     группы auth-мидлвара. Один из них принимает запись.

4. «Ночная выгрузка пишет в S3.»
   → СКАЗАТЬ НЕЛЬЗЯ. Назначение берётся из EXPORT_DEST, который
     в этом репозитории не задан.

5. «Система использует PostgreSQL.»
   → ВЕРНО.

Итог: 2 верны, 1 неверна, 2 непроверяемы.
Вердикт: гипотеза. Утверждение 3 — живая проблема, найденная
скептическим чтением документа, а не пользованием им.

#Что оставить и как это пометить

Три состояния, и каждая страница должна быть ровно в одном из них:

• Проверено — кто-то сверил эти утверждения, в такую-то дату. Имя и дата на странице. Это единственное состояние, в котором по документу можно действовать без дополнительной проверки.
• Не проверено — сгенерировано и не сверено. Держите, если это полезно для ориентировки, и скажите об этом одной строкой сверху: «Сгенерировано, не проверено. Проверяйте всё, по чему собираетесь действовать.»
• Удалено — проверить нельзя или проверили и оказалось в основном неверно. Удалять документацию кажется расточительным и обычно правильно: страница, вводящая в заблуждение, стоит дороже пустого места, которое она занимала.

Пометка важнее содержания. Читатель, знающий, что страница не проверена, пользуется ею как отправной точкой; тот же читатель с той же страницей без пометки пользуется ею как ответом.

#В чём сгенерированная документация действительно хороша

Эта страница скептична, а не враждебна. Три вещи она делает хорошо, и их стоит иметь:

• Ориентировка. Новому человеку нужно примерно понимать, где что лежит, прежде чем он сможет задать хороший вопрос. Сгенерированный обзор для этого годится — при условии, что по нему никто не принимает решений.
• Покрытие скучных частей. Описание каждого модуля руками не написал бы никто и никогда. Сгенерированное покрывает длинный хвост, который иначе остался бы пустым.
• Черновик, который правят. Исправить неверное описание намного быстрее, чем написать его, и настоящее знание оседает именно в исправлениях.

Провал не в том, что её сгенерировали. Провал в том, что сгенерировали, а потом обошлись с результатом так, будто кто-то его проверил.

#Более удачное устройство

Вместо того чтобы генерировать прозу о системе, генерируйте её структурированное описание, несущее три вещи, которых проза нести не может:

1. Указатель под каждым утверждением — файл и строки, откуда оно взялось, либо явная пометка, что это вывод.
2. Раздел с неизвестным, который не пуст. Что установить не удалось и почему.
3. Заявление об охвате — на что реально смотрели и что пропустили.

Это та же работа и другая форма результата, и она убирает ровно то свойство, которое делает сгенерированную документацию опасной: теперь видно, какие утверждения прочитаны, а какие угаданы. Доказательства объясняют, почему это различение главное, а Evidence Package — один конкретный способ его закодировать.

#Что идёт не так

#Чего это не покрывает