Handoff контекста: сохранить прогресс, переехать при необходимости

Сохрани контекст проекта в HANDOFF.md: создай файл или обнови существующий. После этого любая новая сессия — и эта же после сжатия контекста — должна знать о проекте столько же, сколько ты сейчас.

Всё нужное определи сам из контекста чата: проект, путь, над чем работали, что дальше. Не переспрашивай. Юзер написал что-то рядом с этим промтом — это цель или уточнение, учти. Контекст уже сжимался и деталей не хватает — бери их из git log, диффа и живого smoke, а не по памяти.

Работай сам, без субагентов — запускай их только по явной просьбе юзера. И экономно: HANDOFF пишется из того, что уже известно в этом чате, плюс точечные проверки. Код целиком не перечитывай.

Главное: заполненный контекст — не повод переезжать

В Claude Code есть автокомпакт: когда контекст почти заполнен, история сжимается, и работа продолжается в том же чате. Поэтому по умолчанию этот промт — сохранение прогресса: обновил HANDOFF и продолжаешь здесь.

HANDOFF всё равно нужен. Сжатие — это пересказ: точные цифры, команды и причины решений в нём теряются, и живёт он только внутри этой сессии. HANDOFF лежит в git, его читает любая сессия.

Чтобы после сжатия ничего не терялось, нужны три части:

1. HANDOFF.md — факты, ловушки, команды (шаги 1-2).
2. Указатель в CLAUDE.md — любая сессия знает, что HANDOFF надо читать (шаг 3).
3. Хук после сжатия — напоминает перечитать HANDOFF сразу после автокомпакта, когда это нужнее всего (шаг 4).

Шаг 1. Создать или обновить HANDOFF.md

Файла нет — создай по шаблону ниже.

Файл есть — обнови точечно, не переписывай:

• §3 цифры и §6 сделанное — актуальные значения;
• §7 open items — закрытое зачеркни и напиши, что закрыло; новое добавь;
• §7 ловушки — новые допиши в конец нумерованного списка; подсекции нет — создай и перенеси туда грабли, уже описанные в тексте;
• §8 команды — только если поменялись;
• «Последнее обновление» и одна строка в историю итераций;
• §9 не трогай, если юзер в этом чате не менял стиль или красные линии. Исключение — правило про агентов: его нет — добавь; написано обратное («при большой задаче запускай агентов сам») — замени, если юзер в этом чате не подтвердил старый вариант.

Существующее не удаляй без причины и не меняй номера секций: на них ссылаются другие документы. С прошлого сохранения добавить нечего — файл не трогай.

Шаг 2. Smoke и сверка

Прогони smoke из §8. Для сервиса — реальные страницы, API, статус процесса; для библиотеки или CLI — тесты и сборка. В §8 smoke нет — составь и запиши туда. Цифры в HANDOFF должны совпадать с тем, что видно сейчас. Нашёл расхождение — исправь HANDOFF и назови его юзеру.

Шаг 3. Указатель в CLAUDE.md проекта

В CLAUDE.md в корне проекта должна быть строка (нет файла — создай, нет строки — допиши в конец):

Контекст проекта — в HANDOFF.md: факты, ловушки, команды. Прочитай его перед нетривиальной работой и после сжатия контекста.

CLAUDE.md подгружается в каждую сессию и переживает сжатие, поэтому про HANDOFF знает любая сессия, даже без стартовой фразы. Но это инструкция, а не механизм: когда её выполнить, модель решает сама. А пересказ после сжатия выглядит полным, и перечитать HANDOFF легко забыть. Эту дыру закрывает шаг 4.

Шаг 4. Хук: напоминание сразу после сжатия

Хук — команда, которую Claude Code сам запускает по событию; её вывод попадает модели в контекст. Этот хук срабатывает после каждого сжатия, ручного и автоматического, и печатает одну строку — только в проектах, где есть HANDOFF.md. Больше он ничего не делает.

Сначала проверь, не стоит ли он уже: поищи HANDOFF.md в hooks.SessionStart в ~/.claude/settings.json и в .claude/settings.json проекта. Нашёл — пропусти шаг. Нет — добавь в ~/.claude/settings.json: ставится один раз на компьютер и дальше работает во всех проектах.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "f=\"${CLAUDE_PROJECT_DIR:-$PWD}/HANDOFF.md\"; if [ -f \"$f\" ]; then echo \"Контекст только что сжат: в пересказе теряются точные цифры, команды и ловушки. Прежде чем продолжать работу, прочитай $f целиком.\"; fi",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

• Файл уже есть — добавь элемент с "matcher": "compact" в массив hooks.SessionStart (массива нет — создай), всё остальное оставь как было: чужие хуки и настройки должны уцелеть. Файла нет — создай с этим блоком.
• Проверь: JSON валиден (например, jq . ~/.claude/settings.json); команда, запущенная в корне проекта, печатает напоминание с путём к HANDOFF, а в папке без HANDOFF — ничего. Команда написана для sh: macOS, Linux, Windows с Git Bash.
• Нужно в облачных сессиях или всей команде — положи тот же блок в .claude/settings.json проекта и закоммить. Одинаковый хук из двух файлов срабатывает один раз.
• Весь HANDOFF хуком не выводи: вывод хука ограничен 10 000 символов, сверх лимита в контекст попадает только превью.

Шаг 5. Коммит

Проект в git — закоммить одним коммитом всё, что поменялось: HANDOFF.md, CLAUDE.md и .claude/settings.json, если хук ставил в проект. Ничего не поменялось — не коммить.

Шаг 6. Продолжаем здесь или новый чат

