Работа с LLM-агентами, такими как Claude Code, позволяет ускорить разработку, но при этом несёт риски деградации кодовой базы. В соло-проекте с реальными пользователями — React + TypeScript, Express/Node.js, PostgreSQL и DeepSeek в роли LLM — автор столкнулся с типичными проблемами: потеря контекста, дублирование решений, пропущенные деплои и несогласованный стиль кода. Чтобы стабилизировать процесс, была создана система, основанная на структурированной автоматизации, памяти и жёстких правилах.

Почему проекты с LLM-агентами деградируют

Агенты не обладают долгосрочной памятью и каждый раз начинают с нуля. Это приводит к трём основным векторам деградации:

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

Важно: всё описанное относится к Claude Code (CLI-агент от Anthropic). Некоторые идеи применимы к другим агентам, но механика — CLAUDE.md, хуки, settings.json — специфична именно для него.

CLAUDE.md: навигационный слой, а не энциклопедия

CLAUDE.md — это файл, который агент читает в начале каждой сессии. Главная ошибка — превращать его в свалку. После ~200 строк значимость инструкций резко падает. Вместо этого файл должен быть кратким и содержать только ключевые правила и указатели.

Если описание занимает больше трёх строк — оно не для CLAUDE.md. Лучше разнести информацию по папкам в .claude/. Самое важное правило в файле: после выполнения задачи анализировать процесс и предлагать улучшения. Это правило стало основой всей системы.

Memory-файлы: имитация долгосрочной памяти

Поскольку агент не помнит прошлые сессии, память нужно выносить в файлы. Три ключевых файла:

• integration-contracts.md — контракты API: методы, пути, параметры, форматы ответов. Без этого агент продолжает использовать устаревшие эндпоинты.
• architecture-decisions.md — решения, которые были отвергнуты и почему. Это предотвращает возврат к уже обсуждённым и отброшенным вариантам.
• tasks-completed.md — архив завершённых задач с датами и кратким описанием. Помогает избежать повторного внедрения откатанных улучшений.

Memory-файлы работают только при автоматическом обновлении. В CLAUDE.md есть правило: «После каждой задачи (без исключений): обновить todo.md и соответствующие файлы памяти».

Rules и Skills: разделение знаний и действий

Разделение между Rules и Skills помогает агенту эффективнее использовать информацию.

• Rules — пассивные знания: структура проекта, гайдлайны стиля, правила общения. Хранятся в rules/.
• Skills — активные процедуры с чётким вводом и выводом. Например, проверка контрактов или генерация карты проекта. Хранятся в skills/.

Простой тест: если можно сказать «запусти X и скажи, что получилось» — это Skill. Если это справочная информация — это Rule.

Templates: шаблоны вместо изобретения

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

• new-api-endpoint.md — готовый Express-роут с авторизацией, валидацией, обработкой ошибок и логированием.
• new-db-table.md — шаблон миграции с именованием, .down.sql и нумерацией.

Каждый раз, когда агент делает что-то не так — это сигнал: нужен шаблон.

Хуки: автоматизация процессов

Хуки — скрипты, запускаемые до и после действий агента. Они надёжнее правил в промпте, потому что их нельзя проигнорировать.

• hook-pre-deploy.sh — блокирует деплой, если не было git push. Предотвращает расхождение между локальным кодом и сервером.
• hook-post-commit.sh — напоминает обновить memory-файлы и проверить, нужен ли деплой.
• hook-stop-reminder.sh — при завершении сессии выводит чеклист: обновлены ли документы, запущен ли аудит, сделан ли пуш.

Ключевое преимущество хуков: их нельзя «забыть». Правило в промпте агент может проигнорировать. Хук — нет.

Агентная оркестрация: параллелизм для ускорения

Для сложных задач используется многоагентная архитектура. Задача разбивается, и части выполняются параллельно:

• orchestrator-agent.md — декомпозирует задачу и координирует других.
• backend-agent.md — работает с Express, БД, LLM.
• frontend-agent.md — отвечает за React, i18n, дизайн.
• shared-agents.md — ревью, тесты, аудит безопасности.

Порядок выполнения:

1. Сначала миграция БД — нельзя писать код для несуществующей таблицы.
2. Потом API — фронтенд должен знать контракт.
3. Ревью и тесты — параллельно, не зависят друг от друга.

Параллелизм сокращает время выполнения в 2–3 раза и экономит токены.

