Вступление

Всем привет! Меня зовут Дина, я Java‑разработчик, около шести лет в энтерпрайзе. С апреля начала делать пет‑проект вместе с ИИ‑агентом: он писал код, я ставила задачи и смотрела на тесты. Всё шло хорошо: тесты были зелёными, сценарии закрывались, а потом я открыла проект и поняла, что чётко не осознаю, как в нём устроен главный сценарий: от запроса до готового видео. Эта статья о том, как я возвращала себе понимание собственного кода.

Проблема: код появляется быстрее, чем понимание

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

Представьте, что ещё до ИИ‑агентов вам сказали бы: «С сегодняшнего дня ты не пишешь код. Фичи делает другой разработчик, а ты только смотришь его пул‑реквесты». Я не встречала разработчика, который, просматривая PR, вникал бы в него так глубоко, чтобы знать код лучше автора. Вовлечённость всё равно ниже.

С агентами мы все оказались в этой роли.

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

Таким коллегой стала и я сама для себя: в пет‑проекте с невероятной быстротой генерила код, а на ревью отводила не так много времени. Вовлечённость падала, но в моменте это было не заметно.

Когнитивный долг

У этой проблемы есть имя — когнитивный долг. Сам термин звучал и раньше: например, в исследовании MIT Media Lab «Your Brain on ChatGPT» 2 025 года о том, как ИИ‑ассистент влияет на написание эссе. В разработке его популяризировала Маргарет‑Энн Стори, профессор Университета Виктории. Её идею подхватили Саймон Уиллисон и Мартин Фаулер.

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

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

Стори описывает студенческую команду, которую сама курировала. Ребята работали вместе, под присмотром профессора, и всё равно к восьмой неделе уже не могли внести даже простое изменение, не сломав что‑то в неожиданном месте. Сначала они винили технический долг, но дело было другом: никто в команде уже не мог объяснить, почему приняты те или иные решения и как части системы связаны между собой. Когнитивный долг накапливается незаметно, даже когда все стараются.

Есть и цифры. В январе 2 026 года Anthropic провела рандомизированный эксперимент: 52 разработчика, в основном джуниоры, осваивали незнакомую асинхронную Python‑библиотеку Trio, половина выполняла задание с ИИ‑ассистентом в окне чата. На тесте по только что изученному материалу группа с ИИ набрала в среднем 50%, группа без ИИ 67%. Сильнее всего отставание было в вопросах на отладку. При этом ИИ ускорил работу всего примерно на две минуты, и даже это ускорение оказалось статистически незначимым.

Самое интересное в этом исследовании не средние цифры, а то, как люди работали с ИИ. Те, кто полностью отдавал ему написание кода, набрали меньше 40%. Те, кто сначала генерировал код, а потом задавал вопросы, чтобы его понять, или просил объяснения вместе с кодом, набрали 65% и выше. И это с обычным чатом. Сами авторы считают, что с агентами вроде Claude Code, которые пишут код целиком, эффект, скорее всего, будет ещё сильнее.

Мой личный опыт

Расскажу, как непонимание кода стало точкой невозврата в моём проекте.

Это случилось на генерации спек. Я работала по процессу, где агент сам режет историю на сценарии, пишет тест, потом код, потом рефакторит и проводит ревью. На каждом шаге он дописывает отчёт о проделанной работе. В какой‑то момент я посчитала объёмы:

• код продукта: около 3 150 строк;

• спеки и отчёты агентов: 13 260 строк, в 4,2 раза больше кода;

• один только файл прогресса по второй истории: 5 821 строка, в 1,8 раза больше, чем весь код продукта.

Такой объём я физически не успевала читать. Агент генерировал спеки, которые я перестала понимать, и захватил штурвал: он стал основным пилотом, который советуется со мной, а не наоборот. Я видела только зелёные тесты и закрытые сценарии, но контроль был упущен.

Метод: линейный разбор и интерактивное объяснение

Идею я взяла у Саймона Уиллисона, из глав «Linear walkthroughs» и «Interactive explanations» его руководства Agentic Engineering Patterns. Claude Code написал ему утилиту для облаков слов, но фраза из отчёта про «размещение по архимедовой спирали» ничего ему не объяснила. Линейный разбор помог понять структуру кода, но не сам алгоритм. А вот анимация, где видно, как каждое слово пробует встать на место и сдвигается по спирали, наконец сделала алгоритм понятным.

Важно, что это два шага: сначала текстовый разбор, потом анимация, которая на него опирается. Я адаптировала их под свой пет‑проект Аватар — сервис, который генерирует видео через платный API внешнего провайдера.

Стек: Java 17 и Spring Boot на бэкенде, React и TypeScript на фронтенде, Postgres (локально H2), сборка на Gradle. Архитектура чистая: домен, usecase, адаптеры. Код пишет Claude Code, разбор и анимацию тоже делал он.

Шаг 1. Мой промпт для линейного разбора

Прочитай исходный код [путь к модулю генерации видео]. 
Спланируй линейный разбор: в каком порядке объяснять код, 
чтобы человек, который его не писал, понял весь путь от запроса 
на генерацию видео до получения результата, включая ошибки и таймауты. 
Напиши разбор в walkthrough.md. 
Фрагменты кода вставляй shell-командами (grep, sed, cat) прямо из файлов, 
а не переписывай вручную. Объясняй не только что делает код, но и почему он так устроен.

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

Шаг 2. Промпт для интерактивной анимации

