Резюме
Это пример применения методологии на основе открытых отраслевых данных. Цифры рассчитаны по публичным источникам — ваши результаты и декомпозиция процесса на блоки будут зависеть от конкретных условий.
Ситуация. Команда 10 разработчиков. API 50+ endpoints. OpenAPI spec устарел на 40% (функции добавлены, но документация не обновлена).
Проблема. Онбординг долгий: новичок 1–2 недели разбирается в коде (когда документация 3+ месяца давности) — скрытые затраты ~80 ч/год на одного новичка API-клиенты теряются: frontend-разработчик не знает, изменился ли endpoint → интеграция сломана, отладка занимает 4–8 ч Техдолг в документации: обновляешь функцию — забываешь обновить docstring/spec; постоянное отставание на 40% endpoints
Результат анализа. 2 блока — в 🟢 Автоматизация (EPOCH 1–2). 1 блок — в 🟡 Усиление (EPOCH 3). 1 блок — в 🟠 Коллаборация (EPOCH 4). Экономия труда — до 73 788 ₽/год (Москва). Главный эффект — охват: с 10% до 100% функций задокументировано.
Карта процесса
Процесс разбит на 4 блоков.
- 1 Сгенерировать docstring для функций и классов Автоматизация
- 2 Сгенерировать примеры кода для API-эндпоинтов Автоматизация
- 3 Обновить OpenAPI spec по актуальному коду Усиление
- 4 Написать архитектурную документацию для ключевых компонентов Коллаборация
Итого: 2 шага в 🟢 Автоматизация (EPOCH 1–2), 1 шаг в 🟡 Усиление (EPOCH 3), 1 шаг в 🟠 Коллаборация (EPOCH 4).
Проверка готовности
Все четыре ответа должны быть «Да» — тогда можно переходить к внедрению.
- Разработчик может проверить автогенерированный docstring на соответствие реальному поведению функции?
- Инструменты (Claude API, git hooks) и доступ к коду доступны за 1–2 недели?
- Руководство поддерживает внедрение ИИ в процесс документирования кода?
- Команда осознаёт, что долгосрочное делегирование документирования снижает способность замечать расхождения между кодом и docs?
Анализ
Таблица блоков
EPOCH (MIT Sloan, Loaiza & Rigobon, 2025) — шкала 1–5: насколько задача требует человеческого участия. Оценка = максимум из пяти параметров.
«Готовность ИИ-инструмента» определяет стартовый уровень контроля: чем больше опыта у команды с этой связкой «задача + инструмент», тем меньше проверок нужно с первого дня. Новый — команда ещё не делала этот тип задач с этим инструментом, уровень контроля 1. Пробуем — 1–2 цикла, результат ещё нестабильный, уровень 1–2. Стабильный — 3+ цикла без ошибок, уровень 2–3. Доказанный — 8+ циклов, уровень 3–4. Прочерк — блок не передаётся ИИ, оценка неприменима.
| # | Блок | Зависит от | EPOCH | Зона | Описание | Готовность ИИ-инструмента |
|---|---|---|---|---|---|---|
| 1 | Сгенерировать docstring для функций и классов | исходный код, тесты | 1 | Автоматизация | Генерирует docstring для каждой функции в Google/NumPy формате из кода и тестов, до проверки разработчика | Стабильный |
| 2 | Сгенерировать примеры кода для API-эндпоинтов | Блок 1, тесты | 2 | Автоматизация | Создаёт примеры использования функций из unit-тестов, до публикации в документации | Стабильный |
| 3 | Обновить OpenAPI spec по актуальному коду | PR с изменениями | 3 | Усиление | Обновляет OpenAPI spec по изменениям в коде endpoints, до проверки backend разработчика | Пробуем |
| 4 | Написать архитектурную документацию для ключевых компонентов | кодовая база, ADR | 4 | Коллаборация | Готовит черновик архитектурного описания модуля, если разработчик передал контекст решений | — |
Почему такие оценки
| # | Блок | EPOCH | Обоснование |
|---|---|---|---|
| 1 | Сгенерировать docstring для функций и классов | 1 | Детерминированное извлечение: сигнатура + тело функции → стандартный формат. Суждение и контекст не нужны. |
| 2 | Сгенерировать примеры кода для API-эндпоинтов | 2 | Алгоритмическое преобразование тестов в примеры: ИИ адаптирует assert-выражения в читаемые примеры. Minimal суждение о стиле (Stack Overflow Survey, 2024). |
| 3 | Обновить OpenAPI spec по актуальному коду | 3 | Требует суждения (O=3): нужно понять, изменилось ли поведение endpoint или только реализация. ИИ может ошибиться без знания бизнес-контракта. |
| 4 | Написать архитектурную документацию для ключевых компонентов | 4 | Высокое суждение (O=4): архитектурные компромиссы («почему именно так») — это история решений, которую ИИ не знает без явной передачи (Fern, 2026). |
Ограничения ChatGPT в этом процессе
- Не знает намерения разработчика: почему функция реализована именно так — контекст архитектурного решения остаётся вне PR (Stack Overflow Survey, 2024)
- Генерирует happy path без граничных случаев: edge cases и известные баги ИИ не знает без явной истории (Codacy, 2024)
- Архитектурная документация требует суждения об архитектурных компромиссах (O=4) — ИИ не знает, почему выбрана именно эта структура (Fern, 2026)
- Командные конвенции ИИ не знает без явной передачи контекста: «как принято у нас» нужно описывать каждый раз (Stack Overflow Survey, 2024)
Инструкции для передачи задач ИИ
Чтобы передать задачу ИИ, нужно описать три вещи: что подаёте на вход, что получаете обратно и как поймёте, что результат верный. Ниже — такое описание для каждого блока, который переходит к ИИ. Это можно передать разработчику или использовать как основу для промпта.
Автогенерация docstring
- описание совпадает с реальным поведением функции;
- типы параметров указаны корректно;
- пример запускается без ошибок
исходный код функции + связанные unit-тесты
docstring в Google/NumPy формате: краткое описание, параметры с типами, возвращаемое значение, пример использования
3
Экономика
| Метрика | Часов в год | Экономия (₽/год) | Источник |
|---|---|---|---|
| Сгенерировать docstring для функций и классов | 33 | 37 752 | 📊 Расчёт (10 мин/функция × 200 функций) |
| Обновление API spec | 7,5 | 8 580 | 📊 Расчёт (15 мин/неделю вместо 30) |
| Сокращение онбординга новичков | 24 | 27 456 | 📊 Расчёт (−3 дня из 10 дней) |
| Итого | 64,5 | 73 788 |
Ставки рассчитаны по медианным данным HH.ru и ГородРабот.ру, начало 2026 года. Без учёта НДФЛ и страховых взносов (~30%).
| До (без ИИ) | Стало возможным (с ИИ) | Изменение охвата |
|---|---|---|
| API spec обновляется раз в месяц (часто устаревает на 40%) | API spec актуален в реальном времени (из кода) | 100% покрытие вместо 60% |
| Docstring вообще нет или минимальные (10% функций задокументировано) | 100% функций имеют docstring (Google/NumPy format) с примерами | +90% охвата |
| Новичок разбирается 2 недели | Новичок разбирается за 5 дней (вместе с примерами в docstring и README) | −60% времени на онбординг |
| Категория | Описание | Стоимость |
|---|---|---|
| Разовая настройка | Разовая настройка | 60 000 ₽ |
| Интеграция | Интеграция | 60 000 ₽ (разово) |
| Операционные | Операционные (API, подписки) | 10 000 ₽/мес |
| Обслуживание ИИ | Обслуживание ИИ | 2 300 ₽/мес |
| Разовая настройка | Разовые итого | 120 000 ₽ |
| Валидация | Валидация результатов | 2 708 ₽/мес |
| Компетенции | Поддержание компетенций | 550 ₽/мес |
Ловушка зависимости: чем дольше задача делегирована ИИ, тем сложнее замечать его ошибки. Раз в месяц — выполнить одну задачу вручную, чтобы сохранить способность оценивать результат. Подробнее — Мониторинг
Рекомендация
Начать с Блока 1 (🟢 Автоматизация автогенерация docstring) — выбрать один модуль (20–30 функций) и запустить пилот.
На что обратить внимание:
- ИИ-docstring не совпадает с реальным поведением → пересмотреть примеры в unit-тестах
- Новичок всё равно не может разобраться → добавить архитектурный README (это 🟠 Коллаборация блок, требует человека)
Проверка рисков
| Вопрос | Ответ | Следствие |
|---|---|---|
| Ошибка необратима? | Нет | Для 🟢 Автоматизация блоков (docstring, примеры кода) риск низкий — ошибки быстро замечаются в коде. |
| Публика увидит результат без проверки? | Отчасти | Docstring видны в IDE, примеры в Swagger. Требуется проверка разработчиком перед commit. |
| Грозит штраф, иск или вред? | Нет | Документация внутренняя, не регулируемая область. Штраф исключён. |
Уровень контроля после запуска
Уровень автономности — насколько самостоятельно ИИ работает. Для каждого блока выбирается свой уровень в зависимости от цены ошибки.
🟢 Автоматизация блоки (Автогенерация docstring, Примеры кода) — уровень 3 (авто-мониторинг). 🟡 Усиление блоки (OpenAPI spec, примеры ошибок) — уровень 2 (контролируемый). Для каждого блока: проверка человеком перед публикацией в Swagger/Postman.
Если хотите разобрать свой процесс похожим образом — экспресс-диагностика займёт около 45 минут.