Context hygiene

Context Hygiene

Контекст — рабочая память агента: конечная, вытесняемая и дорогая. В неё попадают системные инструкции, CLAUDE.md, диалог, прочитанные файлы и выводы команд; при переполнении история компактифицируется — детали и договорённости теряются молча. Управление тем, что в контексте живёт, а что вынесено наружу, — прямой рычаг качества работы агента.

Диагностика: сессия деградировала?

Признаки (2+ — пора действовать):

• агент переспрашивает то, что уже обсуждали, или «забыл» принятое решение;
• правки уходят не в те файлы / агент заново ищет то, что уже находил;
• агент ссылается на устаревшее состояние кода (файл уже изменён, а он помнит старый);
• ответы стали общими, план дрейфует от исходной цели;
• в сессии было 2+ компактификации подряд при активной работе.

Решение: продолжать или новая сессия

Правило по умолчанию: новая задача — новая сессия. Хвост предыдущей задачи в контексте — не помощь, а шум, который подмешивается в решения.

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

Перед уходом из длинной сессии — ритуал передачи: зафиксируй в файл (NOTES.md, PLAN.md, файл задачи) что сделано, что решено и почему, что осталось. Новая сессия начинается с чтения этого файла (или session-catchup восстановит по нему и git).

Разгрузка контекста внутри сессии

• Разведка — сабагентами. Поиск по кодовой базе, изучение «как устроен модуль X» — отдавай Explore/Task-агентам: в основной контекст возвращается вывод на абзац, а не двадцать прочитанных файлов.
• Читай адресно. Не запрашивай файл целиком ради одной функции; не выводи в контекст мегабайтные логи — фильтруй командой и смотри хвост/совпадения.
• Итоги фаз — в файлы. План, найденные факты, принятые решения — на диск, а не «в голове» диалога. Файл переживает компактификацию; договорённость в диалоге — нет.
• /compact — в осмысленных точках. Между фазами (закончили разведку → компакт → начали правки), а не посреди правки. Перед компактом убедись, что важное состояние уже в файлах.
• Большие правки — план сначала. Plan mode или явный план в файле: после компактификации агент сверяется с планом, а не с воспоминаниями.

Слои постоянного знания

Ключевой вопрос при «надо, чтобы агент это знал всегда»: какого рода это знание?

Знание	Куда	Пример
Правило поведения в проекте	CLAUDE.md	«Миграции не редактировать, только новые»; «тесты — make test»
Устройство системы	docs/ARCHITECTURE.md и др., ссылка из CLAUDE.md	Схема модулей, потоки данных, почему выбран X
Повторяемая процедура	Навык (skill)	«Как мы делаем релиз», «как проводим аудит»
Факт о пользователе/проекте вне кода	Память агента	«Прод — VPS без Docker», «предпочитает русский»
Состояние текущей работы	Файл задачи / PLAN.md	Что сделано, что осталось

Ошибка раскладки — главная причина «раздутого CLAUDE.md, который агент всё равно игнорирует».

Чек-лист CLAUDE.md

• Коротко: ориентир до ~100–150 строк; каждая строка стоит контекста в КАЖДОЙ сессии.
• Императив: «делай X», «не делай Y» — не эссе про историю проекта.
• Нет пересказа кода: структуру агент прочитает сам; фиксируй только неочевидное.
• Нет устаревшего: упомянутые файлы/команды существуют (протухшие правила подрывают доверие ко всем остальным).
• Тяжёлое — по ссылке: «архитектура — см. docs/ARCHITECTURE.md», не копипаста.
• Правила, рождённые из ошибок агента, добавляются сюда сразу (одной строкой «почему»), — это дешевле повторной ошибки.

Границы навыка

Систематический самоаудит агента (повторяющиеся ошибки, протухшая документация, guardrails) — agent-audit. Возобновление прерванной сессии — session-catchup. Постройка обвязки проекта (Makefile, CI, ARCHITECTURE.md с нуля) — harness-engineering. Декомпозиция задачи, чтобы куски влезали в один заход, — task-decomposer.