Контекст, память и инструкции агента

- Claude.md создается как ли ручками или ИИ генериться?

Файл CLAUDE.md (или WARP.md, AI.md в зависимости от инструмента) — это файл с мета-инструкциями для AI-агента, и сегодня в его создание представляет собой гибридный процесс, сочетающий ручную экспертизу и помощь со стороны ИИ.

Детальный разбор механики:

По своей сути, CLAUDE.md — это форма конституционного AI на уровне проекта. Его основная цель — направить поведение агента в рамках конкретной кодовой базы, задать правила игры, описать архитектуру и указать на лучшие практики.

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

Технологии и лучшие практики:

Начальная генерация с помощью ИИ: Самый эффективный подход — это bootstrap-процесс. Вы даете агенту задачу высокого уровня: Проанализируй этот проект (структуру, зависимости, конвенции) и сгенерируй черновик файла WARP.md для будущих AI-агентов. Модель просканирует код, package.json, Dockerfile, и создаст базовую версию документа.
Ручная доработка и ревью: Полученный черновик обязательно проходит ревью у Senior-разработчика. На этом этапе вносятся стратегические указания, удаляются неточности и добавляются правила, которые агент не мог вывести сам (например, Не использовать библиотеку X, потому что у нее проблемы с лицензией).
Версионирование: Файл WARP.md должен находиться в системе контроля версий (Git) вместе с кодом. Это позволяет отслеживать изменения в инструкциях и связывать их с изменениями в кодовой базе.
Иерархия инструкций: В больших проектах используется иерархический подход:
- Корневой WARP.md с общими правилами.
- Вложенные WARP.md в поддиректориях (src/api/WARP.md) с более специфичными инструкциями, которые переопределяют или дополняют глобальные.

Что может пойти не так:

Конфликтующие инструкции: Агент может получить противоречащие правила из разных источников. Важно, чтобы инструмент, который вы используете (например, Warp), имел четкий алгоритм приоритетов (например, инструкция из более глубокой директории важнее).
Избыточность и зашумление контекста: Слишком длинный и подробный файл инструкций может съесть значительную часть контекстного окна модели и снизить ее фокус. Инструкции должны быть емкими и по делу.

Полезные материалы:

- A как вы храните память? разбивка задач сделана и задачи взаимосвязаны. Задача 1 выполняется, ж результате много кода написано с тестами. Задача 2 после нее должна выполниться, но не в текущем контекстном окне. Как передать инфу? Если не создавать память, клод снова просканирует файлы, и потратится куча токенов

Это фундаментальная проблема для stateful AI-агентов, и она решается с помощью многоуровневой архитектуры памяти, которая эмулирует человеческую память. Голый скан файлов — крайне неэффективный и устаревший подход.

Детальный разбор архитектуры памяти:

Память агента делится на три ключевых компонента, каждый со своим назначением и технологическим стеком.

Рабочая память (Working Memory):
- Что это: Аналог человеческой RAM. Это краткосрочная память, которая хранится непосредственно в контекстном окне LLM (у моделей 2026 года это 200K-2M токенов).
- Механизм: Здесь находится информация о текущей задаче, последние сообщения, код, который был написан только что. Когда задача (например, Задача 1 из вашего вопроса) завершается, агент создает краткую сводку (summary) о проделанной работе: Реализовал фичу X в файлах A и B, добавил тесты C. Ключевой интерфейс — FunctionName.
- Передача контекста: Эта сводка вместе с ID коммита или дифф-патчем становится ключом для передачи контекста к Задаче 2. Она помещается в контекстное окно для следующей задачи, что гораздо эффективнее повторного сканирования.
Эпизодическая память (Episodic Memory / Long-Term Memory):
- Что это: Долгосрочное хранилище, реализованное на основе векторной базы данных (Vector DB).
- Механизм: Все важные артефакты (сводки по задачам, диалоги, принятые архитектурные решения, результаты тестов) сохраняются в Vector DB в виде чанков (кусков текста) и их эмбеддингов (векторных представлений). Когда агент приступает к новой задаче, он формирует запрос к этой базе, чтобы найти релевантные воспоминания из прошлого.
- Пример: Перед Задачей 2, агент может сделать запрос: Что я знаю о фиче X?. Векторная база вернет сводку по Задаче 1 и другие связанные документы.
Структурная память (Structural Memory / Knowledge Graph):
- Что это: Наиболее продвинутый уровень, где информация хранится в виде графа знаний (Knowledge Graph).
- Механизм: Агент не просто хранит текст, а извлекает из него сущности (файлы, функции, разработчики) и отношения между ними (функция A использует функцию B, файл C зависит от D). Это позволяет выполнять сложные, структурные запросы.

