Submission package і repro audit

1. Захист вирішує пакет, а не промова

Перед захистом легко скотитися до шкільної логіки: головне — добре виступити. В інженерії жорсткіше: спочатку дивляться на те, що можна перевірити вручну. Рецензент відкриває репозиторій, упирається в порожній README, биту команду запуску і файл final_final_v2.md — і довіра просідає ще до вашого першого слова.

Submission package — це не один репозиторій і не одне посилання на демо. Це набір артефактів, які разом відповідають: що ви зробили, як це запустити, що саме перевірили і де межі проєкту. Зручно думати про нього як про папку здачі інженерної роботи: сам об’єкт плюс паспорт, інструкція, журнал робіт і позначки про те, що ще не доведено до production.

Усе це особливо важливо в AI-assisted розробці. Коли в роботі брав участь Claude Code, рецензенту потрібна traceability: де постановка задачі, де evidence, де запуск перевірок, де ваше рішення, а де допомога інструмента. Package збирають з уже наявних артефактів, а не вигадують заднім числом.

Нижче корисно тримати в голові дуже просту схему:

flowchart TD
    A[Репозиторій] --> B[README і setup]
    B --> C[SPEC.md]
    C --> D[EVIDENCE.md]
    D --> E[Тести і checks]
    E --> F[Demo / screenshots / video]
    F --> G[Відомі обмеження]
    G --> H[Довіра рецензента]

Якщо хоча б одна ланка випадає, уся ланка починає хитатися. Проєкт може бути непоганим, але враження буде приблизно як від кухні без інструкції зі збирання: деталі хороші, а де дверцята, де стінка — здогадайтеся самі.

2. З чого зібрано сильний package

Найчастіша помилка на цьому етапі — думати, що package треба дописувати з нуля. Насправді майже все основне у вас уже є з попередніх модулів. Завдання — зібрати це в несуперечливу структуру, щоб рецензент за кілька хвилин зрозумів, куди дивитися і в якому порядку.

Ось практичний орієнтир для структури:

my-capstone/
  README.md
  SPEC.md
  EVIDENCE.md
  DEMO.md
  TEST_PLAN.md
  .env.example
  ARCHITECTURE.md
  MIGRATION.md
  ROLLBACK_PLAN.md

Частина цих файлів обов’язкова майже для будь-якого capstone, частина залежить від формату проєкту. Зручно бачити це в таблиці.

README.md

SPEC.md

EVIDENCE.md

DEMO.md

README

TEST_PLAN.md

.env.example

ARCHITECTURE.md

MIGRATION.md

ROLLBACK_PLAN.md

RISK_MAP.md

COMPATIBILITY_MATRIX.md

Якщо у вас MVP, package зазвичай будується навколо

README

SPEC.md

EVIDENCE.md

MIGRATION.md

Дуже важливий

README

Ось компактний каркас, який зазвичай працює:

## Швидкий старт

1. Скопіюйте `.env.example` у локальний env-файл
2. Встановіть залежності
3. Запустіть проєкт командою з цього розділу
4. Відкрийте сценарій з `DEMO.md`
5. Виконайте команди перевірки з розділу `Перевірка`

Команди у вашому проєкті будуть свої — десь docker compose up, десь npm run dev, десь ./gradlew bootRun, десь uvicorn. Важливі не назви, а те, що за цими кроками реально можна стартувати з чистого стану — без шаманства й телепатії.

3. Reproducibility audit: п’ять питань довіри

Reproducibility audit звучить трохи урочисто, але по суті це дуже земна річ. Ви берете свій capstone і перевіряєте: чи пройде стороння людина шлях від клонування репозиторію до core flow за документами всередині проєкту — без ваших усних пояснень, без переписки в чаті.

Головна сила цього аудиту в тому, що він закриває одразу п’ять питань довіри:

README.md

SPEC.md

.env.example

TEST_PLAN.md

EVIDENCE.md

README

Тут ключове слово — узгодженість. Якщо в

SPEC.md

README

Саме тому reproducibility audit — це trust mechanism, а не косметика: рецензент довіряє не вашій упевненості, а маршруту перевірки.

Хороша новина в тому, що аудит майже завжди знаходить не «фатальну катастрофу», а дрібні розриви: десь немає команди, десь demo-крок застарів, десь limitations живуть у вашій голові, а не в репозиторії. І краще ви спіймаєте це самі, ніж ментор на захисті.

4. Прогін на чистому середовищі

Найкорисніший спосіб провести аудит — зіграти в «сторонню людину». Відкрити не свій робочий каталог із налаштованими залежностями, а свіжий клон і пройти лише маршрутом з package. Якщо запуск потребує знання, якого немає в

README

Правило прогону просте: ви не підглядаєте в старий термінал, не берете команди з пам’яті, не правите документацію під час прогону, доки не зафіксували проблему. Інакше вийде не аудит, а м’яка самоіндульгенція.

Шаблон такого прогону може бути дуже простим:

git clone <repo-url> capstone-check
cd capstone-check
cp .env.example .env.local     # якщо проєкт використовує env-файл
<команда встановлення залежностей>
<команда запуску проєкту>      # застосунок має стартувати без ручних правок
<команда перевірок>             # очікуємо успішний результат

Якщо у вас контейнерний проєкт, ви, найімовірніше, використовуватимете docker compose up -d. Java-проєкт — ./gradlew test або ./gradlew bootRun. Python — pip install -r requirements.txt і запуск сервісу. Конкретика залежить від формату capstone, логіка одна: усі критичні кроки видно зсередини package.

Окремо важливо прогнати core flow, а не лише технічний запуск: зелена збірка — не фініш. Якщо в

DEMO.md

.claude

Дуже допомагає фіксувати знахідки одразу — в таблицю або нотатку: «крок 3 незрозумілий», «не вистачає версії Node», «команда запуску в README застаріла», «скриншот не відповідає інтерфейсу». Це не дрібниці: з них складається враження «проєкту можна довіряти» або «автор востаннє запускав це тільки у себе».

5. README, EVIDENCE.md і known limitations

Є три файли, які недооцінюють особливо часто:

README.md

EVIDENCE.md

README.md

EVIDENCE.md

Не менш важливі known limitations. Новачки часто бояться їх писати — здається, ніби це визнання слабкості. Насправді все навпаки: відсутність обмежень виглядає підозріло. Межі є в будь-якого capstone: демо-режим замість бойової авторизації, відсутність retry, підтримка лише CSV, непокриті edge cases, локальний запуск без production deployment. Назвали чесно — і рецензент бачить: автор розуміє реальний обсяг проєкту і не продає прототип як космічний корабель.

Простий і сильний шаблон:

## Відомі обмеження

- підтримується лише один core-сценарій, описаний у `DEMO.md`;
- авторизацію замінено деморежимом і вона не призначена для production;
- звіти перевірено на тестових даних;
- retry для зовнішнього API поки що не реалізовано.

Зверніть увагу: тут немає ні виправдань, ні драматизму, ні «не судіть суворо». Тільки факти. Саме такий тон і створює довіру.

Сюди ж належить і фінальна гігієна публікації. У package не повинно бути реальних

.env

Коли package зібрано правильно, з ним стається приємна річ: проєкт починає триматися сам. Його можна відкрити без вас, запустити без дзвінка автору, перевірити без ворожіння й оцінити без знижки на хаос. Це і є головний знак готовності до захисту — не «я втомився і хочу натиснути здати», а «зовнішня людина дійде від репозиторію до результату й не втратить до вас довіру дорогою».