Дизайн-аудит: нулевая толерантность к визуальным ошибкам

Без контроля UI быстро деградирует. Решение — автоматический аудит стилей:

• Поиск inline-градиентов.
• Запрет хардкодных цветов вне CSS-переменных.
• Блокировка запрещённых Tailwind-классов.

Скрипт style-audit.mjs запускается перед коммитом. Если найдены ошибки — коммит не проходит. Это жёсткое правило, но оно спасает от визуального хаоса.

Что ещё можно улучшить

Система не идеальна. Есть открытые проблемы:

• Автоматическая синхронизация языков — английская локализация должна обновляться автоматически при появлении нового текста на русском.
• Проверка работоспособности после деплоя — сейчас проверяется только запуск процесса, но не функциональность.
• Список запрещённых паттернов — нет явного запрета на добавление зависимостей без обсуждения, изменение схемы БД без миграции или использование any в TypeScript.
• Архивация memory-файлов — tasks-completed.md растёт бесконечно. Нужно переносить старые задачи в архив, чтобы не засорять контекст.

Итог: принципы стабильной работы с Claude Code

Система строится на шести принципах:

• Не сваливай всё в CLAUDE.md — он должен быть структурированным и кратким.
• Не полагайся на память агента — важное знание должно быть в файлах.
• Кодируй правила в инфраструктуру — хуки надёжнее промптов.
• Нулевая толерантность к стилевым ошибкам — не пропускай нарушения дизайна.
• Декомпозируй и параллели — агентная оркестрация окупается на задачах от 10+ минут.
• Используй шаблоны — типовые операции не должны требовать творчества.

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

Привет, Хабр! Я Максим, ведущий специалист по анализу данных и машинному обучению в логистике. Сегодня хочу поговорить про результаты и боль в работе с Claude Code. Для примера возьму свой пет-проектawesome-project.com(название изменено) – приложение, в котором пользователи работают с AI-ассистентом в рамках структурированных сессий. Под капотом: React + TypeScript для фронтэнда, Express/Node.js - бекенд, PostgreSQL для работы с данными и DeepSeek в роли LLM. Это соло-проект с реальными пользователями, где Claude Code работает как основной соисполнитель – пишет код, мигрирует БД, деплоит.За время разработки я наступил на каждую возможную граблю (и чувствую, что их поток не кончается):

• сессии, которые «забывали» архитектурные решения;
• агент, который в третий раз предлагал переписать то, что мы уже переписывали;
• коммиты без деплоя;
• деплои без перезапуска сервиса;
• инструкции и документы, которые лежали без смысла, и Claude заново прочёсывал весь код.

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

Важная оговорка: всё описанное работает для Claude Code (CLI-агент от Anthropic). Часть идей переносима на других агентов, но конкретная механика – CLAUDE.md, хуки, settings.json – специфична именно для него.

1. Проблема: почему проекты с LLM-агентами деградируют быстрее

В Alibaba недавно выкатили исследование с известным результатом: когда код пишется с ИИ-моделями – он деградирует. Лучше всех из 18 моделей справился Opus 4.6, а с деталями вы можете ознакомитьсяпо ссылке.

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

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

• Контекстуальная амнезия.Агент не помнит, какие решения уже принимались и почему. Он видит только текущий код – но не историю: что пробовали, от чего отказались, что обсуждали и не стали делать. В какой-то момент он начнёт предлагать «улучшения», которые на самом деле откат к уже отвергнутым вариантам.
• Отсутствие единого стиля.Без явных ограничений каждая новая сессия может внести чуть другой стиль написания компонентов, другое использование типов, чуть другую структуру маршрутов. Через месяц кодовая база превращается в лоскутное одеяло.
• Процессные пробелы.Агент может написать отличный код, но «забыть» перевести часть текста с русского на английский, не запустить аудит стиля, не добавить трекинг события. Каждый такой пропуск – потраченный впустую час и ещё одна чашка кофе. Решение – бросить пить кофе и каждый раз прописывать всё в промпте – невозможно. Во-первых, кофе очень вкусный. Во-вторых, промпт получается безумно раздутым, и агент всё равно теряет контекст. Приходится не надеяться на память агента, а кодировать знания и процессы в инфраструктуру.

2. CLAUDE.md: навигационный слой, а не энциклопедия