Технологии и лучшие практики:

Фреймворки для памяти: Mem0 — state-of-the-art решение, которое абстрагирует работу со всеми уровнями памяти. Агент просто говорит запомни это или вспомни все о X, а фреймворк сам решает, куда и как сохранить/извлечь информацию.
Оркестрация: Для построения сложных, stateful агентов, которые могут переключаться между задачами, используется LangGraph. Он позволяет проектировать потоки работы агента в виде графа состояний.
Векторные БД: Pinecone, Weaviate, Milvus — отраслевой стандарт.
Ранжирование (Reranking): После получения кандидатов из векторной базы, применяется модель-реранкер (например, Cohere Rerank или кастомные SLM), чтобы отобрать самые релевантные воспоминания для текущего запроса.

Что может пойти не так:

Засорение контекста: Неправильно настроенный поиск по памяти может подтянуть нерелевантную информацию, что приведет к галлюцинациям.
Потеря специфики: Слишком агрессивная суммаризация может привести к потере важных деталей. Нужен баланс.
Высокая задержка (Latency): Обращения к внешним системам памяти замедляют работу. Решается продвинутым кэшированием и использованием быстрых in-memory баз данных для рабочей памяти.

Полезные материалы:

- Лучший способ ставить ограничения чего можно/нельзя агенту? CLAUDE.md, settings, claudeignore или что-то еще?

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

Детальный разбор уровней ограничений:

CLAUDE.md / WARP.md (Уровень инструкций):
- Назначение: Определяет высокоуровневые правила поведения и стратегические границы. Это конституция агента.
- Примеры:
  - Никогда не вноси изменения в файлы в директории /src/billing без явного подтверждения.
  - Всегда используй наш внутренний HttpClient вместо прямых fetch запросов.
  - Не предлагай использовать библиотеки с лицензией GPL.
- Сила: Это мягкое ограничение. Модель может его проигнорировать, особенно если основная задача вступает в конфликт с правилом.
claudeignore / warpignore (Уровень доступа к файлам):
- Назначение: Это жесткое ограничение на уровне файловой системы. Аналог .gitignore.
- Механизм: Инструмент (например, Warp) физически не позволяет агенту читать или изменять файлы и директории, указанные в этом файле.
- Примеры: secrets.yml, node_modules/, .env, *.pem.
- Сила: Абсолютное, самое надежное ограничение для защиты чувствительных данных и избежания замусоривания контекста.
Настройки агента в платформе (Settings):
- Назначение: Контроль над операционными возможностями агента на уровне платформы.
- Примеры:
  - Tool Access Control: Разрешить агенту использовать только определенные инструменты (например, read_file, grep), но запретить run_shell_command.
  - Network Access: Ограничить доступ к сети, разрешив обращения только к определенным доменам (например, корпоративный GitHub, npm).
  - Resource Limits: Установить лимиты на время выполнения, количество токенов, затраты.
- Сила: Жесткое ограничение, контролируемое исполняющей средой агента.

Технологии и лучшие практики:

