Инфраструктура контекста для AI-агентов

11 марта 2026

LLM-агенты не помнят ничего между сессиями. Каждый новый разговор начинается с чистого листа, и разработчик снова и снова объясняет одни и те же детали: архитектурные решения, соглашения об именовании, известные ловушки. По мере роста проекта агент теряет когерентность, и программист всё больше времени тратит на исправление рутинных ошибок вместо содержательной работы.

Проблема: агенты без памяти

Стандартный workflow с LLM-агентом выглядит так: новая сессия, разработчик объясняет контекст, агент делает работу, сессия заканчивается. Следующая сессия - и всё начинается с нуля. На небольших проектах это терпимо. При кодовой базе в несколько десятков тысяч строк это становится системным ограничением.

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

Корень проблемы прост: агент не накапливает знания о проекте. Каждая сессия - это агент с нулевым опытом работы в вашей кодовой базе. Решение - не ждать, пока агент «сам разберётся», а спроектировать инфраструктуру для передачи контекста.

Трёхуровневая архитектура контекста

Vasilopoulos описывает три уровня хранения знаний о проекте, которые соответствуют разным паттернам доступа и степени специфичности:

Уровень	Название	Размер	Загрузка	Назначение
Tier 1	Конституция	~660 строк	Всегда	Стандарты, архитектурные паттерны, команды сборки
Tier 2	Специализированные агенты	19 агентов, ~9 300 строк	По домену	Глубокие знания конкретных подсистем
Tier 3	База знаний	34 документа, ~16 250 строк	По запросу	Детальная документация каждой подсистемы

Суммарный объём контекстных документов - 26 200 строк при 108 256 строках кода. Это 24.2% от размера кодовой базы. Не побочный продукт разработки, а инвестиция, которую автор делал целенаправленно.

Tier 1: Конституция (горячая память)

Конституция - единый Markdown-файл на ~660 строк, который загружается в контекст каждой сессии без исключений. Это «горячая память» проекта: то, что агент должен знать всегда.

Что содержит конституция:

• Стандарты качества кода и соглашения об именовании
• Команды сборки и запуска тестов
• Архитектурные паттерны, принятые в проекте
• Чеклисты для типовых операций (PR, деплой, рефакторинг)
• Известные режимы отказа и способы их диагностики
• Таблицы оркестрации - маршрутизация задач к специализированным агентам

Таблицы оркестрации - ключевой элемент, который автор называет «trigger tables». Логика простая: если изменяется файл из домена X, задачу выполняет агент Y. Это автоматически решает проблему выбора агента и устраняет ситуацию, когда разработчик забывает передать управление нужному специалисту.

