Введение

Привет, Хабр! Я Максим, ведущий специалист по анализу данных и машинному обучению в логистике. Сегодня хочу поговорить про результаты и боль в работе с 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/
  rules/ # контекст для агентов
    reference.md             # полный технический референс проекта
    frontend-style-guide.md  # цвета, типографика, анимации
    profile.md               # мой бэкграунд и как со мной работать
  memory/ # хранилище знаний
    integration-contracts.md   
    architecture-decisions.md  
    tasks-completed.md         
  agents/ # инструкции для агентов
    orchestrator-agent.md  
    backend-agent.md        
    frontend-agent.md       
    shared-agents.md        
  templates/ # шаблоны кода
    new-api-endpoint.md     
    new-page.md             
    new-db-table.md
  scripts/ # скрипты для автоматизации команд
    hook-pre-deploy.sh
    hook-post-commit.sh
    hook-stop-reminder.sh
skills/ # навыки для выполнения задач
  check-contract.md   # проверка работы фронта и бэка
  	project-map.md      # поиск по карте проекта

В самом CLAUDE.md – только короткие указатели и правила поведения. Если описание чего-то занимает больше 3 строк, это не для CLAUDE.md. Он всё равно забудет.

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

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

Стал ли CLAUDE.md волшебной таблеткой от собственных ошибок? Нет. Но работать стал явно эффективнее. Мне проще напомнить про этот файл, чем перечислять все инструкции, и это действительно работает.

---

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

Claude Code не имеет памяти между сессиями. Это архитектурная особенность, а не баг. Решение – вынести «память» в файловую систему.

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

Пример записи:

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:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "bash .claude/scripts/hook-pre-deploy.sh" }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "bash .claude/scripts/hook-post-commit.sh" }]
    }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "bash .claude/scripts/hook-stop-reminder.sh" }]
    }]
  }
}

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

#!/bin/bash
# Если запускается деплой – проверяем, что push был сделан
if echo "$BASH_COMMAND" | grep -q "deploy.sh"; then
  LOCAL=$(git rev-parse HEAD)
  REMOTE=$(git rev-parse origin/main 2>/dev/null)
  if [ "$LOCAL" != "$REMOTE" ]; then
    echo "❌ Deploy blocked: git push required first"
    exit 1
  fi
fi

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

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

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

---

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

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

DB Migration → Backend Route → Frontend Component
                    ↓                   ↓
              Security Audit ←→ Code Review + Tests
                         (параллельно)

Почему это важно: если делать последовательно, то проверка кода блокирует тесты, тесты блокируют проверку безопасности. Параллельный запуск сокращает время выполнения в 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

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

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

// package.json scripts 
"audit:style": "node scripts/style-audit.mjs", 
"lint:style": "eslint src/ --rule 'tailwindcss/no-contradicting-classname: error'",
"fmt:classes": "prettier --write src/ --plugin prettier-plugin-tailwindcss"  

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 — постепенно окажется похоронено под пеплом сожженых токенов.

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

.claude/
  rules/ # контекст для агентов
    reference.md             # полный технический референс проекта
    frontend-style-guide.md  # цвета, типографика, анимации
    profile.md               # мой бэкграунд и как со мной работать
  memory/ # хранилище знаний
    integration-contracts.md   
    architecture-decisions.md  
    tasks-completed.md         
  agents/ # инструкции для агентов
    orchestrator-agent.md  
    backend-agent.md        
    frontend-agent.md       
    test-agent.md
    security-auditor.md
     ...
  templates/ # шаблоны кода
    new-api-endpoint.md     
    new-page.md             
    new-db-table.md
  scripts/ # скрипты для автоматизации команд
    hook-pre-deploy.sh
    hook-post-commit.sh
    hook-stop-reminder.sh
skills/ # навыки для выполнения задач
  check-contract/
       SKILL.md   # проверка работы фронта и бэка
  project-map/
       SKILL.md   # поиск по карте проекта

---

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

Claude Code – мощный инструмент, но сам по себе он не гарантирует качество. Кто там говорит, что айтишники уже не нужны – почитайте об успехе разработки в Amazon, и почему полмира в прошлом году дважды сидело без интернета.

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

Система, которую я описал, строится на нескольких принципах:

• Не полагайся на CLAUDE.md , как на свалку – нет смысла всё туда сваливать. В этом файле нужна жёсткая структура правил и ссылок.

• Не полагайся на память агента – всё важное должно быть в файлах.

• Кодируй правила в инфраструктуру – хуки надёжнее инструкций в промпте.

• Нулевая толерантность к стилевым ошибкам –чтобы не было больно глазам не пропускать ошибки дизайн на фронт .

• Декомпозируй и параллели – агентная оркестрация окупается на задачах от 10+ минут.

• Шаблоны вместо изобретения – типовые операции не должны требовать творчества.

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

Если у вас есть свои правила работы с Claude Code или другими агентами – буду рад обсудить их в комментариях.