Комбинированный подход: Всегда используйте все три уровня. Начинайте с самого жесткого (.ignore и Settings), а затем уточняйте поведение через WARP.md.
Guardrails: В коде самого агента (если вы разрабатываете его на LangChain/LangGraph) внедряются программные ограждения (Guardrails). Например, перед выполнением shell-команды, другая LLM (часто более простая и быстрая, как Llama 3.1 8B) проверяет ее на безопасность (например, rm -rf /).
Least Privilege Principle: Давайте агенту минимально необходимые права для выполнения задачи. Если ему не нужно выполнять команды в терминале — отключите этот инструмент.

Что может пойти не так:

Чрезмерные ограничения: Слишком строгие правила могут помешать агенту выполнить задачу. Например, запрет на редактирование package.json не позволит ему добавить новую зависимость.
Неявные нарушения: Агент может обойти мягкие ограничения из WARP.md, если сочтет это необходимым для решения основной проблемы. Поэтому критически важные ограничения должны быть жесткими.

Полезные материалы:

- Как поддерживать общий контекст больших систем с множеством зависимостей, логикой, зависящей, от фичей, вне скоупе текущей разрабатываемой фичи?

Поддержание контекста в больших системах — это ключевая задача для AI-агентов, решаемая через комбинацию автоматического анализа кода и продвинутых RAG-систем (Retrieval-Augmented Generation).

Детальный разбор механики:

Основная идея — не пытаться запихнуть всю систему в контекстное окно. Вместо этого агент должен уметь динамически подгружать только ту информацию, которая релевантна для текущей задачи, даже если она находится за пределами его прямого фокуса.

Индексация кодовой базы:
- На первом этапе вся кодовая база и документация проходят через процесс индексации. Код парсится для построения Abstract Syntax Tree (AST), из которого извлекаются символы: функции, классы, переменные.
- Каждый символ (чанк) снабжается метаданными: путь к файлу, номер строки, зависимости (что он вызывает и кем он вызывается).
- Эти чанки и их описания векторизуются и загружаются в векторную базу данных.
Динамический RAG (Retrieval-Augmented Generation):
- Когда агент работает над фичей (например, в файле A), он сталкивается с вызовом функции foo() из файла B.
- Агент автоматически формирует запрос к RAG-системе: Дай мне определение и контекст использования функции foo().
- RAG-система находит в векторной базе определение функции foo, примеры ее вызова, а также связанные сущности (например, тесты для этой функции). Эта информация динамически добавляется в рабочую память агента (контекстное окно).
GraphRAG и анализ зависимостей:
- Более продвинутый подход 2026 года — GraphRAG. Вместо простого векторного поиска используется граф кода. Узлы — это файлы и функции, ребра — их связи (импорты, вызовы).
- Это позволяет агенту задавать сложные вопросы: Какие части системы затронет изменение функции foo()?, Найди все места, где используется этот API-endpoint. Система навигируется по графу и возвращает полный контекст.

Технологии и лучшие практики:

Инструменты для индексации: Sourcegraph Cody, Continue.dev — это IDE-плагины, которые индексируют кодовую базу в фоновом режиме, создавая эмбеддинги и графы для локального RAG.
GraphRAG: Проекты от Microsoft Research и Neo4j позволяют строить и запрашивать графы знаний поверх кода.
Мультимодальные эмбеддинги: Для сложных систем с диаграммами (например, в Confluence) используются мультимодальные модели, которые могут векторизовать не только текст, но и изображения, создавая единое смысловое пространство.
Иерархический RAG: Информация извлекается на разных уровнях. Сначала агент получает краткую сводку о модуле, и если этого недостаточно — запрашивает конкретные фрагменты кода.

Что может пойти не так:

Неточный поиск (Retrieval): Если поиск возвращает нерелевантную информацию, агент может быть сбит с толку. Это решается использованием гибридного поиска (ключевые слова + семантика) и реранкингом.
Устаревшая индексация: Индекс должен постоянно обновляться по мере изменения кода. Современные инструменты делают это инкрементально и автоматически.

Полезные материалы:

- Какие на сегодняшний день наиболее популярные и перспективные подходы в формировании контекста к вопросу к LLM?

