Когда подключаешь Claude к большому существующему проекту, первая проблема появляется почти сразу: как объяснить ему архитектуру и при этом не превратить CLAUDE.md в файл на несколько тысяч строк.

Можно расписать структуру каталогов, сервисы, репозитории, модели, тесты, Swagger, правила работы с БД, запреты и исключения. Но такой промпт быстро превращается в свалку.

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

Делегируем карту проекта Serena

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

.serena/memories/

Если Claude нужно понять, где находится реализация интерфейса, кто вызывает сервис или какие классы зависят от конкретного объекта, он должен идти в Serena и использовать семантическую навигацию по коду.

Структура проекта существует не как огромный текстовый промпт, а как источник знаний, который запрашивается по необходимости.

Промпт — это только набор правил, без карты проекта

Вместо одного большого промпта я создаю набор небольших файлов. Каждый rule изолирован и отвечает только за свой аспект разработки. Это уменьшает количество пересечений и противоречий в инструкциях для модели.

architecture.md Правила написания нового API и редактирования существующего. Правила создания новых классов, сервисов и их архитектурные границы.

database.md Правила создания миграций, типы для денежных значений, обязательные транзакции и запрет на изменение уже применённых миграций.

api-swagger.md Правила создания и редактирования Request/Resource, форматы ответов API и требования к обновлению OpenAPI-схемы.

testing.md Какие изменения обязательно покрываются тестами, где нужны feature-тесты, где unit-тесты и какие сценарии считаются минимально необходимыми.

Что остаётся в CLAUDE.md

Основной CLAUDE.md становится небольшим управляющим файлом, который:

- описывает приоритеты работы (Serena first); - подключает отдельные rules для гибкой настройки процесса разработки; - содержит общие разрешения, запреты и рекомендации.

Получается простое разделение:

.serena/ — знания о структуре проекта, символах, связях и project memories. .claude/rules/ — правила написания кода, архитектурные ограничения, БД, Swagger, тестирование, разрешения и запреты.

Также важно явно указать, что модели нельзя делать полный обход проекта через Grep / Glob / Read, если необходимую информацию можно получить через Serena.

Два разных источника истины

Serena отвечает на вопрос: «Как проект устроен сейчас?»

Rules отвечают на вопрос: «Как в этом проекте нужно писать код?»

Первое меняется вместе с кодовой базой и должно извлекаться непосредственно из неё. Второе является договорённостью команды и должно быть сформулировано явно.

Именно поэтому смешивать эти два типа информации в одном огромном промпте нет смысла. Правила при такой структуре можно менять независимо.

Изменился подход к тестированию — редактируется только testing.md. Появилось новое требование к API — только api-swagger.md. Изменились правила работы с миграциями — только database.md.

Не приходится искать нужный абзац внутри огромного CLAUDE.md и думать, не конфликтует ли новое правило с инструкцией, написанной где-то двумя тысячами символов выше.

Вывод

Serena получает карту проекта через onboarding и индексирование → .claude/rules фиксирует инженерные правила → CLAUDE.md связывает всё это вместе.

Такое разделение делает AI-разработку управляемее: меньше дублирования, меньше устаревших инструкций и меньше шансов, что модель начнёт придумывать архитектуру там, где её можно просто спросить у Serena.

#BestPractise #AI #Claude #Architecture