# Пример trigger table из конституции
| Изменяемые файлы           | Агент            | Причина                                |
|----------------------------|------------------|----------------------------------------|
| SaveSystem/*               | save-system      | Протокол сохранения, версионирование   |
| UI/Routing/*               | ui-sync-routing  | Правила синхронизации состояния        |
| Physics/RNG*               | deterministic-rng| Детерминированный RNG, seed-управление |
| Drop/*                     | drop-system      | Таблицы лута, формулы вероятностей     |

Tier 2: Специализированные агенты

19 специализированных агентов с суммарным объёмом ~9 300 строк. Каждый агент описан в отдельном файле объёмом от 115 до 1 233 строк. Ключевое наблюдение автора: более половины каждой спецификации - это знания о предметной области, а не инструкции по поведению.

Спецификация агента включает:

• Факты о кодовой базе, специфичные для домена
• Формулы и алгоритмы, применяемые в этом домене
• Конкретные паттерны кода с примерами
• Известные режимы отказа и диагностические признаки
• Только после этого - инструкции по поведению агента

Агенты создавались реактивно, а не проактивно. Автор создавал нового агента тогда, когда отлаживал один и тот же домен несколько расширенных сессий подряд - сигнал о том, что знания этого домена не помещаются в конституцию и требуют отдельного места.

Tier 3: База знаний (холодная память)

34 документа по ~16 250 строк суммарно. Каждый документ охватывает одну подсистему. Доступ через MCP-сервер с поиском по ключевым словам - агент запрашивает нужный документ, когда работает с конкретным модулем.

Документы базы знаний написаны для AI-потребления, а не для людей. Это меняет стиль написания: вместо нарративного описания - структурированные факты, явные пути к файлам, конкретные имена параметров, паттерны кода с аннотациями.

# Пример структуры документа базы знаний

## SaveSystem - Файл: SaveSystem/SaveManager.cs

### Ключевые файлы
- SaveSystem/SaveManager.cs - оркестрация сохранения
- SaveSystem/SaveSerializer.cs - сериализация, версия схемы v3
- SaveSystem/MigrationPipeline.cs - миграция между версиями схемы

### Паттерн сохранения
SaveManager.Save() → SerializeState() → CompressPayload() → WriteToFile()
Версия схемы инкрементируется при любом изменении структуры данных.
НЕЛЬЗЯ изменять структуру SaveData без создания миграции.

### Известные режимы отказа
- Если SaveData.Version != CURRENT_VERSION → запустить MigrationPipeline
- Коррупция файла при прерванной записи → fallback на .bak

Важная особенность: документы не конкурируют с комментариями в коде. Они фиксируют знания, которые не выводимы из кода - историю решений, контринтуитивные ограничения, паттерны, которые разбросаны по нескольким файлам.

Метрики проекта

Автор педантично фиксировал метрики на протяжении всего проекта. Результаты:

Метрика	Значение
Объём кода (C#)	108 256 строк
Время разработки	70 дней part-time
Сессий разработки	283
Промптов человека	2 801
Вызовов агентов	1 197
Контекстных документов	26 200 строк (24.2% от кода)
Ad-hoc сессий	~87%
Структурированных сессий (plan-execute-review)	~13%

Соотношение знания/код в 24.2% автор считает разумным overhead. Стоимость обслуживания - около 1–2 часов в неделю, преимущественно на обновление документов после изменений в коде.

Четыре кейса

Кейс 1: Save System - спецификация как координирующий документ

Save System разрабатывался на протяжении 74 сессий. Документ подсистемы выполнял роль единственного источника истины, к которому обращался агент в каждой сессии. Результат: ноль багов в системе сохранения за весь период разработки. Автор связывает это с тем, что агент каждый раз начинал с полным пониманием протокола, ограничений и паттернов.

Кейс 2: UI Sync Routing - фиксация опыта

Маршрутизация UI-синхронизации - домен с нетривиальными правилами, которые выяснялись методом проб и ошибок. Без документации агент в каждой новой сессии проходил один и тот же путь экспериментов, повторяя уже пройденные ошибки. После кодификации этих правил в документ агента итерации исчезли - агент начинал с правильного решения.

Кейс 3: Drop System - детектирование пробелов в знаниях

Интересный инвертированный кейс. Когда агент начинал систематически буксовать в домене Drop System, это был сигнал - не о плохой работе агента, а об отсутствующей документации. Отсутствие документа стало явным индикатором пробела в знаниях, который нужно заполнить.

Кейс 4: Deterministic RNG - отладка тонких багов

Детерминированный генератор случайных чисел требует глубоких знаний о seed-управлении, синхронизации состояния между клиентом и сервером, порядке операций. Агент с документом подсистемы мог участвовать в отладке тонких багов на уровне, который без контекста был бы недостижим.

Шесть практических принципов

Автор формулирует шесть принципов, выведенных из практики:

Принцип	Формулировка
G1	Базовая конституция даёт высокий эффект с первого дня. Не нужно ждать, пока проект вырастет.
G2	Планирование выявляет требования к контексту. Structured sessions (plan-execute-review) заставляют агента явно запрашивать нужные знания.
G3	Без автоматической маршрутизации разработчик постоянно напоминает агенту, какой контекст загрузить. Таблица оркестрации решает это раз и навсегда.
G4	Повторное объяснение одного и того же - сигнал о необходимости документации. Каждое такое объяснение - инвестиция в документ.
G5	Стратегическое создание агентов разрешает стопоры. Если работа в домене систематически буксует - создать специализированного агента.
G6	Устаревание документов незаметно вводит в заблуждение. Устаревшая спецификация хуже отсутствующей - агент уверенно действует по неверным правилам.

Обслуживание и риски

Основная стоимость инфраструктуры - не создание, а поддержание актуальности. 1–2 часа в неделю: обновление документов после рефакторинга, добавление новых паттернов, удаление устаревших ограничений.

Главный риск - устаревание спецификаций. Автор называет это «молчаливой ловушкой»: агент, работающий по устаревшей документации, делает ошибки с высокой уверенностью. Это хуже, чем агент без документации, - тот хотя бы видимо неуверен. Устаревший документ маскирует пробел под знание.

Структурное наблюдение из статьи: по мере роста проекта разделение труда между человеком-архитектором и агентом-реализатором сохраняется только при наличии инфраструктуры контекста. Без неё агент деградирует в помощника, которого постоянно нужно направлять, а разработчик возвращается к роли реализатора.

«По мере роста сложности проекта агенты теряют когерентность, и разработчик всё больше втягивается в исправление рутинных ошибок реализации. Инфраструктура контекста сохраняет это разделение труда при масштабировании.»

Пример: Hublix — трёхуровневая инфраструктура на практике

Hublix — платформа процессных AI-агентов для Telegram и MAX (VK). Python-монорепо с четырьмя микросервисами, двумя React-приложениями и Terraform-инфраструктурой. Проект с первого дня строился с трёхуровневой инфраструктурой контекста по принципам из статьи Vasilopoulos, и это позволяет наблюдать, как теоретическая модель работает в реальной кодовой базе.

Tier 1: Конституция — CLAUDE.md

Конституция Hublix (~210 строк) явно ссылается на принципы из статьи. Первые строки файла декларируют трёхуровневую структуру:

# Hublix — Constitution

> Tier 1: Hot memory. Always loaded. Concise conventions, trigger tables, failure modes.
> Tier 2: Specialist agents in `.claude/agents/` — domain knowledge embedded.
> Tier 3: Cold-memory specs in `.claude/specs/` — retrieved on demand.

Таблица оркестрации (trigger table) маршрутизирует к девяти специалистам. Каждая строка связывает паттерн изменяемых файлов с конкретным агентом:

| Trigger Signal (files modified)                            | Agent                      |
|------------------------------------------------------------|----------------------------|
| services/orchestration/processors/, tasks/, stores.py      | orchestration-specialist   |
| libs/shared/types/agent.py, StateDefinition                | state-engine-specialist    |
| services/identity/, JWT, WebAuthn, auth flows              | identity-specialist        |
| apps/admin/src/, React components                          | frontend-specialist        |
| infra/, Dockerfile, docker-compose*, .github/workflows/    | infra-specialist           |
| docs/adr/, new service/module, multi-package changes       | Check specs/adr-process.md |
| Any code for review                                        | code-reviewer              |
| After PR creation                                          | pr-reviewer                |

Конституция также включает таблицу известных режимов отказа (13 записей) — от «State machine stuck, no transition» до «Deploy hangs on SSH». Каждая запись содержит симптом, корневую причину, способ исправления и ссылку на соответствующую спецификацию из Tier 3.

Tier 2: Специализированные агенты

Девять агентов в .claude/agents/, каждый в формате YAML-frontmatter + Markdown. Агенты различаются по модели: opus для доменов, требующих глубокого рассуждения (orchestration, state engine, architect), sonnet для задач с меньшей неопределённостью (frontend, infra, code review).

Агент	Модель	Домен	Источник знаний
orchestration-specialist	opus	Message pipeline, DI-протоколы	Embedded + specs/orchestration-pipeline.md
state-engine-specialist	opus	FSM, transitions, guards	Embedded + specs/state-engine.md
identity-specialist	sonnet	Auth, JWT, WebAuthn, 152-ФЗ	Embedded + specs/auth-flows.md
architect	opus	Cross-service design	docs/architecture.md
pr-reviewer	sonnet	Autonomous post-PR review	All rules + all specs (worktree isolation)

Каждый агент содержит секцию embedded knowledge — доменные факты, которые загружаются вместе с агентом. Дополнительно агент ссылается на спецификации из Tier 3 для детальной информации. Это двухуровневая загрузка: базовые знания всегда доступны, глубокие — по запросу.

Tier 3: Спецификации — холодная память

Семь спецификаций в .claude/specs/ (~800 строк суммарно). Каждый документ охватывает одну подсистему:

Спецификация	Подсистема	Когда загружается
orchestration-pipeline.md	8-шаговый message processing	Изменения в services/orchestration/
state-engine.md	FSM, transitions, guards	Изменения в state definitions
tenant-isolation.md	Multi-tenancy, scoped repos	Изменения в DB schema
auth-flows.md	JWT, WebAuthn, magic links	Auth-related changes
adr-process.md	Architecture Decision Records	Планирование non-trivial features

Дополнительные слои: rules, skills, enforcement

Помимо трёх уровней контекста, Hublix добавляет механизмы принудительного исполнения, которых нет в оригинальной статье:

• Rules (.claude/rules/) — 7 файлов правил с YAML-frontmatter и полем paths:, которое привязывает правило к конкретным файлам. Покрытие тестами 100%, mypy strict, 152-ФЗ compliance — не рекомендации, а обязательные ограничения.
• Skills (.claude/skills/) — 14 исполняемых workflow: /test, /implement, /deploy, /pr, /security-audit. Каждый skill — пошаговый процесс с проверками качества.
• Session protocol — обязательная последовательность действий в конце каждой сессии: проверка качества, обновление трекера, push в remote.

Источники

• «Codified Context: Infrastructure for AI Agents in a Complex Codebase» — Aristidis Vasilopoulos, arXiv:2602.20478, февраль 2026.