Формирование контекста для LLM (промпт-инжиниринг) эволюционировало от ручного написания промптов к программируемым и оптимизируемым конвейерам (pipelines). Ключевой тренд — рассматривать промпт не как статическую строку, а как динамически собираемую программу.

Наиболее популярные и перспективные подходы:

RAG (Retrieval-Augmented Generation) — Базовый стандарт:
- Механика: Перед тем как задать вопрос LLM, система сначала ищет релевантную информацию во внешней базе знаний (обычно векторной). Найденные документы вставляются в промпт в качестве контекста.
- Перспектива: RAG становится все более сложным: гибридный поиск, реранкинг, GraphRAG. Это уже не просто найди и вставь, а многоступенчатый процесс фильтрации и ранжирования информации.
DSPy (Demonstrate-Search-Predict Programming):
- Механика: Это фреймворк, который меняет парадигму. Вы больше не пишете промпты, вы пишете сигнатуры — описываете, что хотите получить на выходе (input -> output). DSPy сам генерирует и оптимизирует промпты для конкретной LLM, подбирая лучшие примеры (few-shot), инструкции и даже цепочки вызовов (chain-of-thought).
- Перспектива: Это главный тренд — переход от промпт-инжиниринга к промпт-программированию. DSPy позволяет создавать более надежные и переносимые между разными моделями системы.
Агентные архитектуры (ReAct, Plan-and-Solve):
- Механика: Контекст формируется итеративно. Агент сначала думает (Thought), затем действует (Action), используя инструменты (например, поиск в интернете, запрос к API), получает результат (Observation), и этот результат добавляет в свой контекст для следующего шага.
- Перспектива: Системы вроде LangGraph и AutoGen позволяют строить мультиагентные системы, где агенты общаются друг с другом, формируя общий контекст для решения сложной задачи. Один агент-планировщик декомпозирует задачу, другие — исполняют.
Контекстное сжатие (Context Compression):
- Механика: Даже с огромными контекстными окнами (2M токенов), засорение промпта нерелевантной информацией снижает качество ответа. Перед подачей в LLM, извлеченный из RAG-системы контекст проходит через специальную малую модель (SLM), которая удаляет из него все лишнее, оставляя только суть.
- Перспектива: Это становится стандартным шагом в любом продвинутом RAG-пайплайне для повышения соотношения сигнал/шум.

Технологии и фреймворки:

Для RAG: LlamaIndex, LangChain.
Для программирования промптов: DSPy.
Для агентов: LangGraph, AutoGen, CrewAI.
Для сжатия: Фреймворки вроде LLMLingua.

Что может пойти не так:

Сложность пайплайна: Современные системы формирования контекста — это сложные, многоступенчатые конвейеры. Ошибка на любом из этапов (плохой retrieval, неверный реранкинг) каскадом влияет на конечный результат.
Затраты и задержка: Каждый дополнительный шаг (реранкинг, сжатие, вызов агента) увеличивает стоимость и время ответа.

Полезные материалы:

- Контекстное окно заканчивается - агент забывает. Восстановление контекста после перерыва в работе (не смотря на доки и memory). Постоянная потеря контекста агентом, как с этим бороться?

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

Детальный разбор механики забывания:

LLM по своей природе не имеют памяти между запросами. Весь контекст, который у них есть — это текст, переданный в одном запросе (промпте). Когда контекстное окно (например, 200К токенов) заполняется, старая информация должна быть отброшена, чтобы освободить место для новой. Это и есть забывание.

Продвинутые AI-агенты решают эту проблему, имитируя человеческую память.

