Упаковка capstone після ревʼю

1. Після хорошого ревʼю робота ще не закінчена

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

Хороша упаковка після review не переписує проєкт заново. Вона бере Review log, REMEDIATION.md, accepted limitations і повертає їх у зібраний package — інакше виходить дивна ситуація: mentor побачив одне, а репозиторій досі обіцяє інше.

Корисно швидко звіритися з дуже простою картою:

flowchart TD
    A[Журнал review] --> B[REMEDIATION.md]
    B --> C[Оновлені README / DEMO / EVIDENCE]
    C --> D[Полірування repo]
    D --> E[Фінальний публічний snapshot]

Сенс тут дуже приземлений: ви не вигадуєте новий package наприкінці роботи, а добиваєтеся того, щоб README, demo, evidence і backlog не суперечили одне одному. Саме в цей момент захист перестає бути разовим виступом і перетворюється на стійку публічну версію проєкту.

Щоб розмова була конкретною, далі приклади я показуватиму на невеликому capstone Support Inbox Assistant — це AI-асистент для підтримки інтернет-магазину. Якщо у вас не вебзастосунок, а migration slice, DevOps automation або team workflow design, логіка лишається тією самою: замість карток інтерфейсу у вас будуть build-логи, validation report, diff policy або демонстрація pipeline.

2. README — це двері, а не килимок

Якщо review спіткнувся об документацію, насамперед дивляться в README.md. Це головний вхідний файл, тож саме в ньому найшвидше видно розсинхрон між обіцяним і реальним. З нуля переписувати не потрібно: поверніть те, що mentor підсвітив — missing runtime versions, зайві ручні кроки, застарілий demo-path, обмеження, які були у вас у голові, але не на папері.

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

Дуже часта помилка — писати README як короткий щоденник розробки: три абзаци про натхнення, історія стека, список залежностей, і десь унизу випадково лежить команда запуску. Так робити не треба. Зверху README відповідає на просте: що це, яку проблему розвʼязує, як швидко підняти, чим перевірити core flow, де прочитати про обмеження.

Наприклад, верхня частина README.md у вашого capstone може виглядати так:

# Support Inbox Assistant

Demo-ready capstone-проєкт для пришвидшення обробки типових тікетів підтримки.

## Що робить проєкт

Система приймає звернення, класифікує їх за типом і пропонує чорновик відповіді
для оператора. Core flow: завантаження тікета → класифікація → чорновик відповіді → підтвердження оператором.

## Швидкий запуск

```bash
docker-compose up --build
```

Після запуску відкрийте локальний інтерфейс і завантажте тестовий набір тікетів із `demo-data/`.

## Перевірка

```bash
pytest -q
```

Додатково подивіться `DEMO.md` для сценарію показу і `EVIDENCE.md` для verification trail.

## Обмеження

MVP підтримує лише текстові тікети, без вкладень і без мультимовності.

Якщо на review зʼясувалося, що для запуску потрібні версії Python і Node, окремі сіди або ще один сервіс, саме README має сказати це першим — не усне пояснення, не особисте повідомлення, не нотатка на робочому столі.

3. Demo показує поведінку, а не обіцянки

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

Сам файл DEMO.md краще робити дуже коротким і конкретним:

# Demo

## Сценарій
1. Підняти проєкт через `docker-compose up --build`
2. Відкрити інтерфейс локально
3. Завантажити файл `demo-data/tickets.csv`
4. Показати класифікацію трьох тікетів
5. Показати чорновик відповіді для refund-запиту
6. Запустити `pytest -q` і показати зелений результат

## Очікуваний результат
Оператор бачить клас тікета, запропоновану відповідь і може підтвердити надсилання.

## Якщо відео недоступне
Див. папку `assets/demo/` зі скриншотами і `README.md` для локального повторення.

Зверніть увагу на останню частину. У demo завжди має бути запасний шлях. Посилання на відео, яке живе три дні, — погана ідея. Live demo, який працює «зазвичай, якщо хмара сьогодні в настрої», — теж. Надійніший локально відтворюваний сценарій і стабільні файли.

Ще один важливий нюанс: demo показує один core flow від початку до кінця, а не екскурсію «а ось тут у мене ще кнопка, і ця сторінка теж симпатична». Це виглядає скромніше, але переконує сильніше.

4. Архітектурна нотатка: карта, а не роман

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

Для простого capstone ARCHITECTURE.md уміщується на пів сторінки — його задача показати ключові блоки і потік даних:

