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
### Стандарты компонентов
- Использовать функциональные компоненты + Hooks
- Файл компонента с тем же именем, что и компонент
- Один файл - один компонент
- Props определять через TypeScript интерфейсы
### Управление состоянием
- Простое состояние: useState
- Сложное состояние: useReducer
- Глобальное состояние: Context API / Zustand
- Серверное состояние: TanStack Query
### Решение для стилей
- Tailwind CSS v4 как основа
- CSS Modules как дополнение
- Избегать встроенных стилей
- Приоритет адаптивного дизайна
### Оптимизация производительности
- Использовать React.memo для избежания лишних рендеров
- useMemo/useCallback для оптимизации вычислений
- Динамический импорт для разделения кода
- Изображения использовать через компонент next/image
## Стандарты 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✅ Держать кратко и четко
✅ Синхронизировать с проектом
✅ Сосредоточиться на эффективности
❌ Чрезмерные ограничения
❌ Отрыв от реальности
❌ Игнорирование обслуживания
💡 Подсказка:
CLAUDE.md— это "конституция" проекта, она определяет принципы поведения Claude Code в проекте. Правильная конфигурация может значительно повысить эффективность разработки и качество кода, но следует избегать бремени избыточной конфигурации. Всегда помните: конфигурация служит разработке, а не разработка служит конфигурации.