README для жюри: как подготовить проверяемое демо хакатонного проекта
Соберите пакет сдачи вокруг одного сценария: конкретный вход и результат, проверенные команды, безопасные данные, доступ жюри и зафиксированный коммит.
·6 мин чтения
Что вы узнаете
Опишите один сценарий через точный вход и ожидаемый результат.
Проверьте инструкцию на зафиксированном коммите без устных подсказок.
Разделите рабочий функционал, заглушки и ограничения доступа.
До сдачи проекта осталось проверить, сможет ли человек вне команды получить тот же результат. Открытая ссылка на репозиторий этого не показывает. В README нужны конкретные данные, шаги и признаки успешного выполнения. По ним судья отличит сбой настройки от ошибки продукта и сможет задать вопрос о том, что действительно работает.
Соберите документ вокруг сценария, который вы готовы повторить. Ниже мы разбираем учебный фильтр комнат по оснащению. Идентификаторы и данные вымышленные; описание не представляет реальное мероприятие или помещения. Тот же порядок подходит для другого прототипа, если заменить вход, результат и условия запуска.
1. Покажите одну законченную задачу
Начните с действия пользователя: «Выбрать комнаты, где есть проектор и доска». Затем назовите результат: список подходящих идентификаторов. В учебном наборе у demo-room-a есть projector и whiteboard, у demo-room-b только projector. Вход {"required":["projector","whiteboard"]} должен вернуть {"rooms":["demo-room-a"]}.
Запишите, где человек вводит запрос и где видит ответ. Для интерфейса укажите название экрана и элемента управления; для API конкретный маршрут, метод и тело запроса. В примере выше показано содержимое запроса, а не готовый адрес сервиса. Подставляйте только реально реализованный путь.
Определите, как сравнивать результат: важен ли порядок комнат, допустимы ли дополнительные поля, что возвращается при отсутствии совпадений. Если прототип показывает список, проверяйте список, а не только отсутствие ошибки. Для наших данных запрос {"required":["microphone"]} ожидает {"rooms":[]}. Это второй учебный вход, который помогает проверить поведение без совпадений.
2. Свяжите README с версией сдачи
В начале документа укажите состояние: рабочий прототип, проверенный сценарий и незавершённые части. GitHub описывает README как место, где читатель понимает назначение проекта, начало работы и способ получить помощь. Для сдачи добавьте ссылку на проверяемую версию кода.
Обновите README перед финальным коммитом. После него скопируйте полный идентификатор коммита в форму сдачи и контрольную запись рядом с демо. Идентификатор коммита, содержащего README, запишите после его создания: чтобы сохранить его в самом файле, понадобится новый коммит. Не обозначайте ветку main как неизменную версию.
Для ссылки на конкретный файл откройте его на GitHub и нажмите Y: постоянная ссылка будет указывать на версию в коммите. Отдельно поясните, какой код обслуживает опубликованное демо. Если локальная версия и сервер расходятся, не оставляйте судье выяснять это по поведению экрана.
3. Проведите читателя от чистой копии до ответа
Выберите основной маршрут: локальный запуск либо доступное размещённое демо. Перед шагами укажите реально проверенные версии среды, менеджера зависимостей и необходимые внешние сервисы. Слово «последняя» не сохраняет условия, в которых вы проверили проект.
Для локального пути запишите рабочую папку, установку по сохранённому файлу зависимостей, подготовку конфигурации, загрузку тестовых данных и запуск. После каждого шага укажите наблюдаемый результат: появился файл настроек, загрузились учебные комнаты, открылся нужный экран. Команды берите из своего репозитория и проверяйте в указанном порядке. Универсальная инструкция установки может пропустить вашу миграцию или генерацию файлов.
Настройки объясняйте по именам. Например, APP_MODE выбирает демонстрационный режим, а DEMO_DATA_PATH указывает путь к учебным данным, если такие параметры реализованы в вашем проекте. Для каждого назовите обязательность и место использования. Если интеграции нужен SERVICE_API_KEY, укажите имя и согласованный способ получить тестовый доступ, без значения ключа в README. Не добавляйте переменные, которые приложение не читает.
4. Подготовьте данные и повторный запуск
Положите безопасный вход в доступный файл и свяжите его с ожидаемым ответом. Для нашего примера достаточно учебного списка комнат с двумя указанными идентификаторами и оснащением. Название файла и его расположение должны совпадать с инструкцией. Читатель не должен восстанавливать набор по скриншоту.
Объясните сброс состояния: какие демонстрационные записи удаляются, что загружается заново и как убедиться, что исходные условия восстановлены. Ограничьте сброс тестовыми данными. Если прототип изменяет состояние, повторите сценарий после сброса и сохраните фактический результат.
Проверьте, что в файлах и записи экрана нет реальных контактов, рабочих документов, токенов и доступа к чужим системам. Для чужого кода используйте одноразовую изолированную среду без рабочих секретов и подключённых папок основной машины. Эти условия согласуются с чек-листом технической приёмки.
5. Назовите зависимости и пределы демо
Разделите то, что работает в коде, показано заглушкой и ещё не реализовано. Наш учебный фильтр проверяет оснащение в наборе данных. Он не подтверждает наличие комнаты в реальном здании, её доступность по времени или возможность бронирования. Эти ограничения должны быть рядом с обещанием результата.
Если нужен внешний сервис, опишите зависимость, тестовый доступ и наблюдаемое поведение при его недоступности. Резервная запись показывает записанный сценарий; она не подтверждает работу на новом запросе. Демонстрационный режим обозначьте как такой режим, без обещания действующей интеграции.
Для AI-прототипа сохраните версии доступных компонентов, промпт, исходный ответ и настройки запуска. Один удачный пример не показывает качество на других данных. Подробный порядок контрольной проверки есть в гайде о проверке AI-демо. Не обещайте повторение результата, если условия внешнего сервиса невозможно закрепить.
6. Проверьте права именно для судьи
Откройте код, демо, данные и запись с правами, которые получит проверяющий. Возможность открыть их в аккаунте владельца не подтверждает доступ жюри. Запишите, требуется ли приглашение и когда истекает тестовый доступ. Для закрытого репозитория используйте согласованный способ передачи материалов.
GitHub позволяет управлять доступом людей и команд к репозиторию. Проверьте приглашение и нужные разрешения отдельно от работоспособности приложения. Не публикуйте закрытые материалы ради удобной ссылки. Данные для входа передавайте через разрешённый канал, а в README оставляйте порядок их получения.
7. Свяжите доказательства с критериями
Возьмите опубликованные критерии оценки и для каждого относящегося к вашей работе пункта укажите проверяемое место: сценарий, файл, результат или объяснение. Не выставляйте себе баллы и не заявляйте готовность продукта на основании одного запуска.
Опишите собственную работу и исходные компоненты в объёме, который требуют правила хакатона: готовый код, помощь, библиотеки и применение ИИ. Формулировка «всё наше» не объясняет границы вклада. Ссылка на файл и описание изменения дают судье конкретный предмет для вопроса.
8. Проведите репетицию без подсказок
Попросите товарища пройти документ от начала до результата в чистой среде. Во время проверки записывайте остановки и необходимую помощь. Если вы вручную создали скрытый файл настроек или изменили данные, это часть сценария, которую нужно описать и повторить.
Сохраните короткую запись: проверяемый коммит, среда, вход, шаги, ожидаемый и фактический результат, остановка, помощь автора, ограничения. Acceptance kit Stavleak помогает оформить результат проверки; его валидатор проверяет структуру записи, а доступ и выполнение сценария проверяет человек.
Перед сдачей исправьте расхождения между README, файлами и формой проекта. Сохраните версию документа вместе с кодом и проверьте ссылки ещё раз. Тогда в питче можно сослаться на конкретный проверенный сценарий, объяснить оставшиеся ограничения и дать судье повторить вашу работу.