Новый чат нужен только при одном из сигналов:

• сессия сломалась или зависла: повторяются ошибки API, инструменты перестали отвечать;
• после нескольких сжатий упало качество: переспрашиваешь решённое, путаешь решения, противоречишь HANDOFF;
• дальше другая, несвязанная задача — старая история станет шумом (в этом же чате то же даёт /clear);
• юзер сам просит переехать.

Сигнала нет — так и скажи: «продолжаем здесь». Заполненный контекст сам по себе не сигнал.

Шаблон HANDOFF.md

# <Имя проекта> — Handoff

> Читай это прежде чем что-то трогать: где мы, куда дальше, что нельзя.
> Обновляй точечно: цифры — только проверенные, ловушки — в конец §7, значений секретов не писать.

## 1. Что это
## 2. Стек
## 3. Цифры
## 4. Структура файлов
## 5. Токены / конвенции
## 6. Реализованные фичи
## 7. Что НЕ сделано + ловушки
## 8. Команды
## 9. Стиль общения
## 10. Что делать на старте новой сессии

---
**Последнее обновление:** <дата> · итерация <N> · <суть>

## История итераций
- **Iter 1:** что сделано, метрики

Размер — 300-500 строк. Меньше — не хватит, больше — тащишь шум. Перевалил за 500 — сожми старые строки истории, ловушки не трогай.

Что писать в секциях

1. Что это — 1-2 предложения: кто юзер, что строим, главная ценность. Для новичка, не для тебя.
2. Стек — точные версии и breaking changes против общего знания («это не тот Next.js, что в твоих данных»).
3. Цифры — таблица «сколько чего сейчас»: страницы, записи, юзеры. Якорь масштаба, который новая сессия сверит с реальностью.
4. Структура файлов — только важное и зачем каждая папка. Не ls -R.
5. Токены / конвенции — цвета, шрифты, размеры, правила, которые нарушать НЕЛЬЗЯ.
6. Реализованные фичи — ✓ список, метрики до/после, ссылки на прод.
7. Что НЕ сделано + ловушки — open items с почему (что блокирует), закрытые — зачёркнуты. Ловушки — нумерованный список «симптом → причина → как не повторить», например: «smoke зелёный, а сайт лежит → health-URL отдаёт nginx, а не приложение → проверять реальные страницы». Это самое ценное в HANDOFF.
8. Команды — готовые к копированию: dev, build, type-check, деплой, откат. Smoke, которому можно верить: для сервиса — 2-3 реальные страницы + API со сверкой числа из §3 + статус процесса (pm2 describe <имя>, systemctl status, docker ps); для библиотеки или CLI — тесты и сборка. Один health-URL не годится: прокси отдаёт его и при мёртвом приложении.
9. Стиль общения — язык и tone; что юзер любит и не любит; какие skills использует; красные линии — что не трогать без согласия. Обязательная строка: «Субагентов — Agent/Task, параллельных агентов, воркфлоу и skills, которые их запускают, — не запускать без явной просьбы юзера. По умолчанию работать самому». Юзер в этом чате разрешил иначе — запиши его формулировку дословно.
10. Старт новой сессии — прочитать HANDOFF целиком; git status + git log --oneline -5 (изменения после даты HANDOFF назвать первыми); smoke по §8 и сверка цифр из §3; отчёт «расхождения → что понял → готов делать X»; не переделывать то, что помечено «не трогать без согласия».

Стартовая фраза — только если нужен новый чат

Дай её заполненной, без плейсхолдеров:

Продолжаю проект «<имя>» в новом чате.

Локально: <путь>
Прод: <URL>
Контекст: HANDOFF.md (обновлён <дата>, итерация <N>)

1. Прочитай HANDOFF.md целиком.
2. git status и git log: изменения после даты HANDOFF назови первыми.
3. Smoke по HANDOFF §8: реальные страницы, API, статус процесса.
4. Коротко (≤ 200 слов): расхождения HANDOFF с реальностью, потом что заметил.
5. Предложи план следующей итерации.

Стиль — HANDOFF §9. Субагентов без моей просьбы не запускай, работай сам.

Ответ юзеру

• Что изменилось в HANDOFF — 2-4 пункта; расхождения с реальностью, если были. Ничего не менял — так и скажи: «HANDOFF актуален».
• Smoke — итог одной строкой.
• Указатель и хук — одной строкой: добавлены или уже были. Хук поставил впервые — предложи проверку: /compact, и первым действием модель должна прочитать HANDOFF.
• Вердикт: «продолжаем здесь» или «нужен новый чат, потому что <сигнал>» + стартовая фраза.

Anti-patterns

• ❌ Переезжать только потому, что контекст заполнен. Автокомпакт продолжит сессию.
• ❌ Откладывать до последнего. После сжатия детали уже потеряны — сохранять надо раньше, в конце итерации.
• ❌ Переписывать существующий HANDOFF с нуля. Пропадут ловушки и договорённости прошлых сессий.
• ❌ Перезаписывать settings.json целиком. Пропадут чужие хуки и настройки — только дописать элемент в массив.
• ❌ Дамп чата или копия кода. HANDOFF — дистиллят: решения, причины, контекст, то, чего нет в коде. Не транскрипт и не полные тексты файлов.
• ❌ Секреты в тексте. Путь к .env — можно, значения ключей и паролей — никогда: HANDOFF коммитится и попадает в чаты.
• ❌ Health-URL как единственный smoke.
• ❌ «Возможно», «кажется». Только проверенные факты.
• ❌ Скрывать факапы. Что не сработало — это ловушки §7, самое ценное для следующей сессии.