Руководство по настройке файла CLAUDE.md

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

Что такое CLAUDE.md

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

  • Определить специфичные для проекта стандарты кодирования
  • Установить технологические и фреймворковые ограничения
  • Определить стандарты качества кода
  • Стандартизировать рабочий процесс разработки
  • Зафиксировать архитектурные решения

Основной шаблон конфигурации

Базовая структура шаблона

# Название проекта

## Обзор проекта

[Краткое описание цели проекта, основных функций и целевых пользователей]

## Технологический стек

- Frontend: [Фреймворк и основные библиотеки]
- Backend: [Язык и фреймворк]
- База данных: [Тип базы данных]
- Развертывание: [Платформа развертывания]

## Структура проекта

\```
project/
├── src/ # Исходный код
├── tests/ # Тестовые файлы
├── docs/ # Документация
└── scripts/ # Скрипты
\```

## Правила разработки

[Специфичные для проекта стандарты кодирования]

## Примечания

[Специфичные для проекта примечания и ограничения]

Пример полной конфигурации

# CLAUDE.md - Файл конфигурации проекта

## Общие правила (обязательны для всех проектов)

### Язык общения

- Всегда использовать упрощенный китайский для размышлений и диалога
- Комментарии к коду на английском, документация на китайском

### Управление документацией

- Официальную документацию записывать в каталог `docs/`
- Обсуждения решений записывать в каталог `discuss/`
- README держать кратким, детальную документацию хранить отдельно

## Архитектурные стандарты кода

### Ограничения размера файлов

- Python/JavaScript/TypeScript: каждый файл не более 300 строк
- Java/Go/Rust: каждый файл не более 400 строк
- В каждой папке не более 8 файлов
- При превышении лимита требуется рефакторинг или разделение

### Показатели качества кода

Избегать следующих code smells:

1. **Жесткость**: Систему сложно изменить
2. **Избыточность**: Слишком много дублирующегося кода
3. **Циклические зависимости**: Модули зависят друг от друга
4. **Хрупкость**: Изменения вызывают цепные проблемы
5. **Непрозрачность**: Намерение кода неясно
6. **Комки данных**: Элементы данных всегда появляются вместе
7. **Избыточное проектирование**: Ненужная сложность

## Технологические ограничения

### Frontend технологии

- React 19+ (не использовать 18 или ниже)
- Next.js 15.4+ (не использовать 14 или ниже)
- Tailwind CSS v4 (не использовать v3)
- Приоритет TypeScript, избегать JavaScript
- Запрещено использовать CommonJS, только ES Modules

### Backend технологии

- Node.js 18+
- Использовать TypeScript
- Express/Fastify как Web фреймворк
- Prisma как ORM

### Python проекты

- Использовать uv для управления зависимостями (не pip/poetry/conda)
- Имя каталога виртуального окружения: `.venv`
- Строгая типизация, избегать использования dict
- Держать корневой каталог проекта чистым

## Рабочий процесс разработки

### Управление скриптами

- Все скрипты размещать в каталоге `scripts/`
- Использовать скрипты `.sh` для запуска/остановки
- Не использовать напрямую команды npm/pnpm/python
- Ошибки скриптов должны быть немедленно исправлены

### Управление логами

- Выводить логи из файла конфигурации
- Единообразный вывод в каталог `logs/`
- Включать временные метки и уровни логирования
- Логи ошибок хранить отдельно

### Требования к тестированию

- Покрытие unit-тестами > 80%
- Критичная функциональность должна иметь интеграционные тесты
- Тестовые файлы размещать в каталоге `tests/`
- Использовать CI/CD для автоматического запуска тестов

## Правила именования

### Именование файлов

- Компоненты: PascalCase (например, UserProfile.tsx)
- Утилитарные функции: camelCase (например, formatDate.ts)
- Файлы констант: UPPER_SNAKE_CASE (например, API_CONSTANTS.ts)
- Файлы стилей: kebab-case (например, user-profile.css)

### Именование переменных

- Переменные/функции: camelCase
- Константы: UPPER_SNAKE_CASE
- Классы/интерфейсы: PascalCase
- Приватные свойства: \_camelCase

## Git рабочий процесс

### Стратегия ветвления

- main: продакшн код
- develop: код среды разработки
- feature/\*: ветки функций
- hotfix/\*: ветки экстренных исправлений

### Правила коммитов

- feat: новая функциональность
- fix: исправление проблемы
- docs: обновление документации
- style: корректировка форматирования кода
- refactor: рефакторинг кода
- test: связанные с тестами
- chore: изменения сборки/инструментов

## Стандарты проектирования API

### Принципы RESTful

- GET: получение ресурса
- POST: создание ресурса
- PUT: обновление ресурса (полное)
- PATCH: обновление ресурса (частичное)
- DELETE: удаление ресурса

### Формат ответа

\```json
{
"success": true,
"data": {},
"message": "操作成功",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### Обработка ошибок

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误描述",
"details": {}
}
}
\```

## Стандарты безопасности

### Конфиденциальная информация

- Не жестко кодировать ключи в коде
- Использовать переменные окружения для управления конфигурацией
- Не коммитить файл `.env` в Git
- Регулярно обновлять пакеты зависимостей

### Валидация данных

- Валидация данных и на frontend, и на backend
- Использовать библиотеки валидации схем (например, zod)
- SQL запросы использовать с параметризацией
- Предотвращать XSS и CSRF атаки

## Оптимизация производительности

### Оптимизация Frontend

- Ленивая загрузка изображений
- Разделение кода
- Стратегия кэширования
- Виртуальная прокрутка (большие списки)

### Оптимизация Backend

- Оптимизация запросов к базе данных
- Использование кэша (Redis)
- Сжатие ответов API
- Контроль конкурентности

## Конфигурация развертывания

### Переменные окружения

- development: среда разработки
- staging: тестовая среда
- production: продакшн среда

### Контейнеризация

- Использовать Docker для развертывания
- Многоэтапная сборка для оптимизации размера образа
- Использовать docker-compose для оркестрации сервисов

## Мониторинг и логирование

### Метрики мониторинга

- Время ответа API
- Уровень ошибок
- Использование ресурсов
- Анализ поведения пользователей

### Уровни логирования

- ERROR: информация об ошибках
- WARN: предупреждающая информация
- INFO: общая информация
- DEBUG: отладочная информация

## Особые примечания

⚠️ **Важное напоминание**:

1. Немедленно указывать на обнаруженные проблемы в коде
2. При неуверенности проактивно спрашивать пользователя
3. Поддерживать чистоту и удобство сопровождения кода
4. Соблюдать установленные правила проекта

Специализированные шаблоны по типу проекта

Проекты React/Next.js

## Стандарты проектов React/Next.js

### Стандарты компонентов

- Использовать функциональные компоненты + Hooks
- Файл компонента с тем же именем, что и компонент
- Один файл - один компонент
- Props определять через TypeScript интерфейсы

### Управление состоянием

- Простое состояние: useState
- Сложное состояние: useReducer
- Глобальное состояние: Context API / Zustand
- Серверное состояние: TanStack Query

### Решение для стилей

- Tailwind CSS v4 как основа
- CSS Modules как дополнение
- Избегать встроенных стилей
- Приоритет адаптивного дизайна

### Оптимизация производительности

- Использовать React.memo для избежания лишних рендеров
- useMemo/useCallback для оптимизации вычислений
- Динамический импорт для разделения кода
- Изображения использовать через компонент next/image

Python проекты

## Стандарты Python проектов

### Структура проекта

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### Управление зависимостями

- Использовать uv для управления всеми зависимостями
- pyproject.toml определяет конфигурацию проекта
- requirements.txt для продакшн развертывания
- requirements-dev.txt для зависимостей разработки

### Аннотации типов

- Все функции должны иметь аннотации типов
- Использовать dataclass для определения структур данных
- Совместно с mypy проводить проверку типов
- Избегать использования типа Any

### Асинхронное программирование

- Приоритет async/await
- Использовать asyncio для управления конкурентностью
- Операции с БД через асинхронные драйверы
- HTTP запросы через httpx

Микросервисные проекты

## Стандарты архитектуры микросервисов

### Разделение сервисов

- Разделять сервисы по бизнес-доменам
- Каждый сервис развертывается независимо
- Сервисы общаются через API
- Общий код через управление пакетами

### API Gateway

- Единое управление входом
- Аутентификация и авторизация
- Rate limiting и circuit breaking
- Маршрутизация запросов

### Коммуникация сервисов

- HTTP/REST: синхронные вызовы
- Очереди сообщений: асинхронная коммуникация
- gRPC: высокопроизводительные сценарии
- WebSocket: коммуникация в реальном времени

### Управление данными

- Каждый сервис с независимой БД
- Избегать транзакций между сервисами
- Использовать event-driven для поддержания консистентности
- Реализовывать идемпотентные операции

Рекомендации по использованию

Инициализация конфигурации

Использовать команду /init для автоматической генерации базовой конфигурации:

> /init

Claude Code проанализирует структуру проекта и создаст начальный файл CLAUDE.md.

Постоянное обновление

По мере развития проекта постоянно обновлять файл конфигурации:

Записывать архитектурные решения

Фиксировать все важные технические решения

Обновлять технологический стек

Своевременно обновлять при изменении технологий

Совершенствовать стандарты

Своевременно дополнять стандарты при обнаружении проблем

Оптимизировать рабочий процесс

Оптимизировать процесс разработки на основе практики

Командное сотрудничество

Убедиться, что все члены команды понимают и соблюдают конфигурацию:

  • Новые сотрудники сначала читают CLAUDE.md
  • Регулярно проводить ревью и обновление конфигурации
  • Уведомлять всех об изменениях конфигурации
  • Поддерживать практичность конфигурации

Лучшие практики

DO - Рекомендуемые подходы

✅ Держать кратко и четко

  • Правила ясные, легко понятные
  • Избегать избыточной конфигурации
  • Выделять ключевые ограничения

✅ Синхронизировать с проектом

  • Конфигурация отражает реальную ситуацию
  • Своевременно обновлять устаревший контент
  • Удалять неприменимые правила

✅ Сосредоточиться на эффективности

  • Правила помогают повысить эффективность
  • Избегать формализма
  • Непрерывно улучшать на основе обратной связи

DON'T - Подходы, которых следует избегать

❌ Чрезмерные ограничения

  • Не устанавливать слишком строгие правила
  • Оставлять гибкость для разработки
  • Избегать подавления инноваций

❌ Отрыв от реальности

  • Не копировать конфигурацию других проектов
  • Правила должны соответствовать возможностям команды
  • Учитывать реальные потребности проекта

❌ Игнорирование обслуживания

  • Не настраивать один раз и никогда не обновлять
  • Регулярно проверять эффективность конфигурации
  • Своевременно очищать бесполезную конфигурацию

💡 Подсказка: CLAUDE.md — это "конституция" проекта, она определяет принципы поведения Claude Code в проекте. Правильная конфигурация может значительно повысить эффективность разработки и качество кода, но следует избегать бремени избыточной конфигурации. Всегда помните: конфигурация служит разработке, а не разработка служит конфигурации.

С ИИ — бесконечные инновации и безграничные возможности
О нас
Возможности
Документация
Тарифы
Связаться с нами