CLAUDE.md: улучшение поведения Claude Code по Karpathy

Один файл CLAUDE.md собирает рекомендации Карпатова, делая Claude Code более предсказуемым, снижая ошибки и повышая продуктивность команды.

Зачем нужен CLAUDE.md

CLAUDE.md — это не просто файл с советами, а живой конфиг поведения AI-ассистента, который превращает его из «чудо-мага» в надежного коллеги. После 12 лет работы с серверами и контейнерами я видел, как разные инженеры по-разному «разговаривают» с Claude: кто-то пишет длинные запросы с десятком условий, а кто-то — по одному слову «починить». Результат — unpredictable output, куча правок и потеря времени. CLAUDE.md решает эту проблему, как Ansible-роль для конфигурации — задает рамки, но не убивает гибкость.

Проблемы текущего поведения Claude Code

Главная беда — отсутствие единых правил. Claude Code, как и любой AI, реагирует на запрос, но без структуры его ответы могут быть как удобными, так и совершенно непо полезны. Вот что ломает процесс:

Непредсказуемый формат ответа
Иногда Claude выдает готовый скрипт, иногда — просто список файлов, а иногда — текст в стиле «попробуйте так». В продакшене это опасно: один и тот же запрос требует разных действий.
```
bash
# Пример плохого запроса
"Как настроить Nginx для SSL?"
```
Это как попросить инженера починить сервер без указания, какой именно. Результат — трата времени на уточнения.
Разная глубина контекста
Claude может игнорировать часть запроса, если она «слишком длинная», или наоборот — тратить время на детали, которые не нужны. Как когда в Proxmox добавляешь ноду, а потом понимаешь, что забыл про сетевой мост.
Несогласованные стили вывода
Один раз Claude пишет ответ в виде пошаговой инструкции, другой — в виде списка команд без пояснений. Это как если бы в Nextcloud вы получали файлы в разных кодировках — несовместимость.
Отсутствие проверки на ошибки
Claude часто предлагает команды, которые не проверяют наличие зависимостей или правильность путей. Например, docker run без указания --rm или nginx -s reload без проверки статуса процесса.

Как CLAUDE.md улучшает предсказуемость

CLAUDE.md действует как конфиг для AI, задавая четкие правила поведения. Это как systemd: он не делает всё за вас, но гарантирует, что сервисы стартуют одинаково каждый раз.

Единый формат запроса
CLAUDE.md требует структурированного ввода: контекст → задача → ожидаемый результат. Это как в Ansible-playbook — вы указываете, что должно произойти, а не как это делать.

markdown
## Задача
Настроить Nginx для работы с SSL через Let's Encrypt

## Контекст
Есть сервер с Ubuntu 22.04, Nginx установлен, но SSL-сертификат отсутствует

## Ожидаемый результат
Nginx слушает порт 443, сертификат валиден, автоматический редирект с HTTP на HTTPS

Такой запрос нельзя игнорировать — структура обязывает AI понять, что именно нужно сделать.

Явные правила вывода
В CLAUDE.md прописаны форматы ответов: всегда начинайте с проверки окружения, затем шаги, затем проверка результата. Это как в Proxmox — сначала проверяешь статус ВМ, потом конфиг, потом перезапуск.

bash
# Пример правильного ответа по CLAUDE.md
1. Проверьте установленный пакет:
   docker ps | grep nginx

2. Сгенерируйте сертификат:
   docker run -it --rm -v $(pwd)/certs:/etc/letsencrypt certbot/certbot certonly --webroot -w /var/www/html -d example.com

3. Проверьте конфиг Nginx:
   nginx -t && systemctl reload nginx

Проверка на ошибки
CLAUDE.md требует, чтобы AI проверял каждую команду на ошибки и предлагал альтернативы. Например, если docker run не сработал — предложить проверить логи или права доступа.
Согласованность стиля
Все ответы должны быть в техническом стиле, без «надеюсь» и «попробуйте». Это как в наших конфигах — никаких «возможно, так будет работать», только конкретные действия.

Таким образом, CLAUDE.md превращает Claude Code из «черного ящика» в предсказуемый инструмент, который ведет себя как опытный инженер: системно, с проверками и без лишних слов. Серверы не падают, потому что конфиги пишутся с умом — и AI теперь работает по тем же правилам.

Ключевые принципы из наблюдений Карпатова

наблюдения Карпатова

Минимизация потери контекста

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

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

bash
# Пример: добавить весь каталог src в контекст
claude context add ./src
# Затем задать запрос, используя сохранённый контекст
claude code --context ./src "Опишите функцию calculate_total"

Если требуется сравнить версии, присылайте полные файлы, а не только фрагменты.
При работе с конфигурационными файлами (например, docker-compose.yml) включайте их полностью, иначе модель может не увидеть зависимостей между сервисами.

Чёткие инструкции и примеры

Недопустимо давать расплывчатые указания вроде «исправьте ошибку». Нужно конкретизировать проблему, показать место в коде и желаемый результат.

Неправильный пример

«Почините баг в функции».

Правильный пример

В файле app.py строка 42 генерирует KeyError при отсутствии ключа в словаре.
Добавьте проверку наличия ключа и обработайте исключение, возвращая сообщение «Key not found».

python
# Текущий код (проблемный)
def calculate_total(items):
    return sum(item['price'] for item in items)

# Исправленный код
def calculate_total(items):
    total = 0
    for item in items:
        price = item.get('price')
        if price is None:
            # Обрабатываем отсутствие ключа
            print("Key not found")
            continue
        total += price
    return total

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

yaml
# .claudeconfig.yaml
context:
  include:
    - "./src"
    - "./config"
  exclude:
    - "tests/*"
    - "*.log"

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

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

Практические рекомендации по CLAUDE.md

Формат запросов и примеры

При работе с Claude Code ключевое правило — чётко сформулированный запрос с указанием контекста. Не пишите «сделай это», а объясняйте, что именно нужно сделать и в каком окружении. Например:

bash
# Плохой запрос
 Claude, настрой сервер

# Хороший запрос с контекстом
 Claude, в текущей конфигурации Nginx (файл /etc/nginx/nginx.conf) добавь location-блок для проксирования запросов к API на порту 8080. Учти, что сервис работает в Docker-контейнере с именем "api-service", и нужно проверить, что порт 8080 не занят другими процессами.

Обратите внимание на структуру:

Указывайте конкретный файл или команду, которую нужно изменить
Описывайте текущую конфигурацию и желаемое состояние
Указывайте ограничения (порты, ограничения ресурсов, зависимости)

Пример для Docker Compose:

bash
# Плохой запрос
 Claude, настрой Docker Compose

# Хороший запрос
 Claude, в файле docker-compose.yml для сервиса "db" изменить образ с postgres:12 на postgres:14.11. Добавить healthcheck, который проверяет доступность порта 5432 каждые 30 секунд. Убедиться, что том для данных (/var/lib/postgresql/data) смounted с options noatime для повышения производительности.

Автоматическая проверка и валидация

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

Пример скрипта для проверки Nginx-конфигурации:

bash
#!/bin/bash
# check-nginx-config.sh

CONFIG_FILE="/etc/nginx/nginx.conf"
TEMP_FILE="/tmp/nginx-test.conf"

# Копируем конфиг в временный файл для проверки
cp "$CONFIG_FILE" "$TEMP_FILE"

# Проверяем синтаксис
nginx -t -c "$TEMP_FILE" || {
  echo "Ошибка в конфигурации Nginx: $!"
  exit 1
}

# Дополнительная проверка: ищем потенциально опасные директивы
if grep -q "server_name" "$TEMP_FILE" && ! grep -q "listen 80;" "$TEMP_FILE"; then
  echo "Внимание: server_name указан, но не слушает порт 80. Проверить корректность конфигурации."
fi

echo "Проверка конфигурации Nginx успешно завершена"

Такой скрипт можно интегрировать в workflow CI/CD или запускать вручную перед применением изменений через Claude Code. Это позволяет избежать ситуаций, когда конфигурация ломается из-за опечаток или несоответствия между описанием и реальной настройкой.

Для валидации Docker-компонов можно использовать:

bash
# validate-docker-compose.sh

COMPOSE_FILE="docker-compose.yml"

# Проверка синтаксиса
docker-compose -f "$COMPOSE_FILE" config --dry-run || {
  echo "Ошибка в docker-compose.yml: $!"
  exit 1
}

# Проверка доступности образов
docker pull $(grep image "$COMPOSE_FILE" | awk -F'[:]' '{print $2}' | sort -u) || {
  echo "Не удалось проверить доступность образов из docker-compose.yml"
  exit 1
}

echo "Валидация docker-compose.yml завершена успешно"

Эти практики помогут сделать работу с Claude Code более предсказуемой, снизить количество ошибок и повысить продуктивность команды, как и задумано в CLAUDE.md.

Интеграция в рабочий процесс

С точки зрения системного инженера, любой инструмент автоматизации — будь то Ansible или Claude Code — бесполезен, если он работает в вакууме. Чтобы Claude Code перестал быть просто «умным чатом» и превратился в полноценного участника процесса, его нужно встроить в существующий жизненный цикл разработки. Если мы просто дадим ИИ доступ к коду, мы получим хаос. Если же мы зададим правила игры через CLAUDE.md, мы получим предсказуемость.

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

Главная проблема при работе с AI-агентами — это риск того, что модель начнет предлагать решения, которые противоречат архитектуре вашего проекта. В больших репозиториях, где работают несколько человек, важно, чтобы Claude Code понимал не только синтаксис, но и контекст: как устроены тесты, как запускаются сборки и какие стандарты именования приняты в команде.

Файл CLAUDE.md должен выступать в роли «единого источника истины» (Single Source of Truth). Вместо того чтобы каждый раз объяснять модели, как запустить линтер, вы прописываете это один раз.

С практической точки зрения, я рекомендую добавить в файл четкие инструкции по командам сборки и тестирования. Например, если ваш проект использует make или npm, структура раздела должна выглядеть так:

markdown
## Build and Test Commands

- Build the project: `make build`
- Run all tests: `make test`
- Run a specific test file: `make test TEST_FILE=path/to/file_test.go`
- Linting: `make lint`
- Format code: `make fmt`

Когда Claude Code видит такие инструкции, он не гадает, какой флаг использовать для go test или pytest. Он просто берет готовую команду из вашего конфига. Это снижает вероятность того, что агент создаст лишний мусор в репозитории или, что хуже, применит некорректные параметры сборки.

Также важно синхронизировать модель с вашим Git-flow. Если вы используете строгие правила для коммитов (например, Conventional Commits), укажите это в CLAUDE.md. Тогда Claude будет генерировать сообщения, которые пройдут через ваш CI/CD без лишних правок.

Мониторинг и постоянное улучшение

Любая автоматизация требует обратной связи. В случае с Claude Code, «мониторинг» — это не графики в Grafana, а анализ того, насколько часто модель ошибается или отклоняется от заданных инструкций.

Если вы заметили, что Claude Code раз за разом делает одну и ту же ошибку (например, забывает обновить документацию при изменении API или использует устаревший метод в библиотеке), не пытайтесь исправлять это в каждом отдельном диалоге. Это путь к «решениям на коленке». Правильный подход — внести правку в CLAUDE.md.

Процесс улучшения можно представить как цикл:

Обнаружение: Вы или ваш коллега заметили, что модель предлагает неоптимальный код.
Анализ: Вы выясняете, почему это произошло (недостаток контекста, отсутствие правила).
Обновление: Вы добавляете новый блок в CLAUDE.md.
Проверка: Вы запускаете задачу заново и убеждаетесь, что поведение стало предсказуемым.

Пример добавления правила для предотвращения ошибок в конфигурациях:

markdown
## Coding Standards & Guardrails

- Always use absolute paths in Dockerfiles.
- When modifying PostgreSQL schemas, always include a migration script in `/migrations`.
- Do not use `any` in TypeScript; prefer explicit interfaces.
- All new environment variables must be added to `.env.example`.

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

Часто задаваемые вопросы

Нужно ли добавлять CLAUDE.md в .gitignore?

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

Поможет ли CLAUDE.md избежать ошибок в коде?

Файл не гарантирует стопроцентную точность, так как Claude всё ещё остается вероятностной моделью, но он значительно снижает риск «галлюцинаций». Задавая чёткие правила оформления и проверки команд, вы ограничиваете пространство для маневра нейросети, заставляя её придерживаться проверенных паттернов. Это похоже на использование строгого линтера: он не пишет код за вас, но не даёт совершить глупые синтаксические ошибки.

Можно ли использовать один CLAUDE.md для разных проектов?

Технически это возможно, но я рекомендую создавать специфичный файл для каждого проекта. В одном репозитории у вас может быть стек на Python и PostgreSQL, а в другом — Node.js и Redis, и правила работы с ними будут отличаться. Индивидуальный конфиг позволяет прописать специфические команды сборки, пути к логам и стандарты тестирования, которые актуальны именно для данной инфраструктуры.

Как понять, что правила в CLAUDE.md пора обновить?

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