CLAUDE.md – это файл, который Claude Code читает автоматически в начале каждой сессии. Главная ошибка – класть туда всё подряд. На Хабре есть немало упоминаний этого файла, но мало кто акцентирует внимание на особенности работы с ним самого агента. По личным наблюдениям (и заверениям Claude Code) примерно с 200-й строки значимость инструкций настолько сильно затухает, что теряется буквально на первом запросе.Я видел CLAUDE.md на 800+ строк с примерами кода, SQL-миграциями и командами деплоя. Такой файл создаёт следующие проблемы: агент тратит огромное количество контекстного окна на неактуальное, возникают внутренние противоречия между старыми и новыми инструкциями, и файл перестаёт читаться вообще – ни человеком, ни агентом.

CLAUDE.md – это указатель и сборник строгих правил, остальное раскидано в .claude/ по папкам.

Файл лежит в корне проекта или в .claude/ и создается автоматом при вызове /init в консоле Claude Code.Мояструктуравыглядит так:

В самом CLAUDE.md – толькокороткие указателииправила поведения. Если описание чего-то занимает больше 3 строк, это не для CLAUDE.md. Он всё равно забудет.Наверное, самое важное из правил, которые лежат в этом файле, – по итогу выполнения задачи анализировать процесс и предлагать шаги по улучшению, чтобы снизить временны́е затраты и количество потреблённых токенов. От этого правила постепенно произошли все остальные и появились блоки, про которые расскажу ниже.Ещё важно сказать, что правила в этом файле как будто позволяют управлять фокусом внимания агента. И они заметно эволюционировали с момента старта проекта по текущий день.Стал ли CLAUDE.mdволшебнойтаблеткой от собственных ошибок?Нет. Но работать стал явно эффективнее. Мне проще напомнить про этот файл, чем перечислять все инструкции, и это действительно работает.

3. Memory-файлы: как имитировать долгосрочную память агента

Claude Code не имеет памяти между сессиями. Это архитектурная особенность, а не баг. Решение – вынести «память» в файловую систему.Три самых важных файла вmemory/:integration-contracts.md– контракты между фронтендом и бэкендом. Каждый API-эндпоинт: метод, путь, параметры запроса, формат ответа, коды ошибок. Без этого агент не замечает, что путь изменился, и продолжает обращаться к нему по-старому.Пример записи:

/api/ai/summarize

{ text, lang? }

{ summary }

/api/ai/suggest

{ context, history?, lang? }

SSE stream

/api/ai/feedback

{ messageId, rating }

{ ok: true }

architecture-decisions.md– Код показывает агенту, что выбрано. Но не показывает, что было отброшено и почему. А именно отброшенные варианты он будет предлагать снова, потому что они выглядят разумно, если не знать предыстории. Записывайте причины отказов: это единственное знание, которое агент не может восстановить из кода самостоятельно. Архив решений помогает избежать возврата к старым решениям.tasks-completed.md– архив завершённых задач с датами и кратким описанием того, что было сделано. Это помогает агенту не предлагать «улучшения», которые вы уже реализовывали и откатывали. Заодно помогает быстрее искать по коммитам старые решения, если надо откатывать изменения.

Memory-файлы работают только если обновляются автоматически после каждой задачи. В моём CLAUDE.md написано буквально: «После каждой задачи (без исключений, не ждать отдельного запроса): обновить todo.md, записать в соответствующий файл памяти».

Судя по логам, Claude Code и агенты действительно обращаются к этим файлам – особенно на этапе планирования задач или если упёрлись в тупик.

4. Rules: что нужно знать до старта

Есть тонкая когнитивная граница между тем, что должно лежать в Skills и тем, что должно лежать в Rules(rules/). Рекомендуется разделять их следующим образом:

Rules– это контекст, который агент читает пассивно в начале сессии или когда ему нужна справка. Он не «делает» ничего, просто знает.reference.md– как устроен проект,frontend-style-guide.md– какие цвета и отступы,profile.md– как с тобой общаться. Это фоновое знание.

Skills– это процедуры с конкретным input/output, которые агент вызывает активно для выполнения задачи. Это действия к выполнению в определенных ситуациях, а не справка.

На практике граница размывается, и легко ошибиться в любую сторону. Чтобы этого избежать можно использовать легкий тест: если можно сказать «запусти X и скажи, что получилось» – это Skill. Если это просто справочная информация, которая влияет на то, как агент пишет код – это Rules.

5. Skills и Templates: переиспользуемые процедуры