Прочитай walkthrough.md целиком. 
На его основе сделай страницу result-flow.html, 
которая анимированно показывает, как работает генерация видео в моём проекте: 
какие компоненты участвуют, как приложение ждёт результат, что происходит при ошибке, 
повторной попытке и таймауте. Используй выдуманные данные и имитацию времени, 
никаких настоящих вызовов API. Добавь переключатель сценариев 
(успех, ошибка с повтором, таймаут), паузу, регулировку скорости 
и пошаговый режим вперёд и назад. На каждом шаге показывай, 
в каком состоянии находится каждый компонент и какой фрагмент 
кода сейчас выполняется.

Сценарии ошибки и таймаута я добавила специально. В асинхронном коде непонятнее всего не happy path, а то, что происходит, когда что‑то идёт не так.

Что получилось на моём пет‑проекте

Что нашёл разбор

Разбор получился большим: отдельный раздел на каждую часть пути видео, от запроса до повтора. Приведу оттуда несколько находок.

Проект, который выглядит рабочим, с настоящим ключом не работает. Первое, что показал разбор — поиск заглушек в настоящем клиенте провайдера:

grep -n 'Not implemented yet' RealProvider.java

68:throw new UnsupportedOperationException("Not implemented yet");
73:throw new UnsupportedOperationException("Not implemented yet");

Строки 68 и 73: методы status и playbackUrl. Настоящий клиент умеет только запустить рендер, но не может ни узнать его статус, ни получить ссылку на готовое видео. Весь путь от запроса до готового видео работает только с фейком.

При этом все тесты зелёные. Почему так вышло? Вызов настоящего API платный, поэтому всё тестировалось на фейке — подделке, которая без сети и без оплаты отвечает «как будто» провайдер. Это нормальное решение. Но код писался без меня, и я думала, что настоящий клиент доделается в следующих сценариях. А агент закрывал сценарий, когда тесты становились зелёными — тесты на фейке. Получился замкнутый круг: фейк проходит тесты, тесты закрывают сценарий, сценарий считается готовым. Ни на одном шаге никто не спросил, работает ли это с настоящим API.

Grep нашёл бы эту строку за секунду. Но разбор прошёл по цепочке дальше. Заглушка бросает UnsupportedOperationException. Поллер — фоновая задача, которая раз в 10 секунд спрашивает статус всех видео в работе, ловит только VideoGenerationException, то есть ошибку провайдера. Чужое исключение он не ловит, и оно обрывает весь проход на первом же видео. Через 10 секунд всё повторяется. Получается, одна заглушка не просто «не работает», а останавливает обработку всех видео, и они навсегда остаются в статусе «в очереди». По одной строке такое не увидишь.

Документация обещает одно, код делает другое. Если вызов API падает, в базе остаётся «сирота» — видео в статусе queued без идентификатора рендера. Запись об архитектурном решении (ADR 02) это допускает и обещает, что потом такие строки будут переводиться в failed:

The row is left `queued` with no provider handle — an orphan, deliberately preferred over a paid render with no record. Mapping the failure to `failed` is Scenario 4.3.

Но сценарий 4.3 в итоге сделал совсем другое:

2276:### Scenario 4.3: Include a human-readable reason when the video failed

Кода, который переводит сироту в failed, нет. Пользователь видит «в очереди» вечно и не может повторить генерацию. Это очень похоже на то, о чём пишет Стори: решения записаны, но знание о том, выполнены ли они, потерялось.

В конце разбора агент собрал все ошибки в одну таблицу. Вот пример из неё:

Что дала анимация

Разбор нашёл проблемы, но понять, как на самом деле живёт видео, мне помогла анимация. То, что в тексте разбросано по нескольким разделам (ожидание, ошибка и повтор), в анимации складывается в одну картину. На каждом шаге видно, какой компонент работает, какой ждёт, что лежит в базе и какая строка кода выполняется прямо сейчас. Например, поллер может вообще не заметить статус generating: тики идут раз в 10 секунд, и видео перескакивает из queued сразу в failed. В тексте это одна фраза, а в анимации видишь это своими глазами.

Ниже анимация сценария «ошибка с повтором». Она записана на фейке, ещё до того, как я доделала status. Чтобы фейк «сломался», клиент добавляет в сценарий видео (текст, который должен произнести аватар) специальную метку [[provider-fail:render_error]]. Фейк ищет её в тексте и, если находит, отвечает так, будто рендер не удался. Так можно посмотреть путь ошибки, не платя за настоящий вызов.

Как я проверяла находки. Я шла по разбору и анимации шаг за шагом и каждый раз открывала в IDE код, о котором шла речь. Так каждую находку я проверила сама. Здесь интерактивность сработала второй раз: анимация задаёт маршрут, а код служит доказательством.

Чем закончилось

В тот же день, когда был готов разбор, я взялась за status: теперь настоящий клиент спрашивает статус у провайдера и переводит его ответ в наш. Дальше проверка на настоящем вызове и playbackUrl.

Сколько это стоило

Линейный разбор и анимация вместе заняли у агента около четырёх часов, из них примерно два с половиной ушло на анимацию. Это пассивные 4 часа: моё участие в них — 10 минут на написание промптов. Но к ним надо добавить моё время на то, чтобы пройти разбор и анимацию и сверить их с кодом. У меня это заняло около часа.

Много ли это? Если коротко: за эти часы я узнала, что мой проект с настоящим ключом вообще не доводит видео до конца, и нашла 15 сценариев ошибок без тестов.

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

Выводы

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

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

Источники

• Margaret‑Anne Storey, How Generative and Agentic AI Shift Concern from Technical Debt to Cognitive Debt

• Kosmyna et al., MIT Media Lab, Your Brain on ChatGPT: Accumulation of Cognitive Debt when Using an AI Assistant for Essay Writing Task

• Simon Willison, заметка о когнитивном долге

• Martin Fowler, Fragments: April 2

• Simon Willison, Linear walkthroughs и Interactive explanations

• Anthropic, How AI assistance impacts the formation of coding skills