Рабочая память (внутри контекстного окна):
- Проблема: Окно переполняется.
- Решение: Вместо наивного хранения всей истории диалога, агент применяет стратегии суммаризации. По мере роста диалога, специальная LLM-функция (или даже сама основная модель) создает краткое содержание (summary) предыдущих сообщений. Например, 20 сообщений сжимаются в один параграф: Мы обсудили баг в модуле авторизации, рассмотрели два варианта фикса и остановились на варианте Б, который требует изменения файла auth.service.ts. Это summary заменяет оригинальные сообщения в контекстном окне.
Долгосрочная память (вне контекстного окна):
- Проблема: Агент забывает то, что было в прошлых сессиях работы или давно в текущей.
- Решение: Использование внешнего хранилища, как было описано выше (вопрос про хранение памяти). Ключевые выводы, решения, фрагменты кода и сводки диалогов не просто отбрасываются, а сохраняются в векторную базу данных (эпизодическая память) или граф знаний (структурная память).
- Восстановление контекста: Когда вы возвращаетесь к работе после перерыва, агент не начинает с нуля. Он делает запрос к своей долгосрочной памяти: Каков статус задачи X?, Какие последние файлы я редактировал?. RAG-система извлекает релевантные воспоминания, которые формируют начальный контекст для новой сессии.

Технологии и лучшие практики:

Фреймворк для памяти: Mem0 является стандартом для управления жизненным циклом памяти. Он автоматически обрабатывает суммаризацию, сохранение в Vector DB и извлечение.
Управление состоянием: LangGraph позволяет проектировать агентов как конечные автоматы (state machines). Состояние агента (его текущие цели, воспоминания) явно сохраняется и загружается между шагами, что делает процесс работы предсказуемым и устойчивым к прерываниям.
Attention-менеджмент: Новые архитектуры моделей (не только Transformer) экспериментируют с механизмами, позволяющими закреплять (pin) определенные части контекста, давая им больший вес внимания и предотвращая их вытеснение.
Автоматическая суммаризация: Вместо ручного вызова summary, агенты используют токены-триггеры. Когда контекст заполнен на 80%, автоматически запускается фоновый процесс сжатия истории.

Что может пойти не так:

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

Полезные материалы:

- Контекст проекта, постепенная потеря понимания разработчиком, что вообще происходит под капотом

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

Детальный разбор проблемы и AI-решений:

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

AI как Хранитель знаний (Knowledge Keeper):
- Решение: Весь проект, включая код, документацию, таски в Jira, переписку в Slack и даже записи митингов, непрерывно индексируется и подается в единую систему RAG.
- Пример: Разработчик, приступая к задаче, может задать системе вопрос на естественном языке: Почему мы используем RabbitMQ, а не Kafka, для сервиса уведомлений? Покажи мне архитектурное решение и последние обсуждения этой темы. Система найдет релевантные документы из Confluence, код и сообщения из Slack и предоставит исчерпывающую сводку.
Автоматическая генерация и обновление документации:
- Решение: Агенты, интегрированные в CI/CD пайплайн, автоматически обновляют документацию при каждом изменении кода.
- Механизм: Когда разработчик мержит pull request с изменениями в API, агент анализирует дифф, понимает суть изменений и самостоятельно обновляет соответствующую страницу в Confluence или генерирует новый Markdown-файл, описывающий изменения. Это гарантирует, что документация никогда не устаревает.
Визуализация и исследование кода:
- Решение: Вместо того чтобы читать сотни файлов, разработчик просит агента визуализировать зависимости.
- Пример: Построй граф вызовов для функции calculate_billing_total. Какие сервисы она затрагивает? Агент генерирует интерактивную диаграмму, показывающую все связи, что мгновенно восстанавливает контекст.

Технологии и лучшие практики:

Корпоративные RAG-системы: Такие платформы, как Glean, или self-hosted решения на базе LlamaIndex позволяют создавать единую точку входа для поиска по всем знаниям компании. Они имеют коннекторы к десяткам систем (GitHub, Slack, Jira, Google Drive).
Агенты в CI/CD: Интеграция агентов на базе LangGraph или AutoGen с GitHub Actions/GitLab CI. Агент срабатывает на событие (например, pull_request_merged) и выполняет заранее определенные задачи по документированию.
Инструменты для анализа кода: Sourcegraph Cody и Continue.dev не только помогают писать код, но и являются мощными инструментами для его исследования, позволяя чатиться с кодовой базой.

