Онбординг инженеров с ИИ: понятный план на первую неделю

Почему первая неделя часто идёт не так

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

Новый сотрудник приходит, получает тикет, открывает кодовую базу и начинает гадать. Он не знает, где живёт бизнес‑логика, какая папка — наследие, а какому пакету команда ещё доверяет. Поэтому он ищет по ключевым словам, идёт по случайному импортy и копирует первый паттерн, который кажется подходящим.

ИИ упрощает это делать — и упрощает ошибаться. Если никто рано не объяснит форму репозитория, новый человек задаёт общие вопросы и получает общие ответы. Модель может указать не ту директорию, старую абстракцию или паттерн, который принадлежит другому сервису.

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

Pull request'ы дрейфуют по той же причине. Правила ревью часто живут в головах людей вместо документов по онбордингу. Новый сотрудник открывает PR с неправильным заголовком, без заметок по тестам, с лишними автоматически сгенерированными изменениями или в стиле, которым команда перестала пользоваться месяцы назад. Ревью превращается в очистку вместо обратной связи.

Проблема проявляется в мелких промахах. Кто‑то добавляет поле в ответ API, но забывает про воркер, который его заполняет, фикстуру, которая делает снимок, и заметку в ревью про миграцию. Ничего не ломается явно. Команда всё равно теряет часы.

Эти мелкие различия быстро складываются. Один инженер кладёт логику в хэндлеры, другой — в сервисы, третий даёт ИИ‑инструменту придумать четвёртый паттерн. Через неделю‑две у команды — дрейф. Дрейф замедляет ревью, путает владение и учит следующего новичка неправильным привычкам.

Что дать в первый день

Новому инженеру не нужен тур по каждому инструменту в компании. Ему нужен небольшой стартовый набор, который показывает, как работа действительно проходит в команде.

В этот набор должно входить четыре вещи.

Во‑первых, дайте карту репозитория. Уместите её на одной странице и сделайте практичной: основные папки, что делает каждая зона и кто отвечает за рискованные части. Запись вроде «billing находится здесь» или «спросите Danu перед изменением auth» помогает больше, чем длинный архитектурный документ.

Во‑вторых, в тот же день дайте короткую страницу с правилами ревью. Сделайте её простой. Покажите, что должно быть в pull request'e, какие тесты запускать, когда просить второго ревьюера и какие изменения требуют повышенного внимания. Новые сотрудники не должны догадываться, допустим ли сгенерированный дифф.

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

В‑четвёртых, покажите один пример задачи от начала до конца. Выберите безопасное реальное изменение и покажите весь путь: где лежит код, какой промпт использовать первым, как тестировать, как должен выглядеть PR и какие комментарии от ревьюеров нормальны. Держите пример настолько маленьким, чтобы его можно было прочитать за 10 минут.

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

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

Как объяснить карту репозитория

Карта репозитория должна следовать за продуктом, а не за деревом папок. Новые сотрудники думают сначала о фичах: signup, billing, поиск, админка, уведомления. Если вы начнёте с "apps/", "packages/" и "libs/", они могут заучить имена и при этом не понять, как работает продукт.

Для каждой продуктовой области указывайте файлы, где принимаются реальные решения. Маршруты и UI‑файлы важны, но людям также нужно видеть, где расположены правила ценообразования, проверки прав, ретраи и изменения состояния. Если «отмена подписки» затрагивает пять сервисов, опишите этот путь один раз, чтобы никому не приходилось гадать.

Хорошая карта умещается на одной странице. Для каждой области включите функцию простыми словами, несколько файлов, которые стоит прочитать в первую очередь, где лежат тесты, какие скрипты или конфиги важны и кто владеет этой частью системы.

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

Метки владельцев важнее, чем многие команды признают. Используйте реальное имя или небольшую группу, а не «engineering» или «backend». Если у кого‑то есть вопрос про токены аутентификации, он должен знать, кто ответит за две минуты.

Небольшой пример

Если баг появляется в checkout, карта должна сказать новому инженеру, с чего начать: страница оформления заказа, сервис, который применяет правила скидок, webhook‑хэндлер, который подтверждает платёж, тесты для неуспешных списаний и runbook для локальной сборки. Также должна быть пометка не трогать общий billing‑конфиг на второй день.

Если новичок может ответить «где живёт правило, как я его протестирую и кто его владеет?» через 10 минут с картой — карта работает.

Обучите правилам ревью до первого pull request'а

Большинство новых сотрудников неплохо знают Git. Они испытывают сложности с командными привычками, которые никто не записал. Если ждать первого комментария в ревью, люди начинают гадать.

Хороший pull request легко просмотреть за один заход. Если можете, покажите один реальный пример из вашей команды. Лучшие PR делают одну вещь, объясняют, зачем изменение, и выделяют рискованную часть.

