Секрет эффективного вайбкодинга — документация для нейросетей

Делаем документацию для ИИ-кода, в конце статьи будет 5 шаблонов, которые можно копировать и использовать для проектов.

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

Если вы читали историю о разработчике, который разочаровался в вайбкодинге спустя два года, то знаете: главная проблема — это накопленный техдолг и невозможность поддерживать созданное нейронкой. Но выход не в том, чтобы отказаться от ассистентов, а в том, чтобы научиться правильно документировать результат их работы.

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

Почему ИИ-код нужно документировать

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

ИИ-сгенерированный код создаёт пять специфических проблем:

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

Эти проблемы можно решить с помощью методологии D.O.C.S. и набора шаблонов документации.

Методология D.O.C.S.

D.O.C.S. расшифровывается как Design decisions, Operational context, Code understanding, Support information. Это четыре обязательных блока документации для ИИ-кода. Вы берёте уже готовый код от нейросети и описываете его по четырём блокам.

Design Decisions

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

Пример документирования решения об аутентификации:

			Решение: JWT-аутентификация с refresh-токенами
Рассмотренные альтернативы:
Session-based аутентификация — отклонена из-за проблем с масштабируемостью
Только OAuth — отклонена из-за избыточной сложности для текущего use case
Контекст промпта: Код аутентификации сгенерирован с ограничениями безопасности, требующими истечения токенов, механизма обновления и безопасного хранения
Заметки о верификации: Поток аутентификации проверен по стандартам OWASP с фокусом на обработку токенов

Operational Context

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

Требования окружения указываются точно:

			Node.js 16+.
Redis для хранения сессий.
PostgreSQL база данных

Конфигурация описывается в формате параметр-описание-значение по умолчанию-обязательность:

			JWT_SECRET — секретный ключ для подписи JWT — нет значения по умолчанию — обязательный параметр
DB_CONNECTION — строка подключения к базе данных — нет значения по умолчанию — обязательный параметр
REDIS_URL — URL подключения к Redis — localhost:6379 — необязательный параметр

Особенности деплоя записываются отдельно. Например, необходимость запуска миграций базы данных перед стартом приложения, наличие health check endpoint по адресу /health, реализация graceful shutdown с таймаутом 30 секунд.

Code Understanding

Этот блок объясняет неочевидные части кода.

Для сложных потоков данных используйте пошаговое описание. Пример документирования процесса аутентификации:

Пользователь отправляет credentials на /auth/login
Credentials валидируются против базы данных
При валидации генерируются два токена:
Access token — короткоживущий JWT с правами пользователя
Refresh token — долгоживущий токен, сохраняемый в Redis
Клиент использует access token для API-запросов
При истечении access token клиент использует refresh token для получения нового access token

Для ETL-процессов опишите последовательность шагов с ссылками на функции:

Получение сырых данных — см. ingestData()
Валидация и нормализация — см. normalizeRecords()
Применение бизнес-правил — см. applyBusinessRules()
Обработка транзакций базы данных — см. commitProcessedData()

Рекурсивные алгоритмы требуют отдельного объяснения. Пример с системой прав доступа:

Система прав использует рекурсивный алгоритм для вычисления эффективных разрешений. Права пользователя объединяются с правами групп. Группы могут быть вложенными, что требует рекурсивного разрешения. Права кешируются для производительности. Детали реализации в calculateEffectivePermissions().

Support Information

Симптом: Пользователи получают ошибку Invalid token несмотря на успешный логин

Возможные причины:

Расхождение времени между сервисами
Несоответствие JWT_SECRET между инстансами
Подмена токена

Шаги решения:

Проверить идентичность JWT_SECRET на всех инстансах
Проверить синхронизацию времени на серверах
Проверить payload токена на неожиданные модификации

Или Connection Pool Exhaustion

Симптом: Ошибки подключения к базе данных под нагрузкой

Причина: Размер пула подключений по умолчанию (10) недостаточен для production-нагрузки

Решение: Настроить переменную окружения DB_POOL_SIZE на основе результатов нагрузочного тестирования

Производительность документируется отдельно:

Функция поиска пользователей работает медленно на больших датасетах
Batch-обработка должна ограничиваться 1000 записями на job
Кеширование реализовано для проверки прав, но не для получения сущностей

Возможности для улучшения фиксируются для будущей работы:

Добавить пагинацию к endpoint списка пользователей
Реализовать кеширование на уровне сущностей
Мигрировать на TypeScript для улучшения type safety

Шаблоны документации

Советуем использовать шаблоны для разных этапов вайб-кодинга. Процесс работы с шаблонами выглядит так:

Генерируете код — пишете промпты, дорабатываете логику, пока не получите рабочий результат.
Выбираете шаблон.
Заполняете лично — описываете, что именно сделано, какой был промпт, какие альтернативы отбросили и почему.
Сохраняете в проект — фиксируете заполненный файл рядом с кодом или в общей базе знаний команды.

Ниже — пять готовых шаблонов, которые можно скопировать и использовать в работе.

Шаблон 1: Описание компонента

Самый важный шаблон. Заполняется один раз для каждого нового модуля

			# Компонент: [Название]
## Обзор
Зачем нужен этот компонент и что он делает.
## Данные об ИИ
- **Дата**: [дата]
- **Инструмент**: [например, Claude 3.5 или ChatGPT 4o]
- **Промпт**: [краткая суть промпта или ссылка на него]
## Архитектурные решения
Почему код написан именно так. Какие были альтернативы и почему их отбросили.
## Заметки по коду
- **Зависимости**: [внешние пакеты или другие модули]
- **Пример использования**:
```javascript
// Код вызова компонента

Шаблон 2: Тестирование и безопасность

Как проверяли код и есть ли специфические риски.

			### Шаблон 2: Лог работы с ИИ
Используйте этот шаблон, если нейросеть не выдала идеальный код с первого раза и пришлось дожимать.
# Лог разработки: [Название компонента]
## Начальный промпт
[Что вы попросили у ИИ в самом начале]
## История правок
- **Итерация 1**: [Что было не так и какой промпт использовали для исправления]
- **Итерация 2**: [Следующая правка, если была]
## Что пришлось править руками
Какие части кода ИИ выдал неверно и вы переписывали их самостоятельно.
## Чему научились
Инсайты по промптам: что сработало, а что нет.

Шаблон 3: Архитектурное решение (ADR)

Нужен для фиксации важных глобальных решений в проекте.

			# Архитектурное решение: [Заголовок]
## Статус
[В работе / Принято / Устарело]
## Контекст
Какую задачу или проблему мы решали этим выбором.
## Решение
Что именно решили сделать и как в этом участвовал ИИ.
## Последствия
- Плюсы: [что станет лучше]
- Минусы: [какие риски или ограничения появились]
## Как проверяли
Методика верификации решения.

Шаблон 4: Ревью кода от ИИ

Этот отчет заполняет коллега, который проверяет ваш PR с ИИ-кодом.

			# Ревью ИИ-кода: [Название]
## Общая оценка
- **Уровень риска**: [Низкий / Средний / Высокий]
- **Понимание требований**: [Насколько ИИ справился с ТЗ]
## Анализ по слоям
- **Логика**: [Есть ли ошибки в алгоритмах]
- **Безопасность**: [Нет ли дыр в защите или валидации]
- **Производительность**: [Будет ли это работать под нагрузкой]
## Замечания
Что нужно исправить перед мерджем.

Шаблон 5: Знания о реализации

Для передачи ИИ-кода коллегам или самому себе через полгода.

			# Детали реализации: [Название]
## Основные концепции
Кратко: как это устроено.
## Неочевидные моменты
Где в коде есть сложная логика.
## Границы ответственности ИИ
- Что сгенерировал ИИ полностью.
- Где была глубокая ручная модификация.
## Инструкция по поддержке
- Как это обновлять.
- Типичные ошибки и как их фиксить.
- Что точно нельзя трогать.

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

Для таких задач мы сделали RouterAI — API-шлюз для работы с нейросетями (ChatGPT, Claude, Gemini) в России и оплатой в рублях.