Документация и код-ревью

Код пишется один раз, читается — сто

В Уроках 1-5 вы научились генерировать, рефакторить, тестировать и дебажить код. Но есть два навыка, которые разработчики откладывают больше всего: документация и код-ревью. Это как чистка зубов — все знают, что надо, но лень.

Почему документация важна:

— Вы сами через 3 месяца забудете, зачем написали эту функцию.
— Новый разработчик потратит неделю на понимание кода без документации — и 2 дня с ней.
— API без документации = API, которым никто не будет пользоваться.

Почему код-ревью важен:

— Второй взгляд находит 60% багов до продакшена.
— Код-ревью — обучение: младшие разработчики учатся у старших через ревью.
— Общий стандарт кода: без ревью у каждого свой стиль — проект превращается в зоопарк.

AI решает главную проблему: скорость. Написать README — 2 часа. AI — 5 минут. Сделать ревью 500 строк — 40 минут. AI — 3 минуты. Добавить JSDoc ко всем функциям — полдня. AI — 10 минут.

Два направления этого урока: Документация — README, API-docs, inline-комментарии, changelog, onboarding-гайды. Код-ревью — AI как «первый ревьюер», который ловит очевидные проблемы до человеческого ревью.

5 типов документации + AI как код-ревьюер

Тип 1: README проекта.
Промпт: «Вот структура проекта и ключевые файлы. Напиши README: описание, установка, запуск, структура папок, API-эндпоинты, переменные окружения, примеры использования.» AI создаёт README, которую не стыдно показать на GitHub — с бейджами, оглавлением и примерами кода.

Тип 2: API-документация.
Даёте AI код эндпоинтов: «Сгенерируй OpenAPI/Swagger документацию. Для каждого эндпоинта: метод, путь, описание, параметры (query/body/path), примеры запросов и ответов (200, 400, 404, 500).» AI учитывает edge-кейсы и коды ошибок.

Тип 3: Inline-документация.
«Добавь docstrings (JSDoc/Google-style) ко всем публичным функциям и классам в этом файле. Опиши: что делает, параметры, возвращаемое значение, возможные исключения, пример использования.» AI документирует 50 функций за 5 минут.

Тип 4: Changelog.
«Вот diff последних изменений (git diff). Напиши запись для CHANGELOG в формате Keep a Changelog: Added, Changed, Fixed, Removed. Пиши для пользователей, не для разработчиков.»

Тип 5: Onboarding-гайд.
«Вот структура проекта. Напиши гайд для нового разработчика: с чего начать, ключевые файлы, архитектурные решения, как запустить локально, как запустить тесты, куда смотреть при баге.»

AI как код-ревьюер:
Промпт-паттерн: «Сделай код-ревью этого PR. Проверь: 1) Безопасность — SQL-инъекции, XSS, утечки данных. 2) Производительность — N+1 запросы, лишние вычисления. 3) Читаемость — имена, структура, комментарии. 4) Тестируемость — можно ли протестировать этот код? 5) Архитектура — нарушения SOLID, лишние зависимости.»

AI не заменяет человеческий ревью — он его дополняет. AI ловит «механические» проблемы (стиль, типы, безопасность), человек — «смысловые» (правильная ли бизнес-логика, нужна ли эта фича).

Как документация от AI сократила онбординг с 3 недель до 4 дней

Ситуация: SaaS-продукт, 120,000 строк кода, команда из 8 разработчиков. Проблема: каждый новый разработчик тратил 2-3 недели на «вхождение» — просто чтобы понять, как всё устроено. Документация устарела 2 года назад.

План с AI (2 разработчика, 3 дня):

День 1: Прогнали все ключевые модули через AI — получили описание каждого модуля (что делает, зависимости, ключевые функции). AI сгенерировал карту зависимостей между модулями.

День 2: Сгенерировали API-документацию для всех 45 эндпоинтов (OpenAPI), inline-документацию для 200 публичных функций, README для каждого из 12 пакетов.

День 3: Создали onboarding-гайд: «Первый день», «Первая неделя», «Как дебажить типичные проблемы», «Архитектурные решения и почему они приняты».

Результат: следующий новый разработчик вошёл в проект за 4 дня вместо 3 недель. Сделал первый осмысленный PR на 5-й день. Команда ввела правило: AI-ревью перед человеческим ревью — количество «мелких» замечаний упало на 70%, ревьюеры сфокусировались на бизнес-логике.

Двойной промпт: документация + ревью

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

Ты — технический писатель с опытом документирования API и open-source проектов.

КОД/ПРОЕКТ:
[вставьте код или структуру проекта]

ТИП ДОКУМЕНТАЦИИ (выбери):
1. README — полное описание проекта для GitHub
2. API-docs — OpenAPI/Swagger для каждого эндпоинта
3. Inline — docstrings/JSDoc для всех публичных функций
4. Changelog — по diff/списку изменений
5. Onboarding — гайд для нового разработчика

АУДИТОРИЯ: [разработчики / пользователи API / менеджеры]

ТРЕБОВАНИЯ:
- Язык: [русский / английский]
- Формат: Markdown
- Включить: примеры использования, типичные ошибки, FAQ
- Тон: профессиональный, но не сухой

Ты — senior-разработчик, который проводит конструктивный код-ревью. Твоя цель — помочь автору улучшить код, а не критиковать.

КОД ДЛЯ РЕВЬЮ:
[вставьте код]

КОНТЕКСТ:
- Что делает этот код: [описание]
- Стек: [язык, фреймворк]

ПРОВЕРЬ:
1. 🔴 Безопасность — инъекции, утечки данных, небезопасные операции
2. 🟡 Производительность — N+1, лишние вычисления, неоптимальные алгоритмы
3. 🔵 Читаемость — имена, структура, комментарии, форматирование
4. 🟢 Тестируемость — можно ли покрыть тестами, есть ли побочные эффекты
5. ⚪ Архитектура — SOLID, связанность, повторное использование

ФОРМАТ ОТВЕТА:
Для каждого замечания: [🔴/🟡/🔵/🟢/⚪] серьёзность + строка + проблема + предложение
В конце: общая оценка 1-10 и ТОП-3 приоритетных исправления

Мысль дня

Документация — это подарок себе из будущего. Код-ревью — это подарок команде из настоящего. AI делает оба подарка дешёвыми — пользуйтесь.

Задокументируйте и отревьюьте свой код

Сегодня вы применяете оба промпта на практике. Задание из трёх шагов — от документации до итеративного улучшения кода: