Чеклист передачи проекта: как экспортировать код, оформить секреты и env, настроить локальный запуск, базу данных, CI и README, чтобы команда могла поддерживать проект.
Проект, собранный в AI-платформе, нередко отлично работает внутри нее, но начинает ломаться сразу после переноса в обычный репозиторий. Причина обычно простая: часть настроек и «клея» живет не в коде, а в окружении платформы. При экспорте исходников и запуске в другом месте эти детали пропадают.
Чистый хендовер означает, что проект «живет сам»: его можно забрать из TakProsto, положить в репозиторий и развивать без автора, без чата и без скрытых настроек. Это критично, если проект уходит в другую команду, на аутсорс или просто должен пережить отпуск и смену людей.
После переноса чаще всего не хватает не «фич», а базовых вещей, без которых приложение не поднимается (или поднимается каждый раз по-разному): переменных окружения и секретов, понятного локального запуска, миграций и инициализации базы, минимального CI, README с коротким «как запустить».
Если этого нет, новый разработчик тратит день на догадки: почему не подключается база, где взять ключи, какую команду запускать, какие порты заняты и почему тесты не проходят на чистой машине.
Хороший ориентир: человек, который впервые видит репозиторий, делает рабочий запуск за 30-60 минут. Для этого достаточно, чтобы в проекте были ответы на четыре вопроса:
Когда эти ответы зафиксированы, экспорт превращается из «выгрузили код и удачи» в передачу ответственности с предсказуемым результатом.
Перед экспортом договоритесь о границах передачи. Иначе вы отдадите «папку с кодом», а получатель не сможет ни запустить, ни поддерживать проект.
Сначала определите владельца после передачи. Это не всегда один человек: разработчик отвечает за код, DevOps - за окружения и деплой, продакт или заказчик - за требования и приемку. У каждой роли свои ожидания: кому-то важнее локальный запуск и тесты, кому-то - секреты и инфраструктура, кому-то - критерии готовности.
Дальше согласуйте финальную точку переезда. Экспорт из TakProsto обычно заканчивается репозиторием, но дальше варианты разные: корпоративный Git, отдельный сервер в локальной сети, облачный аккаунт или архив для офлайн-хранения. От этого зависят способ передачи секретов, доступы и формат артефактов.
Зафиксируйте состав того, что передаете. Даже если это «одно приложение», внутри часто несколько частей: фронтенд на React, бэкенд на Go, база PostgreSQL, иногда мобильное приложение на Flutter. Отдельно уточните, есть ли админка, воркеры, фоновые задачи, cron-скрипты, прокси-конфиги.
Полезно заранее записать, что считается «готово»:
Если эти границы согласованы, остальные пункты (env, база, CI, README) становятся понятными задачами, а не угадайкой.
Важно отдавать не просто исходники, а проект, который можно собрать и поддерживать без доступа к платформе. Проще потратить 30 минут на подготовку, чем потом неделями отвечать на вопросы.
Соберите полный состав артефактов и проверьте, что вместе с кодом уезжают файлы, которые реально влияют на сборку и запуск. Базовый набор обычно такой: исходники фронтенда и бэкенда с конфигами сборки, миграции и скрипты инициализации базы, dev-скрипты (запуск, линтеры, форматирование, генерация), заметки по архитектуре и договоренностям, а также файлы для деплоя или инфраструктуры (например, docker-compose), если они есть.
Отдельно проверьте лицензии и права. Это касается npm и Go зависимостей, шрифтов, иконок, картинок, шаблонов писем, тестовых данных и всего, что могло прийти извне. Если есть сомнения, добавьте заметку, откуда взят ассет и можно ли его использовать.
Зафиксируйте состояние проекта на момент передачи: версия, дата, список изменений с последнего стабильного состояния. Иногда достаточно короткого CHANGELOG.md или блока в README.
И подготовьте «план Б». Перед передачей сохраните стабильное состояние, чтобы при срочном багфиксе можно было откатиться и сравнить изменения. Если проект собирался в TakProsto, удобно опереться на snapshots и rollback, а затем экспортировать исходники в репозиторий.
При переезде из платформы в репозиторий чаще всего ломается конфигурация. Начните с инвентаризации: выпишите все переменные окружения и отметьте, где они реально используются (backend, фронтенд, мобильное приложение, CI).
Хороший список выглядит как мини-справочник: название, пример значения (без секрета) и короткая пометка, зачем это нужно. Удобно сразу разделить переменные по смыслу: обязательные (без них сервис не стартует), опциональные (включают функции, но не блокируют запуск), «только прод» (не нужны локально и не должны попадать в dev), а также отдельные тестовые значения для CI.
Шаблон храните в репозитории как .env.example. Внутри достаточно коротких комментариев в одну строку: где используется и какой формат нужен. Например: JWT_SECRET=changeme # backend, 32+ chars.
Секреты передавайте отдельно от кода. Не кладите их в git, issue-трекер или чат с историей. Выберите отдельный канал (менеджер секретов или одноразовая передача) и договоритесь о ротации: после хендовера ключи лучше заменить, даже если утечки не было.
Часто забывают про типовые точки боли: JWT и сессии (секрет, срок жизни, алгоритм), OAuth (client_id, client_secret, redirect URLs), почту (SMTP host/user/password/from), платежи (ключи, webhook secret, sandbox/live), хранилища и сторонние API (S3-совместимые ключи, карты, SMS, аналитика).
Короткий пример: бэкенд на Go ждет DATABASE_URL, а фронтенд на React читает VITE_API_URL. Если это не отражено в .env.example, сборку будут «чинить» часами, хотя проблема в двух строках.
Локальный запуск должен быть одинаковым у автора, у новой команды и у тех, кто подключится через полгода. Начните с минимальных требований по версиям. Лучше указывать диапазоны вроде «Node 18+», «Go 1.22+», «PostgreSQL 15+», «Flutter 3.x», чем оставлять «последняя версия».
Дальше сведите команды в одно место и сделайте их однотипными. В проекте со стеком React + Go + PostgreSQL обычно достаточно зафиксировать:
Чтобы фронтенд и бэкенд запускались вместе без сюрпризов, закрепите порты и правила общения. В dev часто проще настроить прокси на фронтенде, чем бороться с CORS. В production обычно удобнее один домен и запросы к API по относительному пути.
Разведите режимы dev и production: в dev нужны горячая перезагрузка и подробные логи, в production - сборка, миграции и стабильные конфиги. Даже если деплой не локальный, полезно уметь поднять «почти как в проде» запуск одной командой.
Если хотите заранее снять большинство типовых поломок, проверьте четыре вещи: есть ли env-шаблон и список обязательных переменных, можно ли переопределять порты, есть ли явный шаг «поднять БД и инициализировать», и применяются ли миграции до старта API.
При переезде в обычный репозиторий база данных часто становится главным источником сюрпризов. Код можно собрать, а без понятного способа поднять PostgreSQL и получить схему приложение не стартует.
Зафиксируйте минимальные параметры создания базы: имя базы, имя пользователя, пароль, права, кодировку и часовой пояс. Важно описать значения по умолчанию, а не «как у меня на ноутбуке». Для PostgreSQL обычно достаточно UTF8 и явного указания владельца базы.
Сделайте один понятный путь инициализации схемы. Хорошая практика: схема создается только миграциями, а начальные данные (сиды) грузятся отдельным шагом. Так проще тестировать и откатываться.
Чтобы это пережило передачу, в репозитории должны быть: каталог миграций и правило, чем их накатывать; один bootstrap-скрипт, который поднимает БД с нуля и применяет миграции; отдельный шаг для сидов или тестовых данных; пример конфигурации подключения без секретов; короткое описание, где менять параметры через переменные окружения.
С данными лучше быть строгими: боевые дампы почти никогда нельзя передавать «как есть». Если дамп нужен для воспроизведения ошибок, он должен быть обезличенным: без телефонов, email, токенов и платежных данных. Отдельно договоритесь, кто имеет доступ и где эти дампы хранятся.
Финальная проверка простая: возьмите «чистую» машину или контейнер, удалите локальные базы и поднимите проект строго по инструкции. Если нужно вручную создавать таблицы, править SQL или «один раз зайти в админку», хендовер еще не готов.
После экспорта кода важно, чтобы проект продолжал собираться и проверяться сам, без ручных ритуалов. CI нужен, чтобы каждое изменение не ломало локальный запуск, миграции и релиз.
Держите набор проверок минимальным, но полезным: линтеры и форматирование, тесты (юнит и быстрые интеграционные, если есть), сборка фронтенда и бэкенда, проверка миграций на чистой базе и простой smoke test (старт сервиса с минимальными настройками).
Важно, чтобы CI использовал те же команды, что вы рекомендуете разработчикам локально. Если локально все запускается через make test, не делайте в CI отдельную логику на десятки строк.
Секреты не должны попадать в репозиторий даже «временно». В CI добавляйте их как переменные окружения в настройках системы сборки. Обычно это ключи для контейнерного реестра, доступ к тестовой базе, токен для деплоя и подписи мобильной сборки (если релизите Flutter).
Держите отдельные значения для тестового окружения и продакшена и разные права доступа. Тогда утечка тестового токена не превращается в большой инцидент.
Договоритесь о простых правилах: main всегда в состоянии «можно собрать и запустить», релизы помечаются тегами версий, хотфиксы идут отдельной веткой и тоже получают тег. Если храните артефакты сборки, сохраняйте их с версией и датой и держите понятный шаг для отката.
Если проект экспортирован из TakProsto, отдельно проверьте, что сборка воспроизводится без настроек платформы: тот же набор переменных окружения, те же команды, те же миграции.
После экспорта проект часто «умирает» не из-за багов, а из-за тишины: непонятно, какие зависимости нужны, где конфиг, как поднять базу и чем проверить, что все живо. Хороший README решает это за 10 минут чтения и экономит дни переписок.
README должен быть коротким, но конкретным. Удобно, когда он отвечает на вопросы в одном порядке: что это за проект и из каких частей состоит; требования по версиям (Node/Go/Docker и т.д.); где конфиг и какие переменные окружения обязательны; карта репозитория (где фронт, бэк, миграции, сиды, скрипты); контакты и список решений «не трогать» (например, схема авторизации или структура миграций) с коротким объяснением почему.
Раздел «How to run» пишите как инструкцию, которую можно выполнить в чистой среде:
Если есть «How to deploy», добавьте порядок выката: какие переменные обязательны на сервере, когда запускать миграции, как проверить после выката и как выполнить откат.
Вы собрали в TakProsto небольшое внутреннее веб-приложение: фронтенд на React, API на Go и база PostgreSQL. У вас оно работает, но дальше его должна поддерживать другая команда, без доступа к вашей среде.
Хендовер оформили как репозиторий с экспортированными исходниками и набором понятных артефактов: .env.example без секретов, миграции базы, короткая инструкция по запуску. Секреты передали через безопасный канал и договорились, кто и где их хранит.
Чтобы проверить, что передача реальная, сделали тест по таймеру: новый разработчик берет чистую машину, клонирует репозиторий и пытается поднять проект за 30-40 минут, не задавая вопросов. Это быстро показывает, где у вас не документация, а «знание в голове».
В процессе всплыли типовые проблемы: не хватало одной переменной окружения для отправки писем (в проде была, в .env.example не попала), одна миграция осталась только в рабочей базе и не была закоммичена, а порты фронта и бэка в dev не совпадали с прокси-конфигом.
Исправления заняли вечер: добавили переменные в шаблон и описали значения по умолчанию, закоммитили миграции и добавили bootstrap-команду для новой базы, зафиксировали порты в конфиге и в README, добавили в CI сборку и короткий smoke test.
Больнее всего бьют мелкие несоответствия, которые всплывают через неделю, когда новую команду уже «выпустили в поле».
Первая ловушка - секреты. Ключи API, пароли к БД и токены иногда случайно попадают в репозиторий и остаются в истории коммитов. Безопаснее держать секреты только в переменных окружения и отдельном хранилище, а перед передачей прогнать поиск по репозиторию по словам вроде "TOKEN", "SECRET", "PASSWORD".
Вторая проблема - README «есть», но команды не работают. В тексте написано Node 18, а реально проект завязан на Node 20; указана команда, которой уже нет после правок. README нужно проверять на чистой машине.
Третья ошибка - миграции не поднимают базу так же, как в production. Если схема держится на ручных SQL-правках, при первой попытке развернуть проект все рассыпается. Миграции должны создавать схему с нуля, а начальные данные должны загружаться отдельным, повторяемым шагом.
Четвертая ловушка - «локально работает только у автора». Причины обычно в скрытых файлах, локальных настройках IDE, незафиксированных версиях инструментов или в том, что автор однажды руками создал папку, сертификат или конфиг и забыл.
Пятая - CI зеленый, но это не означает, что сборка поднимется на чистой среде. В CI могли случайно закэшироваться зависимости или быть пропущен шаг вроде генерации кода, применения миграций или сборки фронта.
Перед передачей сделайте короткую проверку:
Самая полезная финальная проверка простая: сможет ли другой человек запустить проект без вас. Возьмите чистую машину или новый контейнер, откройте только репозиторий и README и поднимите проект с нуля.
Короткий список, который чаще всего спасает от сюрпризов:
.env.example и понятное описание обязательных переменныхЕсли какой-то пункт не проходит, не держите это «в голове». Зафиксируйте в репозитории: допишите README, уточните переменные, добавьте команды и проверьте еще раз.
Перед финальной передачей сделайте экспорт исходников и сохраните стабильный снимок проекта. В TakProsto (takprosto.ai) для этого есть экспорт кода и snapshots/rollback, что удобно, когда нужно быстро сравнить состояние до и после хендовера или откатиться к рабочей версии.