Принцип

Claude Code — CLI-инструмент для работы с кодом. Эффективное использование требует понимания контекста проекта и правильной формулировки задач.

Настройка проекта

CLAUDE.md

Файл CLAUDE.md в корне проекта содержит инструкции для Claude.

\# CLAUDE.md  
  
\#\# Проект  
FastAPI приложение для e-commerce.  
  
\#\# Команды  
- \`make dev\` — запуск dev сервера  
- \`make test\` — pytest  
- \`make lint\` — ruff + mypy  
  
\#\# Архитектура

src/ ├── api/ # FastAPI роуты ├── services/ # Бизнес-логика ├── repositories/ # Доступ к данным ├── models/ # SQLAlchemy модели └── schemas/ # Pydantic схемы

  
\#\# Стандарты  
- Python 3.11+  
- Type hints обязательны  
- Docstrings: Google style  
- Тесты: pytest, fixtures в conftest.py  
  
\#\# Паттерны  
- Dependency Injection через FastAPI Depends  
- Repository pattern для БД  
- Pydantic для валидации  
  
\#\# Не делать  
- Sync код в async контексте  
- Raw SQL (только SQLAlchemy ORM)  
- Any в type hints без обоснования

Навигация по проекту

Поиск кода

Пример 1: Поиск по функциональности  
"Найди где обрабатываются ошибки аутентификации.  
Формат: файл:строка — описание"  
  
Ожидаемый ответ:  
- src/api/auth.py:45 — HTTPException для невалидного токена  
- src/services/auth.py:78 — AuthenticationError при неверном пароле  
- src/middleware/auth.py:23 — перехват и обработка AuthenticationError  
  
Пример 2: Поиск зависимостей  
"Покажи все места, где используется UserRepository.  
Включи: импорты, инъекции, вызовы методов."  
  
Пример 3: Архитектурный обзор  
"Объясни data flow от HTTP запроса до БД для endpoint POST /orders.  
Покажи цепочку вызовов с файлами и строками."

Понимание кода

Пример 1: Объяснение функции  
"Объясни функцию в src/services/payment.py:process\_payment().  
Фокус:  
- Что делает каждый шаг  
- Какие побочные эффекты  
- Какие ошибки могут возникнуть"  
  
Пример 2: Связи между модулями  
"Как связаны модули auth и user?  
Покажи:  
- Общие зависимости  
- Точки взаимодействия  
- Направление зависимостей"  
  
Пример 3: История изменений  
"Какие изменения были в src/api/orders.py за последние 5 коммитов?  
Для каждого: что изменилось, зачем (из commit message)"

Редактирование кода

Точечные изменения

Пример 1: Изменение функции  
"Файл: src/utils/validators.py  
Функция: validate\_email (строка 34)  
  
Изменение: добавь проверку MX записи домена.  
Используй библиотеку dnspython.  
Сохрани существующую логику regex проверки."  
  
Пример 2: Добавление поля  
"Файл: src/models/user.py  
Модель: User  
  
Добавь поле: phone\_number (опциональное, string, max 20 символов)  
Обнови:  
- Модель  
- Схему UserCreate в src/schemas/user.py  
- Схему UserResponse"  
  
Пример 3: Рефакторинг  
"Файл: src/services/order.py  
Функция: process\_order (80 строк)  
  
Разбей на:  
- validate\_order\_items()  
- calculate\_totals()  
- apply\_discounts()  
- create\_order\_record()  
  
Сохрани текущее поведение.  
Добавь type hints."

Создание нового кода

Пример 1: Новый endpoint  
"Создай endpoint DELETE /users/\{user\_id\}  
  
Требования:  
- Проверка авторизации (текущий пользователь = user\_id или admin)  
- Soft delete (поле is\_deleted)  
- Возврат 204 No Content  
- Логирование действия  
  
Файлы для изменения:  
- src/api/users.py (endpoint)  
- src/services/user.py (метод delete)  
- src/repositories/user.py (метод soft\_delete)  
  
Стиль: как существующие endpoints в проекте."  
  
Пример 2: Новый сервис  
"Создай NotificationService.  
  
Методы:  
- send\_email(user\_id, template, context)  
- send\_push(user\_id, title, body)  
- send\_batch(user\_ids, notification)  
  
Требования:  
- Async  
- Retry при ошибках (3 попытки)  
- Логирование  
- Dependency injection ready  
  
Файл: src/services/notification.py"  
  
Пример 3: Миграция  
"Создай Alembic миграцию для новой таблицы notifications.  
  
Поля:  
- id (UUID, PK)  
- user\_id (FK -\> users.id)  
- type (enum: email, push, sms)  
- status (enum: pending, sent, failed)  
- payload (JSONB)  
- created\_at, sent\_at  
  
Индексы:  
- user\_id + status (для выборки pending)"

Тестирование

Запуск тестов

Пример 1: Конкретный тест  
"Запусти pytest tests/unit/test\_auth.py::test\_validate\_token -v  
При ошибке покажи:  
- Что ожидалось vs что получено  
- Стек вызовов  
- Предполагаемую причину"  
  
Пример 2: Coverage  
"Запусти pytest с coverage для модуля src/services/order.py  
Покажи непокрытые строки.  
Предложи тесты для покрытия."  
  
Пример 3: Отладка падающего теста  
"Тест tests/integration/test\_api.py::test\_create\_order падает.  
Запусти с -x --pdb.  
Найди причину и предложи исправление."

Написание тестов

"Файл: src/services/payment.py  
Функция: process\_refund(order\_id, amount, reason)  
  
Напиши тесты:  
  
1. Unit тесты:  
- Успешный refund  
- Refund больше суммы заказа (ошибка)  
- Заказ не найден  
- Заказ уже refunded  
  
2. Используй fixtures из conftest.py:  
- mock\_order  
- mock\_payment\_gateway  
  
3. Стиль: как существующие тесты в tests/unit/  
  
Файл: tests/unit/test\_payment.py"

Отладка

Пример 1: Анализ ошибки  
"Ошибка в production:

TypeError: 'NoneType' object is not subscriptable File 'src/services/order.py', line 145, in get_order_total return order'items'$$0$$'price'

  
Задачи:  
1. Найди функцию get\_order\_total  
2. Определи, когда order может быть None  
3. Предложи исправление с proper error handling"  
  
Пример 2: Performance issue  
"Endpoint GET /orders медленный (\>2s).  
Профилируй:  
1. Запусти с cProfile  
2. Найди bottleneck  
3. Предложи оптимизацию  
  
Вероятные причины:  
- N+1 queries  
- Отсутствие индексов  
- Избыточные данные"  
  
Пример 3: Memory leak  
"Сервис потребляет всё больше памяти.  
Диагностика:  
1. Добавь tracemalloc в подозрительные места  
2. Найди источник утечки  
3. Предложи исправление"

Git операции

Пример 1: Коммит  
"Сделай коммит изменений.  
Изменённые файлы: src/services/user.py, tests/unit/test\_user.py  
Что сделано: добавлен метод soft\_delete  
  
Формат commit message:  
feat(user): add soft delete functionality"  
  
Пример 2: PR  
"Создай PR для текущей ветки.  
База: main  
  
Содержимое PR:  
- Изменения в auth модуле  
- Новые тесты  
- Обновление документации  
  
Сгенерируй описание на основе коммитов."  
  
Пример 3: Code review  
"Проведи review PR \#123.  
Фокус:  
- Безопасность  
- Соответствие стандартам проекта  
- Покрытие тестами  
  
Формат: комментарии к конкретным строкам."

Команды и shortcuts

Best practices

Эффективные промпты

Хорошо:  
"Файл: src/api/users.py  
Строка 45: функция get\_user  
  
Добавь кэширование результата в Redis на 5 минут.  
Используй существующий redis\_client из src/core/redis.py"  
  
Плохо:  
"Добавь кэширование"  
(нет контекста: какой файл, какая функция, какой кэш)

Итеративная работа

1. "Покажи текущую реализацию функции X"  
2. "Какие есть проблемы с производительностью?"  
3. "Оптимизируй с учётом $конкретное требование$"  
4. "Добавь тесты для новой реализации"  
5. "Запусти тесты и убедись, что всё работает"

Контекст проекта

Полезно указывать:  
- Какие файлы уже прочитаны  
- Какие решения приняты ранее  
- Какие ограничения есть (версии, зависимости)  
- Какой стиль кода принят в проекте