Без документации ИИ далеко не уедет: мои грабли на проекте

Это продолжение статьи “ИИ может писать код, но умеет ли он делать красиво? Мой опыт с виджетом и аватарами” ^[1].

На этой неделе я побывал в телеграм-клубе AI Practiq, где ребята собираются, обсуждают вайбкодинг, делятся опытом ^[2] и практиками.

Один из участников рассказывал о своём опыте и выделил четыре важных аспекта качественной разработки с ИИ. Один из них – документация.

Это очень точно совпало с моими ощущениями.

ИИ не должен работать по принципу First Code. Ему нужно понимать цели, задачи, ограничения, архитектуру, граничные случаи и конечный результат.

К тому моменту я уже дал Claude Code много указаний. Где-то были рефакторинги, где-то менялись продуктовые решения, где-то появлялись новые требования. Документация начала отставать от реальности.

Я решил привести её в порядок. И неожиданно на это ушло почти три часа активного вайбкодинга.

Просил ИИ задавать все вопросы, которых ему не хватает для понимания. В том числе про граничные случаи. Мы обсуждали сложные сценарии, устраняли противоречия между старыми и новыми решениями, фиксировали финальные правила.

В итоге ИИ сгенерировал актуальную документацию, которая потом очень сильно облегчила дальнейшую разработку.

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

ИИ додумал сам, но я всё равно проверил

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

В какой-то момент вижу в чате, что Claude Code пишет про хранение данных в Prometheus.

Я спрашиваю: “когда ты решил подключить Prometheus?”

Он отвечает: “ты говорил про дашборд с метриками, и я решил использовать Prometheus”

Решение, в целом, хорошее. Я его одобрил.

Но дальше мы отдельно прошлись по тому, какие метрики собираются, сколько они хранятся, как устроены ограничения, что пишется в Redis и какие TTL стоят на ключах.

Это важный момент.

Если ИИ использует Redis, я всегда прошу проверить TTL (Time to Live). Какие значения, где зафиксированы, что будет с брошенными данными. Redis не должен однажды превратиться в кладбище временного мусора кэшированных данных, которое никто не чистит.

С PostgreSQL то же самое. Я регулярно спрашивал, какие данные хранятся, в каких таблицах и колонках. Иногда мне не нравилась структура, и я просил рефакторить.

При этом сам я ещё не лез руками в таблицы. ИИ откатывал миграции, накатывал заново, база очищалась. Потом я снова тестировал регистрацию и внезапно понимал: ага, войти не могу, потому что база данных после php artisan migrate:refresh пустая и нужно зарегистрироваться заново.

Это, конечно, весело. Но зато очень быстро.

Следующая часть называется “Как я собирал рабочее окружение для ИИ-разработки” ^[3]

Приглашаю в мой Telegram-канал ^[4], в котором показываю детали реализации, ссылки на продукты, которые вайбкожу, и практические находки, которые не всегда помещаются в статьи на Хабре.