Размер имеет значение. Ревьюер способен качественно оценить небольшое изменение за 10–15 минут. Когда PR смешивает багфикс, очистку, изменения имён и рефактор, качество ревью быстро падает. Попросите новичков разбивать работу по цели, а не по файлам.

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

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

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

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

Ещё одно правило сильно помогает: автор владеет контекстом. Ревьюерам не стоит копаться в истории коммитов или чатах, чтобы понять изменение. Если ИИ помогал писать код, инженер всё равно должен объяснить логику простым языком.

Шаблоны промптов, которые соответствуют ежедневной работе

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

Небольшой общий набор сокращает случайные привычки. Он также упрощает ревью, потому что люди начинают просить у модели одинаковый тип вывода.

Три стартовых промпта

Используйте один промпт для чтения кода. Он должен заставить модель оставаться близко к файлу перед ней.

Explain this file to a new engineer in plain English.
File: [path]
Focus on what it does, what calls it, what inputs and outputs matter, and what might break if I change it.
Use names from the code.
If something is unclear from this file, say "unclear from this file".
Do not guess about files or behavior you cannot see.

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

Draft tests for [function or class].
Use the style and structure from [existing test file].
Cover only behavior you can prove from the code I shared.
Do not invent new features.
Do not change production code.
Return the test code and a short note if context is missing.

Для небольших рефакторов держите запрос узким. Это мешает модели превратить аккуратную чистку в ребут проекта.

Suggest a small refactor for [path] that improves clarity without changing behavior.
Keep public interfaces, data shapes, logging, and error handling the same unless I ask otherwise.
Stay in this file if possible.
If the change is risky, say so and stop.
Show the proposed code and the tests I should run after it.

Самая полезная строка в любом промпте — это ограничение. Просите людей каждый раз явно указывать, что модель не должна менять. Частые ограничения — контракты API, схема базы, проверки авторизации, флаги функций и стиль тестирования.

Храните эти примеры рядом с документацией по коду, а не в презентации, которую никто больше не открывает. Разместите их рядом с картой репозитория и правилами ревью, чтобы новичок мог скопировать, вставить путь к файлу и получить полезный ответ за две минуты.

Простой план на первую неделю

Первая неделя лучше работает, когда у каждого дня есть одна ясная задача. Новым сотрудникам не нужен большой тур. Им нужен короткий путь, который помогает прочитать код, освоить инструменты команды и сделать одно безопасное изменение до конца недели.

Практическая первая неделя может выглядеть так:

• День первый: прогоните репозиторий вместе с реальным человеком. Покажите основные папки, где лежат тесты, как запустить приложение, как пользоваться локальными инструментами и где команда хранит правила ревью. Закончите день простой задачей: запустить приложение и объяснить один путь запроса менторам.
• День второй: проследите один небольшой баг или фичу от отчёта до кода. Цель не в скорости, а в том, чтобы понять, как команда следует нитке через логи, файлы, сервисы и тесты без гаданий.
• День третий: писать промпты рядом с ментором. Используйте реальные задачи, не учебные примеры. Попросите новичка набросать промпты для поиска кода, идей для тестов и небольшого рефактора, затем сравните результаты с общими шаблонами команды.
• День четвёртый: выпустить крошечное изменение через ревью. Держите объём узким: исправление текста, маленький тест, защитная проверка или незначительный баг. Это даёт новичку полный цикл: именование ветки, заметки в PR, комментарии ревью и последующие правки.
• День пятый: привести документацию в порядок и собрать открытые вопросы. Если шаг установки был непонятен или карта репозитория вызвала вопросы, исправьте это пока память свежа.

Этот порядок важен. Сначала новичок узнаёт, где что находится, потом — как думает команда, затем — как команда использует ИИ, и только после — пушит код.

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

Реалистичный пример

Maya присоединяется к бэкенд‑команде во вторник, в середине спринта. Её первая задача кажется небольшой: поменять правило валидации, чтобы форма регистрации принимала новый формат company ID. Маленькие задачи — как раз место, где новички чаще всего дрейфуют, потому что начинают гадать, где лежит логика, и правят не те файлы.

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

Это экономит больше времени, чем команды ожидают. Без карты новый инженер мог бы изменить общий хелпер, сломать другой поток и полдня распутывать последствия. С ясной картой Maya вносит одно целенаправленное изменение в нужном сервисе и не трогает остальную систему.

Правила ревью формируют PR ещё до того, как она много написала. Команда просит одну цель на PR, краткое резюме и тесты, которые соответствуют изменённому поведению. Поэтому Maya не смешивает очистку, рефактор и личные предпочтения по именам в одной ветке.

Она также использует сохранённый промпт из онбординга. Это не магия. Он просто даёт ИИ достаточно контекста, чтобы звучать как команда: «Напиши тесты для этого изменения валидации. Используй наш стиль тестов, держи имена короткими, покрой один валидный и два невалидных случая и не добавляй новые хелперы, если текущий файл их не использует.»

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

Ошибки, которые создают дрейф

Дрейф редко начинается с большой ошибки. Он начинается, когда новому инженеру дают слишком много для чтения, нет понятного порядка и неясное место для начала. Десять документов могут показаться исчерпывающими, но обычно они толкают людей к поверхностному чтению, догадкам и копированию того, что выглядит свежим.

Проблема усугубляется, когда каждый ментор учит немного разному процессу. Один говорит просить у ИИ тесты сначала. Другой — сначала писать фикс, потом подключать промпт. Третий хочет маленькие PR, а кто‑то принимает огромный дифф, если он «идёт быстро». К концу первой недели новичок усваивает, что у команды нет единого стандарта.

Привычки промптов дрейфуют так же. Если команды считают промпты личными фишками, а не общими методами, каждый инженер создаёт персональный стиль, хранит его в заметках или чате и получает разный результат для одной и той же задачи. Это не креатив, это шум.

Привычки ревью ломаются похожим образом. Если команда показывает только отполированные pull request'ы, новички никогда не увидят, чего стоит избегать. Им нужно видеть слабые примеры тоже: неопределённый заголовок, отсутствие заметок по тестированию, отсутствие причины изменения, дифф, который смешивает рефактор и багфикс, или резюме от ИИ, которое много говорит и ничего не поясняет.

Правила перестают быть правилами, когда команда прячет их в старых комментариях, разрозненных чатах или «племенной» памяти. Правило в трёхмесячной переписке — просто тривая.

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

Если хотите меньше дрейфа — сделайте путь скучным и ясным. Дайте один стартовый пакет. Обучите одному процессу. Откройте шаблоны промптов. Покажите слабые PR, прежде чем кто‑то откроет свой.

Быстрые проверки до конца первой недели

К концу первой недели новый инженер должен сделать больше, чем просто завершить настройку. Он должен показать, что умеет работать в командном стиле разработки, а не выдумывать приватный метод, который никто не повторит.

Эти проверки лучше проводить как короткие практические упражнения. Менеджер или тимлид могут сделать их за 20 минут и быстро заметить непонимание.

Попросите новичка объяснить репозиторий простыми словами. Ему не нужны идеальные детали, но он должен указать, где стартует основное приложение, где лежит общая логика и где обычно живут тесты.

Дайте ему небольшую область кода и попросите назвать владельца. Он должен знать, где найти ответ в командных документах, CODEOWNERS или нужном канале чата, а не догадываться.

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

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

Затем спросите, когда он бы остановился и попросил помощи. Хорошие ответы конкретны: когда две папки кажутся решать одну и ту же проблему, когда изменение затрагивает биллинг или авторизацию, или когда он блокирован уже 30 минут и начинает догадываться.

Простой сценарий упрощает проверку. Если им дали баг в API‑хэндлере, он должен назвать вероятную папку, найти владельца, написать маленький фикс, открыть PR по командным правилам и использовать утверждённый промпт перед запросом обратной связи.

Если один из шагов вызывает сомнения — исправьте это на той же неделе. Общие привычки важнее скорости на этом этапе.

Что делать дальше

Большинство документов по онбордингу устаревают, если за ними никто не следит. Относитесь к карте репозитория, правилам ревью и шаблонам промптов как к рабочим частям кодовой базы, а не как к побочным заметкам.

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

То же самое с повторяющимися советами из ИИ. Если старшие инженеры постоянно набирают один и тот же текст в чат, превратите этот совет в общий шаблон промпта. Держите его коротким, привязанным к реальной задаче и удобным для повторного использования.

Лёгкий рутинный уход достаточен:

• обновляйте карту репозитория после структурных изменений
• сохраняйте повторяющиеся советы из чатов как командные шаблоны промптов
• пересматривайте заметки по онбордингу после каждого нового найма
• исправляйте любое правило, которое люди неправильно понимают в первую неделю

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

Так первая неделя остаётся последовательной со временем. Цель не в большем количестве документов. Цель — меньше приватных привычек.

Небольшой стартап может делать это менее чем за час после каждого найма. Один человек обновляет карту, другой чистит промпты, и команда договаривается о любом правиле ревью, которое вызвало трения. Эта привычка предотвращает дрейф лучше, чем длинный справочник, который никто не читает.

Если стартапу нужна помощь с настройкой карт репозитория, правил ревью или практических привычек разработки с помощью ИИ, Oleg Sotnikov на oleg.is работает именно с таким ранним дизайном процессов в роли fractional CTO и советника стартапов. Внешняя помощь часто полезна до того, как команда накопит месяцы небрежных привычек вокруг догадок.