Помним,Skills– это переиспользуемые «процедуры» для типовых операций. Лежит вskills/.Вместо того чтобы каждый раз объяснять агенту, как проверить контракт, у меня есть /check-contract, который делает это автоматически.

Используемые в проекте скиллы:

• /check-contract– верифицирует соответствие между бэкенд-роутами и фронтенд-вызовами после изменений API
• /project-map– получает карту проекта, ускоряет поиск нужных файлов.
• /notebooklm– многоисточниковый ресёрч и синтез документации. Есть про это статья на Хабре, рекомендую. Очень полезно на старте проекта.

Templatesрешают другую проблему: агент не должен «придумывать» структуру для стандартных операций, он должен её заполнять. Хранятся в templates/ следующие файлы:

new-api-endpoint.mdсодержит точный шаблон Express-роута для этого проекта: с requireAuth, с правильным форматом ошибок { error: "message" }, с sanitizeInput(), с нужными try/catch блоками и форматом логирования. Агент не изобретает – копирует и подставляет.

new-db-table.md -шаблон миграции с соглашением именования, с .down.sql, с нумерацией NNN_description.sql.

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

6. Хуки: кодируй правила в инфраструктуру, не в промпт

Хуки – это скрипты, которые автоматически запускаются до и после операций агента. Лежат в scripts/. Claude Code ненавязчиво и без предупреждения игнорирует некоторые инструкции. Чтобы облегчить жизнь этому работяге и уменьшить у себя уровень кортизола, некоторые команды можно сделать автоматическими. Их вызов настраивается в.claude/settings.json:

hook-pre-deploy.sh– блокирует деплой, если не было git push. Звучит тривиально, но это классическая ошибка: агент сделал git commit, получил подтверждение, и сразу пошёл деплоить. На сервере оказывается код из предыдущего коммита. Наверное, это была самая частая ошибка, когда агент писал, что изменения сделаны, а на сервере их нет и тесты их не видят.

hook-post-commit.sh– после коммита напоминает обновить memory-файлы и проверить, нужен ли деплой.

hook-stop-reminder.sh– запускается когда агент завершает работу. Выводит чеклист: обновлены ли docs, запущен ли style audit, сделан ли push. Очень полезно – можно отдельно прочитать, чем же закончилось получасовое ожидание.

Ключевое преимущество хуков перед правилами в промпте: их нельзя «забыть». Правило в CLAUDE.md агент может проигнорировать при большом контексте. Хук – нет.

7. Агентная оркестрация: параллелизм как ускоритель

Для крупных задач я использую многоагентную архитектуру. Вместо того, чтобы делать всё в одной сессии последовательно, задача декомпозируется и независимые части выполняются параллельно. Инструкции для агентов записаны в agents/. Порядок работы агентов для типичной задачи:

Почему это важно: если делать последовательно, то проверка кода блокирует тесты, тесты блокируют проверку безопасности. Параллельный запуск сокращает время выполнения в 2-3 раза и экономит токены! Каждый агент имеет свой файл с инструкциями в.claude/agents/(первый три работают на Opus 4.6, последний на Sonnet 4.6) :

• orchestrator-agent.md– декомпозирует задачу, координирует других агентов
• backend-agent.md– Express роуты, DB миграции, LLM интеграция
• frontend-agent.md– React компоненты, i18n, дизайн.
• shared-agents.md– ревью кода и аудит безопасности, тесты.

Примеры правил оркестрации:

1. Сначала миграция БД – нельзя писать путь к таблице, которой ещё нет
2. Потом API – фронтенд должен знать контракт до того, как начнёт писать компонент
3. Ревью и тесты – параллельно, они друг от друга не зависят

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

8. Дизайн-инструкция: барьер от деградации UI

Визуальная деградация – один из самых неприятных видов деградации. Примерно за три дня активной работы с фронтом и без этих правил всё оформление превратилось в кашу. Пришлось искать выход.

Решение – автоматический аудит стилей с нулевой толерантностью к ошибкам, который описан в :

style-audit.mjs– кастомный скрипт, который проходит по всем файлам src/ и ищет:

• Inline-градиенты (linear-gradient, radial-gradient в style-атрибутах)
• Хардкодные цвета (#hex, rgb(), rgba() вне CSS-переменных)
• Запрещённые Tailwind-классы (например, прямые цветовые классы, которые заменены собственными)

Правило жёсткое:0 ERRORs required before commit. Если скрипт падает, коммит не проходит. Не «желательно исправить», не «посмотрим потом» – все дизайн-ошибки должны быть исправлены до деплоя.

Такое правило ест мало-помалу токены, зато не страшно нажимать F5 и смотреть, что же там наваял фронтенд-агент.

9. Пробелы: что ещё можно улучшить

Буду честен. Файлик с предложениями по улучшениям обновляется каждый день. Часть правил Claude Code продолжает периодически дерзко игнорировать.

Вот что последнее скопилось у меня в списке задач:

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

После деплоя ничто автоматически не проверяет, что приложение реально работает – только то, что процесс запустился.Тесты в целом отдельная боль. Агент может безуспешно пытаться залогиниться по 10 раз, хотя у него есть правило «остановись на второй попытке» и рабочие(!) email и пароль, которые уже работали в предыдущей сессии. Может стоит перевести агента для тестирования на Opus 4.6 и выделить в отдельную сущность.

Список запрещённых паттернов.В CLAUDE.md есть стандарты написания. кода, но нет явного списка запретов: «не добавлять зависимости без обсуждения», «не менять схему БД без миграции», «не использовать any типы». Агент нарушает именно то, что нигде явно не запрещено.Архивирование memory-файлов.tasks-completed.mdбудет расти бесконечно. Нужна политика: задачи старше 30–60 дней переезжают вarchive/. Иначе со временем файл станет слишком большим и начнёт «шуметь» в контексте.

10. Примечание: что следует помнить

Отдельно стоит обратить внимание, что для Claude Code есть официальная документация. Её бывает очень полезно читать и перечитывать. Например, пока писал статью отдельно подчёркивал проблему с управлением процесса тестирования. В документации чётко написано, что для каждого агента должна быть своя инструкция. Выделение shared_agents.md в отдельные файлы в моменте решило проблему с тестированием. Теперь агент вовремя подключается и активно участвует в разработке.

Также заметил, что в начале выполнения некоторых задач сходу потребляется порядка 50к токенов, а потом это число доросло до 75 к и больше. Странно, ведь был скилл project-map.md и, казалось, что агент должен опираться на него впервую очередь. Но, оказалось, что Claude оформил его не правильно. Нужно было написать название скилла, а внутри сделать файлик SKILL.md с описанием самого скилла. Теперь на ознакомление с проектом потребляется порядка 2-3х тысяч токенов. Экономия в 25 раз.

Завершая, отмечу, что существует ограниченный набор правил для Claude , как должны называться папки в директории .claude:

• .claude/agents/ — субагенты (вызов через@name).
• .claude/skills/ — навыки/слэш-команды.
• .claude/rules/ — контекстные правила .

Все остальное, что вы положили туда(например, агентскую память), но не упомянули в CLAUDE.md - постепенно окажется похоронено под пеплом сожженых токенов.

Итоговый макет структуры проекта следующий:

11. Заключение

Claude Code – мощный инструмент, но сам по себе он не гарантирует качество. Кто там говорит, что айтишники уже не нужны – почитайте об успехе разработки в Amazon, и почему полмира в прошлом году дважды сидело без интернета.Поэтому без системы вокруг Claude Code проект деградирует быстрее, чем с обычной командой, просто потому что агент не помнит вчера, не замечает тренды и не несёт ответственности за долгосрочные последствия. Коллеги по цеху не поругают его на кофебрейке за небрежные коммиты, а значит можно делать всё, что не запрещено.Система, которую я описал, строится на нескольких принципах:

• Не полагайся на CLAUDE.md , как на свалку – нет смысла всё туда сваливать. В этом файле нужна жёсткая структура правил и ссылок.
• Не полагайся на память агента – всё важное должно быть в файлах.
• Кодируй правила в инфраструктуру – хуки надёжнее инструкций в промпте.
• Нулевая толерантность к стилевым ошибкам –чтобы не было больно глазам не пропускать ошибки дизайн на фронт .
• Декомпозируй и параллели – агентная оркестрация окупается на задачах от 10+ минут.
• Шаблоны вместо изобретения – типовые операции не должны требовать творчества.

Решают ли эти принципы все боли? Нет. Иногда есть вопросы к тому, что агент реально держит «в голове» и как подходит к выполнению задачи. Но эти принципы помогли ощутимо уменьшить потребление токенов, повысить прозрачность процессов и замедлить деградацию системы, если не остановить.Если у вас есть свои правила работы с Claude Code или другими агентами – буду рад обсудить их в комментариях.