Этот документ описывает фундаментальные принципы управления контекстом LLM в проектах, использующих CodeMemory. Наша главная задача — бороться с Context Drift (потерей фокуса и забыванием специфики проекта при долгих рассуждениях), не превращая при этом промпты в неподъёмные пожиратели токенов.
LLM обладают огромным массивом базовых знаний (training weights). Когда диалог переходит в фазу архитектурных рассуждений (judgment) или решения сложных задач, модель склонна опираться на свои базовые знания о фреймворках, игнорируя локальные правила, инварианты и архитектурные решения конкретного проекта.
Симптом: Модель предлагает стандартное решение из учебника, которое ломает кастомную логику, описанную в документации, которую она читала 10 ходов назад.
Управление контекстом базируется на строгом физическом и семантическом разделении документации на два домена:
- Specs (
specs/) — "Что мы делаем и Как ориентироваться": Здесь живут бизнес-правила, форма данных, контракты API, функциональные карты и глобальные императивные правила (RULES.md). Это пространство стабильно и определяет границы системы. Модель читает Specs для ориентации. - Memory (
.memory/) — "Почему так и Как это реализовано": Здесь живут ADR (Architecture Decision Records), точечные инварианты, подводные камни, причины отказа от альтернатив. Это пространство динамично. Модель опрашивает Memory перед правкой конкретных узлов.
Правило водораздела (What vs How/Why): Спецификации описывают «Что это такое и что оно делает» (даже если это узкая или специфичная фича). Память описывает «Как это реализовано внутри кода и Почему приняты такие решения» (привязка к конкретным классам, алгоритмам, инвариантам и отброшенным альтернативам). Если знание отвечает на вопрос "как система должна вести себя" — это Specs. Если на вопрос "как мы написали код, чтобы это работало, и куда не надо наступать" — это Memory.
Мы не полагаемся на мягкие призывы ("пожалуйста, не забывай правила"). Мы используем структурные паттерны.
Вместо императивных чек-листов (case -> action), скиллы, требующие рассуждений (планирование, обсуждение архитектуры), используют структурированный ход мыслей.
Модель обязана следовать когнитивной траектории:
Назови допущения -> Опровергни/подтверди через поиск (Memory/Specs) -> Интегрируй найденное -> Сделай предложение.
Чтобы не раздувать контекст постоянными отчётами (## Memory Audit на каждый ход — это антипаттерн), репортинг о контексте применяется точечно, по триггерам смены контекста:
- Горизонтальный сдвиг (Ширина): Переход к новой бизнес-сущности, новому файлу или новой фиче, которая ранее в сессии не обсуждалась.
- Вертикальный сдвиг (Глубина): Переход от обсуждения бизнес-требований ("что") к технической реализации ("как" — выбор паттерна, структуры БД).
В этих точках модель обязана сделать паузу, опросить базу и явно зафиксировать (Grounding) найденные инварианты перед тем, как предлагать решения. На рутинных ходах исполнения этот блок опускается.
При использовании знаний из Memory, модель не должна просто цитировать их. Она обязана интегрировать их в свой нарратив:
Правильно: "Я планировал использовать X, но согласно [[id]] мы избегаем этого из-за Y, поэтому предлагаю Z."
Неправильно: "Вот что я нашёл: [[id]] говорит о Y. Давай делать Z."
Для удержания фокуса модели мы применяем концепцию «Режимов» (Modes) в качестве внутренних психологических рамок (mindsets) для скиллов. Мы сохраняем атомарность команд (The Linux Way), но внутри них задаём чёткую ролевую модель:
- Ask Mode (Анализ требований): Модель выявляет бизнес-цели, ограничения и скоуп. Запрет на предложение технических реализаций.
- Architect Mode (Проектирование): Обсуждение паттернов, инвариантов и структур данных. Запрет на кодогенерацию.
- Code Mode (Исполнение): Механическое написание кода и тестов. Запрет на изменение спецификаций и планов без явного разрешения.
Точка сдвига как Триггер: Скилл /grill охватывает как Ask, так и Architect режимы. Ключевая механика удержания контекста — это детектирование границы между ними. Когда диалог переходит от Ask Mode («что мы хотим сделать») к Architect Mode («какую систему очередей или паттерн мы для этого используем»), модель обязана сделать паузу и опросить Memory. Это ловит самый опасный момент дрейфа, когда у модели активируются базовые знания (training weights) о фреймворке.
Когда задача требует тяжёлого расследования или рендера (разведка этапа, прогон E2E, диагностика дефекта), эта работа оседает в контексте навсегда — тот же дрейф, но от объёма, а не от judgment. Механика: тяжёлый юнит работы спавнится субагентом и сгорает в его одноразовом контексте, а вызывающий получает только результат. Так /work делегирует разведку /prepare-субагенту, а /autopilot гоняет весь трек (/work//validate//diagnose) субагентами, сам оставаясь тонким — читает лишь индекс, отчёты и pointer-возвраты.
Это требует жёсткого контракта вместо мягкой просьбы (см. антипаттерны): оркестратор не «оценивает работу субагента» — он читает фиксированный вердикт (green/defect/blocked, located/inconclusive) из текста отчёта, подкреплённого неподделываемым артефактом (сырой вывод тестов, E2E-скриншоты с разделением «что видно» ↔ «соответствие expected»). Вердикт нельзя получить, не прогнав гейт — в этом его смысл.
Mode (Ask/Architect/Code/bespoke) задаёт, что скилл вправе производить. Interaction mode — независимая ось: может ли скилл блокироваться вопросом к человеку. attended — вправе остановиться и спросить; autonomous — никогда не блокируется, берёт лучший приемлемый дефолт и логирует, иначе завершается терминальным артефактом (вердикт, стоп, pointer-возврат). Ось следует каналу, а не флагу: inline-вызов = attended, спавн субагентом = всегда autonomous (возврат идёт родителю, человеку отвечать некому). Это и делает изоляцию субагентами (#5) безопасной — спавнутый скилл структурно не повиснет на вопросе.
Даже при идеальных триггерах диалог может зайти в тупик или уйти в галлюцинации. Для таких случаев вводится "аварийный костыль" — явный скилл /mem-explore.
- Суть: Это не часть стандартного workflow, а ручной тормоз.
- Действие: Заставляет модель остановить текущий поток мыслей, сделать широкий поиск по текущим сущностям в Memory и Specs, сопоставить свои последние предложения с найденными правилами и выдать отрезвляющий отчёт-сводку, корректирующий её дальнейший курс.
- "Пожиратели контекста" (Over-reporting): Требование от модели писать подробные отчёты о поиске или текущем состоянии на каждый ход.
- Мягкие просьбы вместо жестких структур: Фразы вида "Постарайся следовать правилам проекта" тонут в весах модели. Нужны жёсткие контракты (CoT).
- Смешивание "Что" и "Почему": Хранение деталей реализации конкретного метода в общих спецификациях. Это раздувает спеки и приводит к их игнорированию.
- Дублирование кода в документации: Переписывание интерфейсов, роутов или схем БД текстом. Спека должна ссылаться на код или объяснять логику, а не дублировать то, что модель может прочитать напрямую (
grep/read_file).