# Архітектура проєкту

Проєкт складається з трьох основних частин:

1. Web UI — інтерфейс оператора підтримки.
2. API-шар — приймає вхідні дані і віддає результат класифікації.
3. Сервіс обробки — виконує класифікацію і генерує чорновик відповіді.

Сховище використовується лише для тестових даних і історії демо-сценаріїв.
Auth, черги і зовнішні інтеграції до MVP не входять.

Якщо хочеться зробити наочніше, можна додати просту схему:

flowchart LR
    A[Оператор] --> B[Web UI]
    B --> C[API]
    C --> D[Сервіс класифікації]
    D --> E[Тестові дані / сховище]

Для migration slice така схема буде іншою, але принцип той самий: показати звʼязку блоків, не все підряд. Наприклад: старий модуль → проміжний адаптер → новий runtime → verification suite. Reviewer має зрозуміти форму системи швидше, ніж устигне втомитися.

Поряд із архітектурною нотаткою добре працює коротка картка проєкту — по суті міні case study на одну сторінку, щоб будь-яка зовнішня людина зрозуміла ваш capstone без глибокого читання репозиторію.

# Картка проєкту

## Проблема
Оператори підтримки витрачають занадто багато часу на ручну обробку типових звернень.

## Для кого
Для команди підтримки невеликого інтернет-магазину.

## Розв’язання
Проєкт класифікує тікети і пропонує оператору чорновик відповіді.

## Що перевірено
Покрито core flow: завантаження тікета, класифікація, чорновик відповіді, підтвердження оператором.

## Обмеження
Немає підтримки вкладень, мультимовності та інтеграції із зовнішньою CRM.

## Наступний крок
Додати історію рішень оператора і розширити набір сценаріїв регресії.

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

5. Роль Claude Code — одне точне формулювання

Цю частину найчастіше уточнюють саме після review. Поки проєкт живе у автора, фраза «Claude допомагав по всьому проєкту» здається нешкідливою, — а після першого ж уточнювального питання стає видно, що вона нічого не доводить. Тому потрібна не нова легенда, а одне точне формулювання, яке однаково тримається в README.md, EVIDENCE.md і картці проєкту.

Добре працює проста рамка з трьох питань: що робив я? де допоміг Claude Code? чим я це перевірив? Якщо ви відповідаєте на всі три, формулювання стає сильним і безпечним.

Ось хороший шаблон для README або картки проєкту:

## Роль AI у проєкті

Claude Code допомагав на етапах аналізу задачі, чорнової реалізації,
генерації тестових заготовок і редагування документації.

Моя відповідальність включала постановку задачі, вибір scope,
перевірку diff, запуск tests/checks, ухвалення архітектурних рішень
і підготовку фінального demo.

А ось корисна таблиця «як не треба» і «як треба»:

Тут важливіша точність, ніж кількість механізмів. Одного чесного запису про plan-first, diff review і smoke-check зазвичай достатньо. Пʼять незрозумілих хуків без пояснення користі — ні.

6. Межі проєкту — показувати, а не ховати

Якщо review знайшов дірку, не треба робити вигляд, ніби її не було. У вас лише три чесні ходи: виправити проблему, записати її в REMEDIATION.md як backlog або оформити як accepted limitation там, де людина очікує побачити межі проєкту. EVIDENCE.md тут не прикраса, а слід того, що саме ви перевірили і що змінили після review.

Якщо після review ви закрили setup-gap, додали scenario-level test або звузили scope, це має зʼявитися не лише в коді, а й в артефактах.

Невеликий фрагмент REMEDIATION.md може виглядати так:

# REMEDIATION

## Must fix
- Додати явну обробку порожнього тікета: зараз сценарій падає на валідації.
- Уточнити версію Python у README: setup на чистій машині відтворюється не завжди.

## Should fix
- Додати regression test для refund-ticket із порожнім коментарем.
- Розширити demo-датасет ще двома негативними прикладами.

## Пізніше
- Інтеграція з CRM
- Мультимовність

Такий файл не послаблює проєкт — він робить його чесним: видно, що ви не плутаєте «я знаю про проблему і зафіксував її» з «ой, сподіваюся, ніхто не помітить». Те саме стосується known limitations у README.md: якщо прямо написати, що MVP не підтримує вкладення, це звучить доросліше, ніж якщо reviewer дізнається про це сам на demo.

Саме тому не варто прибирати ці артефакти заради хибного блиску: портфельний проєкт — не рекламний плакат, а зрозумілий і чесний технічний об’єкт.

7. Фінальне полірування репозиторію

Коли README.md, DEMO.md, EVIDENCE.md і remediation уже синхронізовані, залишається остання приземлена робота — навести лад у самому репозиторії. Навіть добрий capstone може виглядати недбало, якщо в корені лежать пʼять чернеток, старий notes-final-final-2.md і папка tmp, про походження якої краще не питати. Репозиторій не зобовʼязаний бути стерильним, але має виглядати так, ніби ним керували свідомо.

Мінімальне полірування зазвичай включає зрозумілу структуру кореня, стабільні назви, відсутність приватних даних, видалення чернеток і фінальну самоперевірку. Тут допомагають навіть дуже прості команди:

git status                         # робоче дерево має бути чистим
git grep -n "TODO\|FIXME" .        # шукаємо забуті заглушки
git grep -n ".env" README.md DEMO.md

Перша команда банальна, але важлива: брудне дерево перед публікацією майже завжди означає, що щось не дороблено або не синхронізовано. Друга допомагає впіймати покинуті «потім виправлю». Третя ловить інструкції на кшталт «візьміть мій локальний .env і якось розберіться».

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

Ще один корисний прийом — зібрати зрозумілі папки для зовнішніх матеріалів: assets/demo/ для скриншотів, docs/ для архітектурної нотатки. Тоді reviewer не має грати в археолога, розшукуючи demo-скриншот між тимчасовим JSON і експортом тестів.

Окремо має сенс перевірити і короткий опис репозиторію — рядок під назвою проєкту. Не “My cool AI stuff”, а щось на кшталт “Demo-ready capstone for support ticket triage with reproducible setup and test evidence”. Це маленький рядок, але він одразу задає правильне очікування.

8. Портфельна картка: чітка зовнішня версія

Коли README.md, demo, evidence і сам репозиторій уже вичищені, з них майже автоматично складається зовнішня картка проєкту. Це ще не адаптація під конкретну вакансію і не текст у резюме — просто одна акуратна публічна версія capstone, яку можна показати будь-кому: ментору, колезі, знайомому розробнику, потенційному reviewer. Її мета — не продати проєкт, а швидко й чесно пояснити, що ви зробили.

Хороша картка зазвичай уміщується на одну сторінку і відповідає на ті самі питання, що й повний набір артефактів, тільки коротше:

# Support Inbox Assistant

Проєкт допомагає оператору підтримки швидше обробляти типові звернення.

## Що вирішує
Зменшує час на класифікацію тікета і підготовку першої відповіді.

## Основний потік
Завантаження тікета → класифікація → чорновик відповіді → підтвердження оператором.

## Що перевірено
Pytest для core flow, smoke-сценарій із `DEMO.md`, ручний прогін на демо-наборі.

## Роль AI
Claude Code використовувався для аналізу задачі, чорновиків тестів і документації.
Scope, архітектура, diff review і фінальна перевірка були на моєму боці.

## Обмеження
Немає вкладень, мультимовності та інтеграції з CRM.

## Що далі
Історія дій оператора, додаткові негативні сценарії, CI pipeline.

Зверніть увагу на останню секцію. «Що далі» — не визнання поразки, а нормальний roadmap: будь-який живий проєкт можна розвивати, і коли ви спокійно це визнаєте, він виглядає дорослішим, а не слабшим.

Тут же доречний короткий блок «Чого мене навчив проєкт» — якщо він справді додає сенсу, а не перетворюється на мотиваційний плакат: «навчив відділяти demo-ready scope від production-ready очікувань», «навчив перевіряти AI-згенеровані тести», «навчив працювати через evidence, а не через впевненість моделі». Корисно, коли конкретно й виростає з проєкту.

Саме в цей момент capstone перестає бути просто навчальним фіналом курсу. Людина відкриває репозиторій, швидко розуміє задачу, бачить, що працює, як ви працювали, і що ви не ховаєте обмеження. Це і є те саме відчуття довіри, заради якого робиться вся упаковка.

Саме цей public snapshot потім ляже в Career Evidence Bank: README.md дасть короткий опис, DEMO.md і картка — портфельний walkthrough, EVIDENCE.md і REMEDIATION.md — чесний interview narrative про рішення, перевірки і межі. Тобто зараз ви не перепридумуєте capstone, а готуєте набір доказів, з яким можна виходити назовні без нового збирання історії.