Что может пойти не так:

Мусор на входе — мусор на выходе (GIGO): Если в базе знаний много устаревшей или противоречивой информации, RAG-система будет давать неверные ответы. Необходима регулярная гигиена данных.
Проблемы с доступом: RAG-система должна строго соблюдать права доступа, чтобы не показывать разработчику информацию, которую ему видеть не положено.

Полезные материалы:

- Как построить оптимальный мемори банк? Забывает правила из препромптов даже на пустом контексте. Я обычно использую бесплатные чат-боты для получения информации или разработке mvp, но мне не нравится, как эти чат-боты работают с контекстом (часть теряется, иногда бот изменяет свое решение и не объясняет/замечает это).

Эти вопросы, хотя и разные по формулировке, указывают на общие проблемы современных LLM: надежность, управляемость и работа с состоянием. Оптимальный мемори банк (система памяти) — это ключ к их решению.

Архитектура оптимальной системы памяти (Memory Bank):

Как упоминалось ранее, это гибридная, многоуровневая система. Давайте рассмотрим ее компоненты подробнее.

Сенсорная память (Sensory Input):
- Что это: Необработанный поток данных — диалог с пользователем, содержимое файлов, вывод инструментов.
- Оптимизация: На этом уровне происходит фильтрация и обогащение. Например, из лога с ошибкой извлекается только сам стектрейс, а мусор вокруг отбрасывается.
Рабочая память (Working Memory / Short-Term):
- Что это: Активный контекст в LLM.
- Оптимизация:
  - Суммаризация: Для сжатия истории.
  - Приоритезация: Не все части контекста равны. Правила из препромпта (гайдлайны) должны иметь больший вес. Современные модели позволяют использовать специальные теги или маски внимания (attention masks), чтобы указать LLM, на какие части промпта обращать особое внимание. Это решает проблему забывания правил.
  - Структурирование: Контекст подается не сплошным текстом, а в структурированном виде (например, XML или JSON), где четко разделены инструкции, история, данные из RAG и т.д.
Долгосрочная память (Long-Term Memory):
- Что это: Внешнее хранилище (Vector DB, Graph DB).
- Оптимизация:
  - Правильный чанкинг (Chunking): Текст нужно делить на осмысленные куски. Для кода — это чанкинг по функциям/классам, а не по количеству строк.
  - Метаданные: Каждый чанк должен иметь богатые метаданные (дата, источник, автор, связанные сущности), что позволяет делать более точные запросы при извлечении.
  - Реранкинг: Обязательный шаг для отбора наиболее релевантных воспоминаний.

Почему бесплатные чат-боты работают с контекстом хуже?

Бесплатные версии чат-ботов (например, ChatGPT) обычно используют самую простую, наивную форму памяти: скользящее окно по истории диалога. У них нет доступа к внешним базам данных для долгосрочной памяти, нет RAG, нет реранкинга и нет продвинутых техник суммаризации. Они state-less. Продвинутые агенты, напротив, являются stateful-системами, где память — это центральный компонент архитектуры.

Почему агент меняет решение и не замечает этого?

Это связано с отсутствием саморефлексии (self-reflection). Продвинутые агентные архитектуры решают это так:

Паттерн Plan-and-Solve: Агент сначала составляет план действий. После каждого шага он сравнивает результат с планом и своим предыдущим состоянием.
Агент-критик (Critic Agent): В мультиагентных системах (AutoGen, CrewAI) один агент выполняет работу, а второй (критик) проверяет ее на соответствие начальным требованиям и гайдлайнам. Если критик находит несоответствие, он возвращает задачу на доработку с указанием на ошибку.

Технологии и фреймворки:

Системы памяти: Mem0
Агентные фреймворки с рефлексией: LangGraph, AutoGen, CrewAI
Для RAG и чанкинга: LlamaIndex

Полезные материалы: