Онбординг человека и AI-агента подозрительно похож

Чем больше я работаю с AI-агентами, тем сильнее их проблемы напоминают мне онбординг нового разработчика.

Писать код агент умеет. Сложности начинаются, когда нужно понять, как запустить проект, почему здесь сделано именно так и какие договорённости приняты в команде.

С человеком у нас для этого давно есть универсальное решение — другие люди:

— Спроси Петю.
— Тут есть нюанс, я расскажу.
— Это нигде не написано, но мы так не делаем.

С агентом такой подход не работает. И сразу становится видно, сколько знаний о системе хранится не в документации или коде, а в головах команды.

GitHub в статье Onboarding your AI peer programmer прямо сравнивает настройку Copilot coding agent с онбордингом нового разработчика.

OpenAI в материале Harness engineering пишут, что информация, которую агент не может найти во время работы, для него фактически не существует. Если что-то обсудили в чате или на созвоне и нигде не зафиксировали, агент об этом не узнает. Например, команда обсудила архитектурное решение в Mattermost или Telegram и пошла дальше. Через несколько месяцев о нём не будет знать ни агент, ни новый разработчик, который придёт в проект.

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

При этом сама проблема далеко не новая. Ещё в исследовании IBM Moving into a New Software Project Landscape отмечалось, насколько важно новичку разобраться в структуре проекта и иметь возможность проверить, правильно ли он её понял.

Дайте новому человеку — или агенту — репозиторий и посмотрите, сможет ли он без Пети понять:

— как запустить проект;
— как прогнать тесты;
— где искать нужный код;
— какие договорённости приняты в команде.

AI может оказаться неплохим тестом на качество инженерной среды. Если для этого всё-таки нужен Петя, значит, важный контекст остался за пределами репозитория.

Слишком большая часть знаний о системе всё ещё живёт в головах старожилов.

И у подготовки проекта к работе с AI есть хороший побочный эффект: следующему человеку тоже будет проще в него войти.