Пакет handoff для захисту capstone

1. Хороший проєкт без handoff package виглядає сирим

Коли ви дивитеся на свій capstone, вам здається, що все очевидно. Ви памʼятаєте, чому вирізали одну фічу й залишили іншу в LATER, де Claude Code допоміг, а де ви його жорстко зупинили. Ревʼюер не жив у вашій голові й не бачив нічної битви з CSV. Завдання пакета приземлене — провести ревʼюера проєктом у правильному порядку: яку проблему ви розвʼязували, який scope взяли, як запустити, як подивитися demo, чим перевірено й що чесно залишилося за межею слайса.

Тут важливо не плутати два схожі артефакти. HANDOFF_NOTE.md, з яким ви стикалися раніше, — коротка передача стану між сесіями. HANDOFF_PACKAGE.md — пакет для ревʼюера, який дивиться на весь capstone як на завершений, хай і обмежений, інженерний результат.

Зручно тримати це в голові як просту схему:

flowchart TD
    A[Проблема] --> B[SPEC.md]
    B --> C[Реалізація]
    C --> D[EVIDENCE_LOG.md]
    C --> E[DEMO.md]
    C --> F[README.md]
    D --> G[HANDOFF_PACKAGE.md]
    E --> G
    F --> G
    B --> G
    G --> H[Ревʼюер]

Зверніть увагу на найважливіше місце в цій схемі: HANDOFF_PACKAGE.md не підміняє інші документи, а зʼєднує їх. Не нова правда про проєкт, а навігаційна карта наявних артефактів. Коли такий міст зібрано, у ревʼюера майже готова канва захисту.

2. Склад пакета без звалища

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

Нижче — мінімальний набір для capstone demo.

README.md

SPEC.md

DEMO_QUALITY_GATE.md

DEMO.md

EVIDENCE_LOG.md

HANDOFF_PACKAGE.md

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

DEMO_QUALITY_GATE.md тут корисно тримати в окремій голові. Це не заміна HANDOFF_PACKAGE.md, а внутрішній stop/go-документ: додатковим підтвердженням його можна додати, але маршрут усе одно задає handoff package.

На практиці корисно вибрати одне стабільне місце. Наприклад, README.md, SPEC.md, EVIDENCE_LOG.md, HANDOFF_PACKAGE.md — у корені репозиторію, скриншоти — в docs/screens/. Зручніше в docs/handoff/ — теж нормально. Головне, щоб структура не вимагала квесту на пʼять кліків і шаманського знання, де ви вчора сховали файл з обмеженнями.

3. HANDOFF_PACKAGE.md — маршрут, а не переказ

Дуже спокусливо відкрити новий файл і почати накопіювати туди шматки з README, SPEC, EVIDENCE, DEMO. На ділі виходить навпаки: зʼявляються дві версії однієї інформації, і вони розходяться. Центральний файл пакета — маршрут, а не переказ: він відповідає на «з чого почати й куди йти далі». Відкрив ревʼюер лише його — і зрозумів, у якому порядку читати решту. Майже зміст, тільки прикладний.

Наприклад, структура проєкту може виглядати так:

personal-cfo/
├── README.md
├── SPEC.md
├── EVIDENCE_LOG.md
├── HANDOFF_PACKAGE.md
├── DEMO.md
└── docs/
    └── screens/

А каркас самого HANDOFF_PACKAGE.md може бути таким:

# HANDOFF_PACKAGE.md

## Проєкт
Personal CFO: імпорт CSV і місячний фінансовий звіт.

## З чого почати
Спочатку відкрийте README.md, потім SPEC.md і DEMO.md.

## Що важливо перевірити
Основний потік: CSV → категорії → monthly report.
Тести: `pytest -q`  # 12 passed

## Обмеження
Див. README.md, розділ Known limitations.

Це коротко, але вже працює: порядок читання задано, історію не продубльовано. Ще один добрий прийом — додати маленьку таблицю відповідностей між типовими питаннями ревʼюера та вашими файлами:

Це маленька деталь, але вона робить пакет дорослим: він перестає бути «папкою документів» і перетворюється на зрозумілий інженерний маршрут.

4. Роль EVIDENCE_LOG.md: процес, а не виправдання

Багато студентів думають, що ревʼюера найбільше цікавить фінальний код. Насправді його цікавить і процес: результат без слідів перевірки виглядає як удача або вдалий вихід нейромережі. EVIDENCE_LOG.md потрібен саме для того, щоб показати — результат не випадковий.

Найчастіша помилка тут — спроба перетворити лог на стенограму всіх чатів із Claude Code: кожну вашу репліку ревʼюер читати не зобовʼязаний. Набагато корисніші короткі структуровані записи за ключовими слайсами: що змінювали, як Claude допоміг, що прийняли або відхилили, чим перевірили, яке рішення залишили за собою.

Ось приклад нормального запису:

## 2026-05-18 — Імпорт CSV

Claude допоміг знайти проблему з UTF-8 BOM у `csv_parser.py`.
Я прийняв виправлення парсингу, але відхилив зайве рефакторення сервісу.
Перевірив: `pytest -q tests/test_import.py`  # 6 passed
Smoke: `data/sample.csv` створює звіт за квітень.
Ризик: файли понад 10MB поки не тестував.

Зверніть увагу: тут немає пафосу й немає містики. Ви не пишете «Claude блискуче оптимізував систему». Ви фіксуєте конкретний інженерний факт: ось де була проблема, ось яку частину AI-пропозиції ви прийняли, ось як перевірили, ось який ризик залишився.

Дуже корисно стежити за формулюваннями. Нижче різниця між слабким і сильним описом роботи за участю AI:

Такий стиль працює одразу в дві сторони: ревʼюер бачить вашу зрілість, а вам самим потім легше відповідати, що робив Claude Code, а що ви, — уже не «ну він допомагав», а нормальна інженерна історія.

5. Обмеження, питання і реалістичні next steps

Майже кожен студент у якийсь момент боїться писати обмеження: здається, що чесний список недоробленого послаблює проєкт. На практиці відбувається навпаки. Ревʼюер сильніше довіряє проєкту, де автор спокійно каже: ось що працює, ось що свідомо не ввійшло до слайса, а ось де я не вдаю, що все ідеально.

Добрі обмеження завжди конкретні. Не «є дрібні баги», а «файли понад 10MB не перевірялися». Не «авторизація поки умовна», а «в demo один тестовий користувач, повноцінний signup поза scope». Так видно, що ви розумієте систему.

Ось як це може виглядати в README:

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

- Усі приклади працюють у USD, multi-currency поки немає.
- У demo використовується один тестовий користувач.
- Імпорт CSV перевірено до 10MB.
- Реальні банківські API не підключено.

Такий розділ особливо добре виглядає в проєктах на кшталт Personal CFO. Якби ви робили Landing Optimizer, обмеження були б іншими: немає прямої інтеграції з рекламними кабінетами, аналіз працює за URL і введеним описом аудиторії, а не за реальною статистикою кампаній. Суть та сама: limitation не ховається.

Поруч із обмеженнями добре працює невеликий блок «що я хочу отримати від review». Це вже не захист, а доросла інженерна позиція: ви прийшли не лише за оцінкою, а й за точковим зворотним звʼязком.

## Що я хочу отримати від review

1. Чи нормально винесено `CsvImportService` в окремий модуль?
2. Які edge cases імпорту я ще не покрив тестами?
3. Чи варто залишати multi-currency у `LATER`, а не тягнути в demo?

І, нарешті, Next steps. Тут головне — не перетворювати цей блок на маркетинговий roadmap рівня «через тиждень буде production-ready SaaS». Краще три-чотири спокійні, реалістичні кроки: додати multi-currency, розширити coverage на великі CSV, підключити нормальну авторизацію, завести логи помилок імпорту. Такий список показує, що ви розумієте наступну ітерацію.

6. Збираємо handoff package на прикладі Personal CFO

Давайте зберемо все на наскрізному прикладі Personal CFO. Core flow працює, demo відрепетировано, smoke checks зелені.

Спочатку ви відкриваєте README й переконуєтеся, що там є швидкий старт, цінність, обмеження. Не «фінансова суперплатформа нового покоління», а «інструмент для solopreneur, щоб швидко побачити місячний cashflow за CSV».

Потім ви дивитеся на SPEC.md. Там має бути видно, чому scope саме такий — один core flow, без банківських API, без багатосторінкової аналітики й повнорозмірної бухгалтерії, якій у курсі не місце. Чесні non-goals — і ревʼюер не спитає, чому немає пʼяти функцій, які ви ніколи не обіцяли.

Далі ви доводите EVIDENCE_LOG.md до стану «коротко, але конкретно», без порожніх місць за ключовими слайсами. Особливо зафіксуйте випадки, де Claude Code пропонував ширше, а ви втримали зміни: це показує controlled workflow.

Після цього збираєте HANDOFF_PACKAGE.md — всередині не потрібно писати роман, вистачить короткої карти:

# HANDOFF_PACKAGE.md

## Що зроблено
Personal CFO: CSV → категорії → monthly report.

## Де дивитися
README.md → SPEC.md → DEMO.md → EVIDENCE_LOG.md

## Як перевірити
`docker compose up -d`
`pytest -q`  # 12 passed

## Що важливо знати
Обмеження і next steps описано нижче в цьому файлі та в README.md.

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

Та сама логіка майже без змін переноситься на Landing Optimizer: замість «CSV → категорії → monthly report» — інший core flow, «URL landing page → AI-аналіз → backlog гіпотез». Ролі документів ті самі: README — цінність, SPEC — межі, DEMO — сценарій, EVIDENCE — перевірка, HANDOFF_PACKAGE — маршрут.

7. Перевірка пакета чужими очима

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

Добрий тест починається з чистого старту. Відкриваєте README, йдете своїми ж посиланнями та командами й дивитеся, чи не тримається проєкт на «ну я ж знаю, де це лежить». Зламається quickstart, HANDOFF_PACKAGE.md заведе в нікуди, обмеження виявиться лише у вас у голові — тест це швидко покаже.

Для такого прогону часто вистачає буквально трьох команд:

docker compose up -d
pytest -q          # 12 passed
npm run build      # збірка ok

Після цього відкрийте HANDOFF_PACKAGE.md і поставте собі кілька простих питань. Чи розумію я завдання, не відкриваючи код? Чи можу відтворити demo за DEMO.md? Чи бачу, чим підтверджено результат? Чи розумію, що ще не готово? Відповідь «ну взагалі-то я це знаю, просто не написав» — означає, що пакет ще не зібрано.

І ось тут зʼявляється дуже корисний орієнтир. Якщо ви через день без зусиль проходите своїм репозиторієм як чужа людина — зможе і ревʼюер. А це вже не магія, а акуратно зроблена інженерна упаковка результату. На такому пакеті й тримається захист: видно, що запуск відтворюваний, demo path зібрано, рішення й обмеження названо чесно.

1

Опитування

Sprint і готовність до демо, рівень 31, лекція 4

Недоступний

Sprint і готовність до демо

Sprint і готовність до демо

Відкрити