Defense handoff package для 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[Reviewer]

Обратите внимание на самое важное место в этой схеме: 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.

## Что важно проверить
Core flow: 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-assisted работы:

Такой стиль работает сразу в две стороны: ревьюер видит вашу зрелость, а вам самим потом легче отвечать, что делал 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      # build ok

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

И вот здесь появляется очень полезный ориентир. Если вы спустя день без усилия проходите по своему репозиторию как чужой человек — сможет и ревьюер. А это уже не магия, а аккуратно сделанная инженерная упаковка результата. На таком пакете и держится защита: видно, что запуск воспроизводим, demo path собран, решения и ограничения названы честно.

1

Задача

Claude code, 31 уровень, 4 лекция

Недоступна

Handoff verification script для reviewer-ready пакета

Handoff verification script для reviewer-ready пакета

Открыть

1

Задача

Claude code, 31 уровень, 4 лекция

Недоступна

Полный reviewer-ready HANDOFF_PACKAGE.md

Полный reviewer-ready HANDOFF_PACKAGE.md

Открыть

1

Опрос

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

Недоступен

Sprint и готовность к демо

Sprint и готовность к демо

Открыть