Ваш ИИ-агент не тупой. Просто у него нет каркаса

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

Речь о каталоге .claude, который лежит в корне любого рабочего проекта с ИИ-агентом. Внутри обычно семь элементов: файл контекста проекта, settings.json с правами доступа, хуки, поддагенты, навыки, описание MCP-серверов и файл памяти. Большинство разработчиков открывали от силы один-два из них. Отсюда и стопор на третьей итерации: агент просто не знает, что ему разрешено, кто проверяет его работу и что уже было сделано раньше.

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

Первым при каждом запуске читается файл контекста проекта (в Claude Code он называется CLAUDE.md), и его содержимое становится постоянным фоном для всей сессии. Туда стоит вписывать структуру каталогов, стек технологий, рабочие команды и явный список того, чего агенту делать нельзя. Раздувать этот файл опасно: препринт Less Context, Better Agents показывает, что перегруженный постоянный контекст снижает долю успешно выполненных задач с 91,6% до 71%. Рабочее правило простое: держать файл в пределах 300 строк и регулярно вычищать из него всё, что перестало быть актуальным.

settings.json определяет, какие команды и обращения к MCP агенту разрешено выполнять без лишних вопросов, а какие запрещены полностью. Разумный минимум: разрешить безопасные команды чтения вроде git status или cat и явно запретить необратимые операции вроде принудительного пуша или рекурсивного удаления файлов. Тогда агент перестаёт дёргать человека разрешением на каждый шаг, а по-настоящему опасные действия всё равно остаются заблокированы.

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

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

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

MCP-серверы описываются в .mcp.json и дают циклу доступ к внешним инструментам вроде GitHub или поиска по документации. Правило простое: подключать только то, что реально используется в текущей работе, для всего, что требует токенов доступа, отдавать предпочтение официальным серверам и не тащить пять серверов на всякий случай, особенно если у кого-то из них есть право на запись без логирования вызовов.

Седьмой элемент, память и состояние. Обычно это индексный файл вроде MEMORY.md плюс отдельная папка с более стабильным описанием проекта: архитектурой, спецификацией API, разбором прошлых инцидентов. Память хранит то, что меняется от сессии к сессии, отдельное хранилище, то, что остаётся неизменным. У памяти есть свой каприз: если она только пополняется и никогда не чистится, она сама превращается в источник деградации контекста, о которой инженерная команда Anthropic пишет отдельно.

Поверх каркаса работает исполнительный цикл из пяти элементов. Техническое задание, файл на диске, а не в голове модели, который агент перечитывает на каждой итерации вместе с условиями «готово» и условиями, при которых нужно остановиться. Связка план-действие-проверка, где отдельный шаг проверки решает, можно ли двигаться к следующей итерации, вместо того чтобы полагаться на слово самого агента. Разветвление на поддагентов, когда одна задача превращается в десяток независимых подзадач и один перегруженный контекст физически не тянет такой объём, а десять маленьких тянут. Планировщик и сохранение состояния: cron, launchd или systemd запускают цикл, пока человек занят другими делами, а каждая итерация обязана записывать на диск, что сделано и что дальше, иначе агент проснётся и забудет, зачем вообще просыпался.

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

Собрать все семь файлов каркаса и наладить цикл поверх них реально за один вечер, а дальше система работает сама. Начать стоит с простой проверки: открыть .claude в своём проекте и посчитать, сколько из семи элементов там реально есть.

Источники и материалы: препринт Less Context, Better Agents (arxiv.org/abs/2606.10209); документация Claude Code по настройкам (docs.anthropic.com/en/docs/claude-code/settings) и по хукам (docs.anthropic.com/en/docs/claude-code/hooks); материалы инженерной команды Anthropic о работе с контекстом (anthropic.com/engineering/effective-context-engineering-for-ai-agents) и о мультиагентных системах (anthropic.com/engineering/built-multi-agent-research-system); репозитории github.com/centminmod/my-claude-code-setup, github.com/wshobson/agents, github.com/anthropics/skills, github.com/modelcontextprotocol/servers, github.com/anthropics/claude-agent-sdk-python, github.com/moonrunnerkc/swarm-orchestrator. Источник идеи: https://t.me/ai_machinelearning_big_data/10476