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

Передача исходного кода — это момент, когда проект перестаёт быть «то, чем может управлять агентство», и становится «тем, чем клиент может владеть». Без чёткой передачи быстро проявляются стандартные проблемы: приложение собирается только на одном ноутбуке, в production используется секрет, которого никто не может найти, или небольшое обновление превращается в дни гаданий.
Цель любого чек-листа передачи проста: после передачи клиент должен уметь собрать, запустить и развернуть продукт без постоянного вмешательства агентства. Это не значит «никогда не нужна поддержка». Это значит, что базовые операции повторяемы и задокументированы, чтобы следующий человек мог подхватить работу с уверенностью.
Что считается артефактами передачи, должно быть явно оговорено. Минимум обычно включает:
Объём имеет такое же значение, как и содержание. Некоторые передачи охватывают только одно окружение (например, production). Другие включают dev, staging и production с отдельными настройками и процессами. Если вы не укажете, какие окружения включены, люди будут понимать по-разному, и именно это вызывает простои.
Практичный критерий успеха — проверочный тест: человек, который не собирал приложение, может экспортировать код (например, с платформы вроде Koder.ai), следовать документации, настроить переменные окружения, запустить миграции, собрать и развернуть в согласованном окружении.
Этот чек-лист фокусируется на технической готовности: переменные окружения, вращение секретов, миграции базы данных, скрипты развёртывания и проверка сборки. Он не охватывает юридические условия, контракты, пункты об ИС или споры по оплате. Это важно, но относится к отдельным соглашениям.
Чистая передача начинается до самого экспорта. Если договориться, кто за что отвечает и когда, вы избежите сюрпризов в последний момент: сломанных развёртываний, неоплаченного хостинга или отсутствующих доступов.
Выберите дату передачи и определите окно заморозки (обычно 24–72 часа), когда вносите только срочные исправления. Это удерживает экспортируемый код и работающую систему в синхронизации. Если во время заморозки нужен хотфикс, запишите точно, что изменилось, и убедитесь, что это включено в финальный экспорт.
Решите, кто будет владельцем DNS, облачного хостинга и платных сервисов после передачи. Это не просто бумажная формальность. Если оплата остаётся на карте агентства, сервисы могут быть приостановлены без предупреждения.
Быстрый способ это зафиксировать:
Запишите это простым языком, чтобы обе стороны могли следовать договорённостям.
Согласуйте, какие окружения существуют (local, staging, production) и где каждое из них размещается. Укажите, является ли staging отдельным сервером, отдельной базой данных или просто флагом функциональности. Если вы использовали платформу вроде Koder.ai, также подтвердите, что хостится там, а что ожидается запустить в инфраструктуре клиента после экспорта.
Не оставляйте запросы доступа на последний день. Убедитесь, что нужные люди имеют доступ к репозиторию, CI, хостингу, базе данных и почтовому провайдеру.
Также согласуйте финальный приёмочный тест и процесс подписания. Например: «Клиент может собрать с чистой машины, запустить миграции, развернуть в staging и пройти smoke-тест. Затем обе стороны подписывают акт приёма в письменной форме.»
Хороший чек-лист передачи начинается с репозитория, который новая команда может открыть и понять за несколько минут. Подтвердите, что включено (код приложения, шаблоны конфигурации, скрипты) и что умышленно исключено (реальные секреты, приватные ключи, большие сгенерированные файлы). Если что-то исключено, укажите, где это хранится и кто этим владеет.
Сохраняйте предсказуемую структуру. Стремитесь к понятным верхнеуровневым папкам, например frontend/, backend/, mobile/, infra/, scripts/ и docs/. Если проект — монорепозиторий, объясните, как части связаны и как запускать каждую из них.
README должен быть пригоден для человека, который не писал проект. В нём должны быть перечислены предпосылки и быстрый путь к рабочему дев-руну без догадок.
Включите короткий раздел README, который отвечает на вопросы:
Добавьте простые заметки по архитектуре на понятном языке: что с чем взаимодействует и почему. Небольшой рисунок опционален, но несколько предложений обычно достаточно. Пример: «React-фронтенд обращается к Go API. API читает и пишет в PostgreSQL. Фоновые задачи выполняются отдельным воркер-процессом.»
Наконец, включите версионированный changelog или заметки релиза для сборки, передаваемой на хендовёрд. Это может быть CHANGELOG.md или короткий файл «handoff release notes», где указан точный коммит/тег, что было доставлено и известные проблемы.
Если код экспортирован из платформы вроде Koder.ai, укажите тип сгенерированного проекта (web, server, mobile), ожидаемый тулчейн (например React, Go, PostgreSQL, Flutter) и поддерживаемые версии ОС/инструментов, которые клиент должен использовать для воспроизведения сборки.
Переменные окружения часто являются причиной того, что «рабочее приложение» ломается сразу после передачи. Хороший чек-лист рассматривает их как часть продукта, а не как послефактное добавление.
Начните с инвентаря, по которому новая команда может действовать без догадок. Держите его простым и указывайте пример формата значения (не реальные секреты). Если переменная необязательна, опишите, что случится при её отсутствии и какое поведение по умолчанию.
Простой способ представить инвентарь:
.env файл)Явно указывайте различия по окружениям. Например, staging может указывать на тестовую базу и песочницу платежного провайдера, в то время как production использует боевые сервисы. Также отметьте значения, которые должны совпадать между системами, такие как callback-URL, allowed origins или bundle-идентификаторы мобильного приложения.
Документируйте, где сейчас хранится каждое значение. Многие команды распределяют значения по локальным .env файлам для разработки, CI-переменным для сборок и настройкам хостинга для runtime. Если вы использовали Koder.ai для экспорта, включите файл .env.example и короткую заметку о том, какие переменные нужно заполнить до первой сборки.
Наконец, докажите, что в репозитории нет скрытых секретов. Не ограничивайтесь проверкой текущих файлов. Просмотрите историю коммитов на предмет случайных ключей, старых .env файлов или вставленных учётных данных в пример конфига.
Конкретный пример: React-фронтенд и Go API могут нуждаться в API_BASE_URL для веба, а бэкенду — в DATABASE_URL и JWT_SIGNING_KEY. Если staging использует другой домен, укажите оба значения и где их менять, чтобы новая команда не отправила настройки staging в production.
Передача не считается завершённой, пока клиент не контролирует все учётные данные, которые нужны приложению. Это значит — вращать секреты, а не просто делиться ими. Если у агентства (или у бывшего подрядчика) остаются рабочие ключи, это — незакрытая дверь, которой вы не можете аудировать.
Начните с полного инвентаря. Не ограничивайтесь паролями базы данных. Включите ключи сторонних API, OAuth client secrets, секреты подписей webhook, ключи подписи JWT, SMTP-учётные данные, ключи доступа к хранилищу и любые «временные» токены в CI.
Вот простой чек-лист для дня вращения секретов:
После вращения подтвердите, что ничего не сломалось. Прогоняйте быстрые тесты «как реальный пользователь», а не только смотрите логи.
Сосредоточьтесь на потоках, зависящих от секретов:
Пример: если вы экспортировали проект из Koder.ai и приложение использует платёжный провайдер и доставку почты, поверните оба ключа, разверните, затем сделайте небольшой тестовый платёж и отправку тестового письма. Только после успешных тестов отзывайте ключи агентства.
Наконец, задокументируйте, где секреты будут храниться дальше (vault, CI-переменные или настройки хостинга), кто может их менять и как безопасно откатить изменения, если вращение вызвало ошибки.
Передача может выглядеть «завершённой», хотя именно база данных первая даёт сбой. Рассматривайте миграции и данные как отдельный продукт: версионированные, повторяемые и протестированные.
Начните с записи текущей версии базы данных и места, где лежат миграции в репозитории. Будьте конкретны: путь к папке, шаблон именования и идентификатор последней миграции (или метка времени). Если используется PostgreSQL (часто с Go-бэкендом), также укажите требуемые расширения.
Включите короткий runbook, который отвечает на вопросы:
Откаты требуют честности. Некоторые изменения обратимы только восстановлением бэкапа. Укажите это простым языком и сопроводите шагом по бэкапу (снимок перед релизом, проверка процесса восстановления).
Перед завершением передачи прогоните миграции на копии production-данных, если возможно. Это выявит медленные запросы, отсутствующие индексы и проблемы «работает на пустых данных». Реалистичный тест — экспорт кода, настройка env, восстановление анонимизированной дампы, затем применение миграций с нуля. Это упражнение проверяет большую часть чек-листа передачи.
Если приложение было создано на платформе вроде Koder.ai и затем экспортировано, дважды проверьте, что файлы миграций и любые сид-скрипты включены в экспорт и корректно вызываются при старте бэкенда.
Передача завершена только тогда, когда кто-то другой может пересобрать приложение с нуля на чистой машине. Ваш чек-лист должен включать точные команды сборки, необходимые версии и ожидаемый результат (например: «веб-бандл в /dist», «имя бинарника API», «место APK Flutter»).
Запишите инструменты и пакетные менеджеры, которые вы реально используете, а не те, которые считаете используемыми. Для типичного стека это может быть Node.js (npm или pnpm) для React, тулчейн Go для сервера, инструменты клиента PostgreSQL для локальной настройки и Flutter SDK для мобильной части.
Сделайте установку зависимостей предсказуемой. Убедитесь, что lock-файлы закоммичены (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) и выполните чистую установку на новой машине или контейнере, чтобы доказать работоспособность.
Зафиксируйте, что делает CI, шаг за шагом, чтобы его можно было скопировать на другой CI-провайдер, если потребуется:
Отделите конфигурацию времени сборки от конфигурации времени выполнения. Конфигурация сборки влияет на то, что компилируется (например, BASE_URL, вшитый в веб-бандл). Конфигурация времени выполнения инжектируется при старте (DATABASE_URL, API-ключи, флаги). Их смешивание — распространённая причина «работает в CI», но ломается в проде.
Предоставьте простую локальную проверку. Даже короткий набор команд подойдет:
# Web
pnpm install
pnpm test
pnpm build
# API
go test ./...
go build ./cmd/server
# Mobile
flutter pub get
flutter test
flutter build apk
Если вы экспортируете из платформы вроде Koder.ai, включите сгенерированные CI-файлы или пресеты сборки, использовавшиеся при развёртывании, чтобы клиент мог воспроизвести ту же сборку вне платформы.
Хороший чек-лист не ограничивается «вот репозиторий». Он объясняет, как код превращается в запущенный сервис и кто нажимает кнопку.
Начните с описания текущего процесса развёртывания: полностью вручную (команды на сервере), через CI (пайплайн собирает и деплоит) или через хостинг-платформу. Укажите, где хранятся конфиги и какие окружения существуют (dev, staging, production).
Сделайте шаги релиза повторяемыми. Если процесс зависит от человека, запоминающего 12 команд, превратите их в скрипты и укажите необходимые права.
Дайте клиенту всё, чтобы развернуть на первый день:
Согласуйте ожидания по недоступности. Если требуется «нулевой даунтайм», опишите, что это значит на практике (blue-green, rolling deploy, окно только для чтения при миграциях). Если даунтайм допустим, определите чёткое окно.
Статические ресурсы и кэши — частые точки отказа. Укажите, как собираются и обслуживаются ассеты, когда нужно сбрасывать кэш и используется ли CDN.
Откат должен быть коротким, протестированным рецептом, привязанным к тегу или ID релиза. Например: развернуть предыдущий тег, восстановить снимок базы и инвалидировать кэши.
Если приложение было создано в Koder.ai и затем экспортировано, укажите последний работоспособный снимок и точную версию экспорта, чтобы клиент мог быстро сопоставить код с рабочим релизом.
Проверка — момент, когда вы узнаёте, настоящая ли передача. Цель проста: новый человек берёт экспортированный код, настраивает его и получает то же приложение без догадок.
Перед началом зафиксируйте, как выглядит «правильно»: версия работающего приложения, текущий коммит/тег и один–два ключевых экрана или API-ответа для сравнения. Если экспорт был из Koder.ai, отметьте снимок или время экспорта, чтобы доказать, что вы тестировали актуальное состояние.
Для smoke-тестов держите их короткими и привязанными к рискам:
Если что-то ломается, зафиксируйте точную команду, вывод ошибки и используемые env. Эти детали экономят часы при смене владельца.
Самый быстрый путь превратить передачу в пожар — предполагать, что «код достаточно». Хороший чек-лист фокусируется на мелочах, которые решают, сможет ли клиент действительно запускать и менять приложение без вас.
Большинство проблем укладывается в несколько шаблонов:
Сделайте вращение и очистку доступа запланированной задачей, а не пунктом «когда найдём время». Назначьте дату, когда аккаунты агентства удаляются, сервисные ключи регенерируются и клиент подтверждает возможность деплоя только со своими кредами.
Для env выполните инвентарь из трёх мест: репозиторий, CI и UI хостинга. Затем проверьте это, сделав чистую сборку на новой машине или контейнере.
Для миграций тестируйте с той же ролью базы данных, которую будет использовать production-деплой. Если в production нужны привилегированные шаги (включение расширения), пропишите их и определите владельца.
Реалистичный пример: после экспорта проекта из Koder.ai клиент успешно деплоит, но фоновые задачи падают, потому что URL очереди был задан только в панели хостинга. Простой аудит env бы это выявил. Сопроводите тегированный релиз и документированный откат (например, «развернуть тег v1.8.2 и восстановить последний снимок»), и команда избежит простоя.
Если оставить одну страницу из этого чек-листа, оставьте эту. Цель проста: чистый клон должен запускаться на новой машине, с новыми секретами и базой, которая может безопасно двигаться вперёд.
Запускайте эти проверки на ноутбуке, который никогда не видел проект (или в чистом контейнере/VM). Это самый быстрый способ поймать недостающие файлы, скрытые предположения и старые креды.
Агентство передаёт React-фронтенд, Go API и PostgreSQL. Команда клиента клонирует репозиторий, копирует предоставленный .env.example в реальные env, создаёт новые учётные данные для базы, почты и сторонних API. Они запускают go test (или согласованную команду тестов), собирают React-приложение, применяют миграции к чистой Postgres-инстанции и запускают оба сервиса. Наконец, они деплоят с использованием документированного скрипта и подтверждают, что этот же коммит можно пересобрать позже.
Сделайте передачу краткой и управляемой. 30–60 минутный walkthrough обычно эффективнее длинного документа.