Исторически каждая новая технология приносила собственный "декларативный слой", который позволял перестать объяснять системе, как выполнять задачу, и начать описывать, что требуется получить.
Но сначала, о себе. Меня зовут Влад. Создаю прибыльные продукты с ai агентами и людьми.
В тг дневнике рассказываю о том, что создал / сколько заработал. И чему научился за 2 года разработки с AI
🔴 В следующей статье расскажу про ошибки при составлении Claude.md и других спек для агентов.
Большинство разработчиков до сих пор считают, что CLAUDE.md — это место, куда можно записать свои предпочтения.
использовать TypeScript;
не использовать any;
писать комментарии;
запускать тесты;
использовать Tailwind.
Подобные файлы действительно работают. Но лишь частично. Проблема в том, что они воспринимают Claude как обычную LLM.
Claude Code давно перестал быть просто моделью. Сегодня это агентная среда исполнения.
Он читает файлы.
Изучает Git.
Запускает терминал.
Создает новые документы.
Проводит рефакторинг.
Вызывает MCP-серверы.
В определенном смысле Claude Code больше напоминает младшего разработчика, чем чат-бота.
И именно здесь появляется новая инженерная задача. Любому инженеру необходимы правила работы. AI-агент получает CLAUDE.md.
Это декларация поведения интеллектуальной системы.
Именно поэтому определение "README для Claude" является слишком упрощенным.
Более точная формулировка выглядит так:
CLAUDE.md — это декларативная спецификация поведения AI-агента внутри конкретного проекта.
Почему проблема оказалась настолько серьезной
До появления Claude Code большинство взаимодействий выглядели одинаково.
Каждая новая задача начиналась примерно так:
Следуй Clean Architecture.
Используй существующий стиль проекта.
Не создавай новые зависимости.
И те же инструкции повторялись заново.
Через неделю — сотни повторений.
Это не просто неудобство.
Это фундаментальная проблема архитектуры взаимодействия человека и AI.
Постоянный контекст не должен жить в голове пользователя.
Он должен жить внутри проекта.
Именно эта идея лежит в основе всей современной агентной разработки.
Как мы пришли к CLAUDE.md: эволюция передачи контекста AI
Появление CLAUDE.md — это не случайное решение Anthropic и не очередной конфигурационный файл. Это закономерный этап эволюции разработки с языковыми моделями.
Каждый новый этап решал проблему предыдущего, но одновременно открывал новую.
Этап 1. Prompt Engineering
Первые поколения LLM не обладали ни памятью, ни пониманием проекта.
Единственным способом управлять моделью был длинный промпт.
Разработчики быстро поняли простую закономерность: чем больше контекста получает модель, тем лучше она понимает задачу.
Поэтому появились огромные промпты, в которых описывали буквально всё:
Каждая новая сессия начиналась одинаково: сначала несколько тысяч слов инструкций, и только потом — сама задача.
Но было совершенно не масштабируемо.
Любое изменение архитектуры требовало переписывать промпт. Любой новый чат означал, что весь контекст придется объяснять заново.
Этап 2. System Prompt
Следующим шагом стали системные инструкции.
Часть правил переехала внутрь модели.
Теперь пользователю не нужно было каждый раз писать:
Отвечай как опытный разработчик.
Однако системный промпт решал только общие задачи.
Он не знает, что именно ваш проект использует Feature-Sliced Design, запрещает ORM или требует писать тесты перед каждым коммитом.
System Prompt знает, как должна вести себя модель вообще.
Но он не знает, как должен работать агент именно в вашем проекте.
Этап 3. Memory
Затем появилась долговременная память.
Модель научилась запоминать пользователя.
Это значительно улучшило взаимодействие.
Но память оставалась персональной.
Она не принадлежала проекту.
Если завтра в команду приходил другой разработчик или создавался новый репозиторий, все знания о проекте снова приходилось объяснять вручную.
Этап 4. AI-агенты
Настоящий перелом произошел тогда, когда модели перестали быть просто собеседниками.
Они превратились в полноценных программных агентов.
Современный агент уже не ограничивается генерацией кода.
Во время выполнения одной задачи он может:
анализировать структуру репозитория;
искать зависимости между файлами;
запускать команды в терминале;
выполнять тесты;
читать документацию;
использовать MCP-серверы;
редактировать десятки файлов;
создавать Pull Request.
Именно здесь возникла новая проблема.
Теперь модель принимает не одно решение, а сотни небольших инженерных решений подряд.
Можно ли добавить зависимость.
Стоит ли делать рефакторинг.
Нужно ли переписать соседний модуль.
Если раньше ошибка в промпте влияла на один ответ, то теперь она начинает влиять на всю цепочку действий агента.
Стало очевидно, что агенту недостаточно просто понимать задачу.
Он должен понимать правила проекта, внутри которого работает.
Именно поэтому индустрия постепенно пришла к новому уровню абстракции — постоянным инструкциям проекта.
Теперь знания о проекте перестали жить в промптах и памяти отдельных разработчиков.
Они стали частью самого репозитория.
Любой агент, который открывает проект, сначала изучает его правила, а уже потом начинает принимать решения.
Это означает переход от Prompt Engineering к Context Engineering — проектированию среды, в которой агент работает, а не отдельных запросов к модели.
Этап 5. Context Engineering
Сегодня центр внимания сместился.
Как написать хороший промпт?
Теперь вопрос звучит иначе:
Как правильно построить среду, в которой агент будет принимать решения?
Именно это называется Context Engineering.
CLAUDE.md является его главным инструментом.
CLAUDE.md — это операционная система поведения
Представим двух разработчиков.
Они используют абсолютно одинаковую модель Claude.
монолит;
Laravel;
простые CRUD.
Без CLAUDE.md модель вынуждена угадывать.
С CLAUDE.md она уже знает:
где должна появиться новая логика;
какие слои можно изменять;
какие директории запрещены;
какие зависимости использовать нельзя;
какие тесты обязательны;
какие архитектурные решения являются допустимыми.
Это принципиально меняет качество работы агента.
Фактически каждое решение проходит дополнительный уровень проверки.
Можно представить это так:
Задача ↓ Claude ↓ CLAUDE.md ↓ Архитектурные ограничения ↓ Инструменты ↓ Редактирование ↓ Тестирование ↓ Проверка критериев готовности ↓ Результат
Пользователь вообще не упоминает архитектуру.
Она уже встроена в поведение агента.
Главная ошибка большинства CLAUDE.md
Практически все открытые репозитории совершают одну и ту же ошибку.
Они записывают предпочтения, а не инварианты.
❌ Используй красивые названия.
Подобные инструкции невозможно проверить.
Хорошее правило всегда обладает тремя свойствами.
Оно конкретное
Используй хорошие практики.
Никогда не создавай функцию длиннее 40 строк без объяснения причины.
Оно проверяемое
Перед завершением задачи обязательно выполни lint и typecheck.
Оно влияет на принятие решений
Используй красивый стиль.
Никогда не добавляй новую библиотеку, если аналогичная функциональность уже существует в проекте.
Именно такие правила начинают менять поведение агента.
Они превращают модель из генератора текста в исполнителя инженерной политики проекта.
Почему идеальный CLAUDE.md короче, чем кажется
Парадоксально, но лучшие CLAUDE.md редко бывают огромными.
Когда файл превращается в свалку из сотен пожеланий, возникает противоположный эффект.
Правила начинают конфликтовать.
Менее важные инструкции вытесняют более важные.
Вместо декларации архитектуры получается список случайных мыслей команды.
Идеальный CLAUDE.md не пытается ответить на все вопросы.
Он отвечает только на один:
Какие правила агент обязан соблюдать независимо от поставленной задачи?
Именно поэтому хороший файл больше похож на конституцию государства, чем на техническую документацию.
Он не описывает каждую ситуацию.
Он определяет фундаментальные принципы, из которых агент выводит конкретные решения самостоятельно.
Именно это делает CLAUDE.md одним из самых недооцененных инженерных документов эпохи агентного программирования.
