Claude Code without the magic: Habr breaks down the architecture, context noise, and engineering practices

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

Где теряется контекст

Главная идея статьи простая: Claude Code ломается не потому, что модель «недостаточно умная», а потому что инженерная среда вокруг неё плохо устроена. Автор описывает агент как цикл из сбора контекста, действия и проверки результата. Если в этом цикле перегружен хотя бы один слой, качество резко падает: длинный CLAUDE.

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

Формально у Claude Code большое окно, но значительная часть токенов тратится ещё до начала работы: на системные инструкции, дескрипторы skills, описания MCP-инструментов, LSP-состояние, память и проектный CLAUDE.md. Автор приводит показательный расчёт: один типичный MCP-сервер может занимать тысячи токенов только на схемы инструментов, а несколько подключённых серверов легко съедают заметную долю доступного окна.

Добавь сюда длинный вывод тестов, grep и логов — и полезная история диалога начинает вытесняться сама собой.

• Системные инструкции и базовые правила Описания skills и MCP-инструментов Память проекта и содержимое CLAUDE.md Результаты вызовов shell, тестов и поиска Сжатая, но уже не всегда точная история сессии Из этого вытекает практический вывод: редко используемые знания не должны жить в постоянно загруженном контексте. Для смены задачи лучше чаще использовать очистку сессии, для продолжения одного направления — управляемое сжатие. Ещё один совет из статьи — просить агента перед новой сессией собирать HANDOFF.md с прогрессом, тупиками и статусом проверки. Это дешевле и надёжнее, чем надеяться, что автоматическое compaction сохранит действительно важные архитектурные решения.

Skills, hooks и агенты Второй важный блок посвящён разделению ролей.

Автор предлагает не смешивать в одну кучу MCP, tools, skills, hooks, plugins и subagents. Логика такая: инструмент даёт новую возможность, skill задаёт рабочий процесс, hook вшивает обязательную автоматическую проверку, а subagent выносит отдельную задачу в изолированный контекст. Это полезное уточнение, потому что многие команды пытаются лечить любой сбой новым промптом или очередным tool, хотя проблема может решаться совсем на другом уровне.

Статья отдельно объясняет, каким должен быть хороший skill. У него короткий и точный дескриптор, понятный триггер использования, прописанные входы, выходы и условие остановки. Всё тяжёлое — примеры, runbooks, вспомогательные файлы — должно подтягиваться по требованию, а не висеть в основном SKILL.

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

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

Чем раньше система поймала ошибку, тем меньше токенов, времени и лишних правок уйдёт в мусор.

Кэш, верификация и контракт

Одна из самых интересных частей текста — объяснение того, насколько архитектура Claude Code завязана на prompt caching. Автор пишет, что стабильный префикс промпта экономит не только деньги, но и снижает трение по лимитам. Отсюда несколько неочевидных правил: не вставлять динамические данные в системный промпт, не тасовать порядок инструментов, не переключать модель посреди длинной сессии без необходимости и по возможности откладывать полную загрузку редких tool-схем.

Даже Plan Mode, как отмечается в статье, удобнее реализовывать без смены всего набора инструментов, чтобы не ломать кэш. Финальный акцент сделан на верификации и на роли CLAUDE.md.

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

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

«Если вы не можете объяснить, как понять, что

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

Что это значит Этот материал важен не только для пользователей Claude Code.

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