Упаковка capstone после ревью

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

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

Хорошая упаковка после review не переписывает проект заново. Она берёт Review log, REMEDIATION.md, accepted limitations и возвращает их в собранный package — иначе получается странная ситуация: mentor увидел одно, а репозиторий по-прежнему обещает другое.

Полезно быстро свериться с очень простой картой:

flowchart TD
    A[Review log] --> B[REMEDIATION.md]
    B --> C[Обновлённые README / DEMO / EVIDENCE]
    C --> D[Repo polish]
    D --> E[Final public snapshot]

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

Чтобы разговор был конкретным, примеры дальше я буду показывать на небольшом capstone Support Inbox Assistant — это AI‑ассистент для поддержки интернет-магазина. Если у вас не веб-приложение, а migration slice, DevOps automation или team workflow design, логика остаётся той же: вместо карточек интерфейса у вас будут build-логи, validation report, diff policy или демонстрация пайплайна.

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 project для ускорения обработки типовых тикетов поддержки.

## Что делает проект

Система принимает обращения, классифицирует их по типу и предлагает черновик ответа
для оператора. Core flow: загрузка тикета → классификация → draft ответа → подтверждение оператором.

## Быстрый запуск

```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. Показать draft ответа для 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. Сервис обработки — выполняет классификацию и генерирует draft ответа.

Хранилище используется только для тестовых данных и истории демо-сценариев.
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: загрузка тикета, классификация, draft ответа, подтверждение оператором.

## Ограничения
Нет поддержки вложений, мультиязычности и интеграции с внешней 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

Проект помогает оператору поддержки быстрее обрабатывать типовые обращения.

## Что решает
Уменьшает время на классификацию тикета и подготовку первого ответа.

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

## Что проверено
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, а готовите набор доказательств, с которым можно выходить наружу без новой сборки истории.