Советник Claude Code каждый раз напоминает о «сути проекта»: как писать CLAUDE.md с учётом официальной спецификации
14 июля 2026
Каждый разработчик, работающий с Claude Code, рано или поздно сталкивается с ситуацией: советник снова и снова напоминает о «сути проекта», даже если вы уже десятый раз объясняете одни и те же требования. Разработчики из сообщества Anthropic нашли элегантное решение — файл CLAUDE.md. В официальной документации и практике сообщества этот файл стал не просто удобным инструментом, а обязательным атрибутом для эффективной работы с AI-советником. В этой статье — как правильно составить CLAUDE.md, чтобы Claude Code перестал задавать лишние вопросы и начал работать как продолжение вашей команды.
Что такое CLAUDE.md и зачем он нужен?
CLAUDE.md — это конфигурационный файл, который определяет поведение советника Claude Code в контексте конкретного проекта. По сути, это набор инструкций, правил и подсказок, которые AI-советник использует каждый раз, когда вы обращаетесь к нему за помощью. Файл располагается в корневой директории проекта и содержит:
- описание целей и архитектуры проекта;
- предпочтительные технологии и фреймворки;
- стиль кода и соглашения об именовании;
- специфичные для проекта команды и утилиты;
- ограничения и запреты.
Официальная спецификация Anthropic рекомендует использовать CLAUDE.md для того, чтобы уменьшить количество повторяющихся вопросов и повысить качество ответов. В отличие от системных промптов, которые задаются один раз при старте сессии, CLAUDE.md загружается при каждом обращении к Claude Code, гарантируя, что советник всегда помнит контекст.
Как работает CLAUDE.md: технические детали
Согласно официальной документации Anthropic (доступной на docs.anthropic.com), CLAUDE.md обрабатывается в несколько этапов:
- Чтение файла — при инициализации сессии Claude Code автоматически ищет файл
CLAUDE.mdилиCLAUDE.md(регистр важен) в корне проекта. - Парсинг правил — советник разбивает содержимое на секции и извлекает ключевые инструкции.
- Применение в контексте — каждое последующее обращение к AI включает содержимое файла как часть системного промпта.
- Приоритетность — если в проекте несколько файлов с правилами (например,
.claude.mdиCLAUDE.md), приоритет имеет последний по алфавиту.
Разработчики из сообщества отмечают: «Claude Code каждый раз напоминает о сути проекта, если не описать её в CLAUDE.md». Это особенно критично для больших проектов с разрозненной архитектурой.
Пошаговая инструкция по созданию эффективного CLAUDE.md
Шаг 1. Определите цель проекта
Начните с краткого, но ёмкого описания проекта. Не пишите «Это веб-приложение» — укажите конкретную бизнес-логику.
Пример:
# Проект: Система управления заказами для сети ресторанов
## Цель
Автоматизация процесса приёма, обработки и доставки заказов через веб-интерфейс и мобильное приложение.
## Ключевые требования
- Поддержка 1000 одновременных пользователей.
- Время ответа API не более 200 мс.
- Интеграция с платёжными шлюзами Stripe и PayPal.
Шаг 2. Опишите архитектуру и стек технологий
Укажите, какие технологии используются и в каких контекстах. Это поможет AI избегать неподходящих предложений.
Пример:
## Технологический стек
- **Бэкенд**: Python 3.12, FastAPI, SQLAlchemy, PostgreSQL 16.
- **Фронтенд**: React 18, TypeScript, Tailwind CSS.
- **Инфраструктура**: Docker, Kubernetes, AWS (EC2, RDS, S3).
- **Тестирование**: Pytest, Playwright, Locust.
## Архитектура
Микросервисная архитектура с API Gateway (Kong) и очередью сообщений (RabbitMQ).
Шаг 3. Задайте стиль кода и соглашения
Claude Code может генерировать код, который не соответствует вашему стилю. Чтобы этого избежать, пропишите правила.
Пример:
## Стиль кода
- Используйте PEP 8 для Python.
- Для JavaScript — Prettier с настройками из .prettierrc.
- Именование переменных: snake_case для Python, camelCase для TypeScript.
- Длина строки: не более 100 символов.
- Комментарии: только для сложной логики, избегайте очевидных комментариев.
Шаг 4. Укажите запреты и ограничения
Это ключевой раздел. Чётко опишите, чего AI не должен делать.
Пример:
## Запреты
- НЕ используйте сторонние библиотеки без согласования.
- НЕ изменяйте файлы конфигурации (docker-compose.yml, .env).
- НЕ предлагайте переписывать архитектуру с нуля.
- НЕ используйте устаревшие версии библиотек (см. requirements.txt).
Шаг 5. Добавьте примеры и шаблоны
Чем больше контекста, тем точнее будут ответы. Включите примеры кода, которые AI должен использовать как образец.
Пример:
## Примеры кода
### Создание эндпоинта (Python/FastAPI)
```python
from fastapi import APIRouter, HTTPException
router = APIRouter(prefix="/orders", tags=["orders"])
@router.get("/{order_id}")
async def get_order(order_id: int):
"""Получить заказ по ID."""
order = await db.get_order(order_id)
if not order:
raise HTTPException(status_code=404, detail="Order not found")
return order
Обработка ошибок
- Возвращайте структурированные ошибки с кодом и сообщением.
- Используйте кастомные исключения (например, OrderNotFoundError).
### Шаг 6. Определите поведение при генерации
Укажите, как AI должен реагировать на разные типы запросов.
**Пример:**
```markdown
## Поведение советника
- При запросе на рефакторинг: сначала опиши изменения, затем предложи код.
- При генерации тестов: покрывай краевые случаи (пустые данные, ошибки валидации).
- При предложении новой функциональности: обоснуй, как это вписывается в текущую архитектуру.
Практические советы от сообщества
Разработчики, активно использующие Claude Code, делятся несколькими лайфхаками, которые значительно улучшают работу с CLAUDE.md.
Используйте YAML-секции для структурирования
Хотя файл называется .md, вы можете вставлять YAML-блоки для чёткого разделения правил.
---
version: "1.0"
author: "Команда разработки"
last_updated: 2026-07-14
---
Добавьте ссылки на документацию
Если в проекте есть внутренняя вики или Confluence, укажите ссылки. Claude Code может их прочитать и использовать для ответов.
Регулярно обновляйте файл
По мере развития проекта меняйте CLAUDE.md. Разработчики рекомендуют пересматривать его каждые 2–3 спринта.
Тестируйте на типовых запросах
Создайте несколько тестовых промптов (например, «Напиши эндпоинт для создания пользователя») и проверьте, соответствует ли ответ вашим правилам. Если нет — скорректируйте файл.
Пример полного CLAUDE.md
Вот пример, который можно взять за основу:
# CLAUDE.md — Конфигурация советника для проекта OrderFlow
## Цель проекта
Система управления заказами для сети из 50 ресторанов. Основная задача — автоматизация приёма заказов и их распределение по кухням.
## Технологический стек
- **Бэкенд**: Python 3.12, FastAPI, SQLAlchemy, PostgreSQL 16.
- **Фронтенд**: React 18, TypeScript, Tailwind CSS.
- **Инфраструктура**: Docker, Kubernetes, AWS.
## Стиль кода
- PEP 8 для Python.
- Prettier для JavaScript/TypeScript.
- Длина строки: 100 символов.
- Комментарии только для сложной логики.
## Запреты
- Не использовать сторонние библиотеки без согласования.
- Не изменять docker-compose.yml, .env, kubernetes/*.yaml.
- Не предлагать миграцию на другой язык или фреймворк.
## Примеры
- Эндпоинты: см. /app/routers/orders.py.
- Модели: см. /app/models/order.py.
- Тесты: см. /tests/test_orders.py.
## Поведение
- При генерации кода: следуй существующим шаблонам.
- При рефакторинге: сначала опиши план, затем изменения.
- При ошибках: предлагай исправление с пояснением.
Как избежать типичных ошибок
Разработчики, которые только начинают использовать CLAUDE.md, часто допускают несколько ошибок:
- Слишком общие формулировки — «следуй лучшим практикам» не даёт конкретики. Указывайте чёткие правила.
- Отсутствие примеров — AI лучше понимает на примерах, чем на абстрактных инструкциях.
- Игнорирование обновлений — если проект изменился, а CLAUDE.md остался прежним, советник будет давать устаревшие советы.
- Перегруженность — слишком длинный файл (более 200 строк) может снизить производительность советника.
Заключение
CLAUDE.md — это не просто технический файл, а мост между вашим проектом и AI-советником. Правильно составленный документ избавляет от лишних напоминаний, ускоряет разработку и повышает качество кода. Как отмечают авторы оригинальной статьи на Habr, «Claude Code каждый раз напоминает о сути проекта, если не описать её в CLAUDE.md». Используйте приведённые рекомендации, адаптируйте их под свой проект и забудьте о повторяющихся вопросах.
Комментарии