Как разобраться в коде, который написал кодовый агент?

#Что здесь на самом деле другое

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

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

• Устаревшую документацию чинить не надо. Часто есть много сгенерированной документации, и ничего из неё никто не проверял.
• Винить ушедшего эксперта не в чем. Люди на месте; они это тоже не читали.
• Код нередко в порядке. Отчего к ситуации труднее отнестись серьёзно, чем она заслуживает.
• Системе может быть несколько недель. Возраст здесь ни при чём.

#Метод

1. Получите явную опись

   Компоненты, зачем каждый, что от чего зависит. Выведенную из системы, а не из воспоминаний — которых в этой ситуации на удивление мало.

2. Требуйте различения «прочитано / выведено»

   Агент, объясняющий систему, выдаёт наблюдённые и выведенные утверждения одинаковой прозой. Настаивайте, чтобы каждое утверждение называло файл и строки, из которых взялось, — либо было помечено как вывод.

   Одно это требование и отличает полезное описание от гладкого.

3. Проверьте сгенерированную документацию

   Возьмите пять конкретных утверждений из любого README или проектной заметки и сверьте каждое с кодом. Там, где они расходятся, чья-то картина мира уже неверна.

4. Проследите денежный путь от начала до конца

   Платёж, заказ, регистрация — что коммерчески критично. Пройдите от точки входа до базы, включая то, что происходит при сбое на каждом шаге.

   Несчастливый путь — это то, что генерируется, а не проектируется, и там быстрые сборки слабее всего.

5. Проверьте внешние границы

   Каждый входящий вебхук: проверяет ли он, кто его прислал? Каждый исходящий вызов: повторы, таймауты и безопасно ли его повторять. Именно здесь правдоподобная реализация и правильная больше всего похожи.

6. Найдите дублирующиеся подходы

   Три реализации одной идеи — характерная подпись. Каждая обычно нормальна; цена в том, что изменение придётся вносить трижды, а кто-то внесёт его дважды.

7. Запишите, что установить не удалось, и перепроверьте после следующего пуша

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

#Как отделить прочитанное от выведенного

Единственная дисциплина, которая важнее всего, — и та, которой по умолчанию не делает ничто.

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

Для читателя, который не может их различить, это не мелочь: он примет решение, зависящее от того, из какой половины пришла фраза, не имея способа это выяснить.

БЕЗ различения

  «Неудачные платежи повторяются трижды с экспоненциальной
   задержкой, после чего помечаются как неуспешные.»

С различением

  УТВЕРЖДЕНИЕ  Неудачные платежи повторяются трижды.
  ПЕРСПЕКТИВА  Наблюдено
  ДОКАЗ-ВО     app/Jobs/SettlePayment.php:22   ($tries = 3)

  УТВЕРЖДЕНИЕ  Повторы используют экспоненциальную задержку.
  ПЕРСПЕКТИВА  Выведено — по умолчанию во фреймворке она
               экспоненциальная, и задержка нигде не настроена.
               Напрямую не прочитано.

  НЕИЗВЕСТНО   Что происходит после третьего сбоя? Обработчик
               не найден.                                ВЫСОКИЙ

#Следы, которые оставляет быстрая работа агента

Ни одно из этого само по себе не дефект. Искать стоит всё, потому что они ходят группами.

• Три решения одной задачи. Разные сессии решали одно и то же по-разному, и каждое локально разумно.
• Тщательные счастливые пути и тонкие несчастливые. Что происходит, когда провайдер отваливается по таймауту, очередь копится или один и тот же запрос приходит дважды.
• Настройки, которые есть и которые никто не читает, — или читаются из двух мест с разными значениями по умолчанию.
• Обширные комментарии, описывающие предыдущую версию функции, над которой стоят.
• Тесты, проверяющие реализацию, а не требование, и поэтому проходящие при любом поведении кода.
• Зависимости, добавленные ради одного использования и не убранные.
• Сгенерированная документация: гладкая, обширная, непроверенная.

#Как использовать агента, чтобы он объяснил собственную работу

Это работает хорошо и является самым быстрым путём к картине. Три вещи, на которых надо настоять, иначе получится проза, а не описание:

1. Указатель под каждым утверждением. Файл и диапазон строк — либо явная пометка, что это вывод.
2. Непустой раздел с неизвестным. Агент, который не сообщил ни об одном сомнении, заполнил дыры и перестал их отличать.
3. Заявление об охвате. На что он реально смотрел и что пропустил. Без этого нельзя отличить полную картину от частичной.

Ровно эти три требования и кодирует формат Evidence Package у 1ADK, и ничто не мешает команде потребовать того же самого самостоятельно.

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

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