## Лучшие практики Этот документ объединяет обширный опыт, накопленный пользователями Claude Code в реальной разработке. Независимо от того, являетесь ли вы новичком, только начинающим использовать Claude Code, или опытным пользователем, желающим повысить эффективность — здесь вы найдёте ценные советы. Мы организовали материал в порядке от основ к продвинутым техникам. Рекомендуем сначала просмотреть всё целиком, а затем постепенно применять советы в повседневной работе. ## Лучшие практики инициализации проекта Хорошее начало — это половина успеха. Потратив 10 минут на правильную инициализацию проекта перед первым использованием Claude Code, вы сделаете каждое последующее взаимодействие более эффективным. ### Шаг первый: создание CLAUDE.md Это самый важный шаг. `CLAUDE.md` — это своего рода «руководство по проекту» для Claude. При каждом запуске Claude Code автоматически читает этот файл и понимает контекст вашего проекта. **Почему этот шаг так важен?** Без CLAUDE.md вам придётся многократно объяснять Claude одно и то же: ``` Вы: установи зависимости через pnpm Claude: хорошо, запускаю npm install... Вы: не npm, а pnpm! Claude: извините, запускаю pnpm install... ``` С CLAUDE.md эту базовую информацию нужно указать только один раз. **Пример шаблона CLAUDE.md:** ```markdown # Название моего проекта ## Обзор Это система управления интернет-магазином на основе Next.js 15, написанная на TypeScript. ## Стек технологий - Среда выполнения: Node.js 22 LTS - Фреймворк: Next.js 15 (App Router) - Стилизация: Tailwind CSS v4 - База данных: PostgreSQL 16 + Prisma ORM - Менеджер пакетов: pnpm 9 - Фреймворк для тестирования: Vitest + Playwright ## Часто используемые команды - Установка зависимостей: `pnpm install` - Сервер разработки: `pnpm dev` (порт 3000) - Запуск тестов: `pnpm test` - Проверка кода: `pnpm lint` - Миграция базы данных: `pnpm prisma migrate dev` - Сборка для продакшена: `pnpm build` ## Стандарты кодирования - Строгое использование TypeScript, запрет на `any` - React-компоненты пишутся функционально с хуками - Стили только через Tailwind, без inline style и CSS-файлов - Все API-маршруты возвращают единый формат: `{ success: boolean, data?: T, error?: string }` - Запросы к базе данных идут через service-слой, прямые вызовы Prisma в route запрещены - Формат сообщений коммитов: префиксы `feat:` / `fix:` / `docs:` / `refactor:` и т.д. ## Структура проекта - `src/app/` — страницы и API-маршруты (App Router) - `src/components/` — переиспользуемые UI-компоненты - `src/components/ui/` — базовые компоненты (Button, Input и т.д.) - `src/services/` — слой бизнес-логики - `src/lib/` — утилиты и конфигурация - `prisma/` — схема базы данных и файлы миграций ## Важные замечания - Не редактировать вручную файлы в `prisma/migrations/` - Переменные окружения настроены в `.env.local` (не коммитить в Git) - Промежуточное ПО для авторизации API находится в `src/middleware.ts` - Изображения хранятся в `public/images/`, загрузка через компонент next/image ``` **Использование /init для быстрой генерации:** Если не хотите писать вручную, можно использовать команду `/init` — Claude автоматически проанализирует проект и сгенерирует файл: ``` /init ``` Claude просканирует структуру проекта, package.json, конфигурационные файлы и автоматически сгенерирует CLAUDE.md. Затем вы вручную дополните то, что он мог упустить: командные соглашения и т.д. ### Шаг второй: настройка .claudeignore Аналогично `.gitignore`, файл `.claudeignore` указывает Claude, на какие файлы не нужно обращать внимание. Это не только ускоряет поиск, но и предотвращает отвлечение Claude на ненужные файлы. ```bash # .claudeignore # Директории с зависимостями node_modules/ vendor/ .venv/ # Результаты сборки dist/ build/ .next/ out/ # Большие файлы данных *.sql *.csv *.sqlite data/ # Бинарные и медиафайлы *.jpg *.png *.mp4 *.zip # Автогенерируемый код generated/ *.gen.ts prisma/migrations/ # Логи logs/ *.log ``` ### Шаг третий: описание структуры директорий в CLAUDE.md Этот шаг часто пропускают, но он очень эффективен. Когда Claude понимает структуру директорий, он знает, где искать файлы и где их создавать: ```markdown ## Структура проекта src/ ├── app/ # Next.js App Router │ ├── (auth)/ # страницы, требующие авторизации │ ├── (public)/ # публичные страницы │ └── api/ # API-маршруты ├── components/ │ ├── ui/ # базовые UI-компоненты (shadcn/ui) │ ├── forms/ # компоненты форм │ └── layouts/ # компоненты layout ├── services/ # бизнес-логика (один файл на модуль) ├── hooks/ # пользовательские React-хуки ├── lib/ # утилиты │ ├── auth.ts # авторизация │ ├── db.ts # подключение к базе данных │ └── validators.ts # определения Zod-схем └── types/ # определения типов TypeScript ``` ## Лучшие практики повседневного кодинга После правильной инициализации эти привычки в повседневном использовании помогут вам добиться большего с меньшими усилиями. ### Чётко описывайте задачи, а не давайте расплывчатые указания Это самый базовый и важный принцип. Claude — не телепат: чем яснее вы выражаетесь, тем лучше он выполняет работу. | Расплывчатое указание (низкая эффективность) | Чёткое описание (высокая эффективность) | |---|---| | «Исправь функцию входа» | «Добавь в src/app/api/auth/login/route.ts ограничение на количество неудачных попыток входа: при 5 неудачах с одного IP за 5 минут — блокировка на 15 минут, используй Redis для хранения счётчика»| | «Напиши компонент» | «Создай компонент UserAvatar в src/components/ui/. Принимает два props: name и imageUrl. Если изображение отсутствует — показывать первые буквы имени. Используй Tailwind rounded-full для круглой аватарки»| | «Тут баг, почини» | «Пользователи сообщают, что на странице списка товаров после перехода на другую страницу фильтры сбрасываются. Проверь логику пагинации в src/app/products/page.tsx, убедись что URL query params сохраняются при переключении страниц»| ### Активно используйте @ для указания контекста Когда вам нужно, чтобы Claude обратился к конкретному файлу, используйте символ `@` для прямой ссылки — это быстрее и точнее, чем заставлять его искать самостоятельно: ``` Посмотри @src/services/order-service.ts и @src/types/order.ts, затем добавь в order-service метод отмены заказа с проверкой статуса на возможность отмены. ``` **Способы использования @:** ```bash @src/services/auth.ts # ссылка на один файл @src/components/ # ссылка на всю директорию @package.json # ссылка на конфигурационный файл @https://nextjs.org/docs # ссылка на онлайн-документацию (содержимое будет извлечено) ``` > **Совет по экономии**: Активно используйте `@` для указания релевантных файлов — это дешевле, чем заставлять Claude искать по всему проекту. При поиске Claude читает большое количество файлов, что расходует дополнительные токены. ### Делайте одно дело за раз Избегайте перегрузки одного запроса большим количеством задач. Claude лучше всего справляется, когда сосредоточен на одной задаче: ``` # Не рекомендуется: слишком много всего за один раз "Добавь в модуль пользователя функцию загрузки аватара, заодно переделай стили на странице входа, и ещё добавь debounce к поисковому полю, и обнови шаблон письма для сброса пароля." # Рекомендуется: пошагово Шаг 1: "Добавь функцию загрузки аватара в компонент UserProfile, используя S3 для хранения" Шаг 2: "Обнови стили страницы входа, ориентируясь на макет дизайна в @docs/design-spec.md" Шаг 3: "Добавь debounce 300ms к поисковому полю, используя пользовательский хук" Шаг 4: "Обнови шаблон письма для сброса пароля, ориентируясь на стиль @src/templates/welcome.html" ``` ### Сначала дайте Claude прочитать, потом исправлять При работе с существующим кодом сначала дайте Claude понять код, а потом уже вносите изменения — это гораздо эффективнее прямого редактирования: ``` # Первый шаг: сначала понять "Прочитай @src/services/payment-service.ts, расскажи мне о текущей логике обработки платёжного потока, особенно об обработке ошибок и механизме повторных попыток. Не меняй код." # Второй шаг: потом планировать "На основе твоего понимания, я хочу добавить платёжный канал WeChat. Составь план изменений, перечисли что нужно модифицировать." # Третий шаг: выполнение изменений "План выглядит хорошо, начинай выполнение. Сначала измени payment-service.ts." ``` ### Используйте Plan Mode для сложных задач Для масштабных задач, затрагивающих множество файлов, используйте Plan Mode (переключение по `Shift+Tab`) — дайте Claude сначала составить план: ``` [Plan Mode] Мне нужно добавить в существующую систему RBAC (ролевая система контроля доступа). Сейчас есть только две роли пользователей: admin и user. Нужно поддержать кастомные роли и детальные права. Сначала проанализируй существующий код и составь подробный план реализации. ``` Claude сгенерирует пошаговый план, который вы утвердите, а затем переключитесь в обычный режим для выполнения. ### Используйте /clear и /compact Эти две команды — ключевые инструменты управления контекстом: ```bash /compact # сжать текущую историю диалога, сохранить ключевую информацию, освободить место в контексте /clear # полностью очистить историю диалога, начать с нуля # Когда использовать: # - переключение на совершенно другую задачу → /clear # - тот же проект, но диалог стал слишком длинным → /compact # - ощущаете, что ответы Claude стали хуже (контекст перегружен) → /compact # - только что закончили одну функцию, начинаете следующую → /clear ``` > **Важный принцип**: При смене темы обязательно сначала выполните `/clear`. Остатки старого контекста не только тратят token'ы, но и могут привести к тому, что ответы Claude будут вам мешать. ## Лучшие практики проверки кода Claude Code может не только писать код, но и помогать проверять его. ### Использование команды /review Быстрая проверка текущих изменений Git: ``` /review ``` Claude проверит все неcommitted изменения и укажет на потенциальные проблемы: - Логические ошибки и граничные случаи - Проблемы безопасности (SQL-инъекции, XSS и т.д.) - Проблемы производительности - Несоответствие стиля кода - Отсутствие обработки ошибок ### Попросите Claude написать тесты для проверки изменений После внесения изменений попросите Claude написать тесты для проверки: ``` Я только что изменил логику отмены заказа в @src/services/order-service.ts. Напиши юнит-тесты для этого метода, покрывая следующие сценарии: 1. Нормальная отмена заказа в статусе «ожидает отправки» 2. Попытка отменить уже отправленный заказ (должна завершиться неудачей) 3. Отмена несуществующего заказа 4. Параллельная отмена одного и того же заказа ``` ### Многораундовый рабочий процесс проверки Для важных изменений кода можно проводить многораундовую проверку: ``` # Первый раунд: общая проверка "Проверь последние изменения в @src/services/payment-service.ts, особое внимание — на безопасность и обработку ошибок." # После внесения изменений на основе отзывов, второй раунд: "Повторно проверь изменённый код, на этот раз уделяя особое внимание производительности и граничным случаям." # Третий раунд (опционально): сравнительная проверка "Сравни код до и после изменений, убедись, что все проблемы исправлены и не появилось новых." ``` ## Лучшие практики отладки Исправление багов — одна из сильных сторон Claude Code. Освоив правильные методы отладки, вы позволите Claude быстрее находить проблемы. ### Предоставляйте полный лог ошибки Не показывайте Claude только последнюю строку сообщения об ошибке — давайте полный контекст: ``` При запуске pnpm build возникла ошибка, полный лог: ``` Type error: Argument of type 'string | undefined' is not assignable to parameter of type 'string'. Type 'undefined' is not assignable to type 'string'. > 42 | const user = await getUser(session.userId) | ^^^^^^^ 43 | return NextResponse.json(user) ``` Ошибка возникает в @src/app/api/user/route.ts. Подозреваю проблему с определением типа session, помоги проверить. ``` ### Пошаговая отладка: сначала диагностика, потом исправление Не торопитесь просить Claude сразу исправить — сначала дайте ему провести диагностику: ``` # Первый шаг: диагностика "Пользователи сообщают, что после входа иногда происходит redirect на страницу 404. Проверь @src/middleware.ts и @src/app/(auth)/layout.tsx, проанализируй возможные причины этой проблемы. Не меняй код." # Второй шаг: подтверждение причины и исправление "Твой анализ имеет смысл, действительно проблема в логике перенаправления при истечении session. Исправь эту проблему и заодно добавь подходящее логирование ошибок для дальнейшей отладки." ``` ### Используйте скриншоты Claude Code умеет читать скриншоты, что особенно полезно для UI-багов: ``` Посмотри на этот скриншот @screenshot.png, текст в последнем столбце таблицы обрезается. Проверь стили в @src/components/DataTable.tsx и исправь проблему. ``` В терминале можно просто перетащить изображение в область ввода Claude Code — он автоматически его обработает. ## Лучшие практики Git-рабочего процесса Claude Code глубоко интегрирован с Git, правильное использование этих возможностей делает управление версиями проще. ### Использование /commit для автоматической генерации сообщений коммитов Claude проанализирует ваши изменения кода и автоматически сгенерирует стандартизированное сообщение коммита: ``` /commit ``` Сгенерированное сообщение коммита обычно включает: - Префикс типа изменения (feat, fix, refactor и т.д.) - Краткое описание изменений - Область влияния Если автоматически сгенерированное сообщение вас не устраивает, можно попросить изменить: ``` /commit # Сгенерированное сообщение недостаточно хорошее? "Сделай сообщение коммита более подробным, объясни почему эта логика была изменена" ``` ### Рабочий процесс с функциональными ветками + PR Рекомендуемый рабочий процесс: ```bash # 1. Создать функциональную ветку git checkout -b feature/order-cancel # 2. Запустить Claude Code для разработки claude # 3. В процессе разработки делать небольшие коммиты > "Реализовать базовую логику отмены заказа" > /commit > "Добавить поле причины отмены и валидацию" > /commit > "Добавить юнит-тесты для отмены заказа" > /commit # 4. Завершить разработку, создать PR > Создать Pull Request для текущей ветки, резюмировать все изменения из коммитов, сгенерировать стандартизированное описание PR ``` ### Избегайте прямых изменений в ветке main ``` # Добавьте это правило в CLAUDE.md: ## Git-стандарты - Все изменения должны выполняться в функциональных ветках, прямые изменения в main запрещены - Именование веток: feature/xxx, fix/xxx, refactor/xxx - Перед коммитом запускайте `pnpm lint && pnpm test` убедитесь, что всё в порядке ``` После добавления в CLAUDE.md, Claude будет автоматически соблюдать эти правила. Если вы случайно попросите его изменить код в ветке main, он напомнит сначала создать ветку. ## Лучшие практики командной работы При использовании Claude Code в команде единые соглашения делают совместную работу более гладкой. ### Совместное использование CLAUDE.md Добавьте CLAUDE.md в Git-репозиторий, чтобы все члены команды использовали единую конфигурацию проекта: ```bash # CLAUDE.md в корневой директории проекта → коммитится в Git git add CLAUDE.md git commit -m "docs: add CLAUDE.md project configuration" # Личные предпочтения → положить в .claude/CLAUDE.md, добавить в .gitignore echo ".claude/CLAUDE.md" >> .gitignore ``` **CLAUDE.md команды должен содержать:** - Стек технологий и архитектурное описание проекта - Стандарты кодинга и соглашения по именованию - Часто используемые команды и скрипты - Описание структуры директорий - Командные соглашения (стратегия ветвления, стандарты коммитов, процесс review) **Личный .claude/CLAUDE.md может содержать:** - Личные предпочтения в кодинге - Часто используемые сниппеты кода - Специфические настройки среды разработки ### Стандартизация PR Review Определите стандарты PR review в CLAUDE.md, чтобы Claude выполнял согласованную проверку: ```markdown ## Стандарты PR Review При проверке кода обращайте внимание на следующие аспекты: 1. **Функциональная корректность**: полностью ли реализованы требования 2. **Обработка ошибок**: покрыты ли исключительные ситуации 3. **Безопасность**: есть ли риски SQL-инъекций, XSS, обхода прав доступа 4. **Производительность**: есть ли ненужные запросы к базе данных, утечки памяти 5. **Покрытие тестами**: есть ли соответствующие тесты для нового кода 6. **Стиль кода**: соответствует ли стандартам проекта 7. **Документация**: есть ли JSDoc-комментарии для публичных API ``` ### Единообразие стиля кода Обеспечьте единый стиль кода через CLAUDE.md: ```markdown ## Стиль кода - Именование: компоненты — PascalCase, функции/переменные — camelCase, константы — UPPER_SNAKE_CASE - Имена файлов: файлы компонентов — PascalCase (например, UserAvatar.tsx), остальные — kebab-case - Порядок импортов: React → сторонние библиотеки → внутренние модули → типы → стили - Максимальное количество строк в функции: 50, если больше — разбить - Если у props компонента больше 3 свойств — использовать interface ``` ## Сводка продвинутых техник Вот несколько продвинутых техник, накопленных опытными пользователями: ### Пользовательские Slash-команды Создайте пользовательские шаблоны команд в директории `.claude/commands/`: ```bash # .claude/commands/review-security.md Проведите проверку следующего кода на безопасность, особенно обратите внимание на: 1. Риски SQL-инъекций 2. Поверхность атаки XSS 3. Защита от CSRF 4. Полнота проверки прав доступа 5. Шифрование чувствительных данных 6. Утечка чувствительной информации в логах Область проверки: $ARGUMENTS ``` Использование: ``` /review-security @src/app/api/ ``` ### Координация изменений в нескольких файлах Когда нужно одновременно изменить несколько файлов, дайте Claude чёткое общее представление: ``` Мне нужно добавить функцию купонов в систему заказов, затрагиваются следующие файлы: - @src/types/coupon.ts — создать, определение типов купонов - @src/services/coupon-service.ts — создать, бизнес-логика купонов - @src/services/order-service.ts — изменить, применение купона при расчёте - @src/app/api/coupons/route.ts — создать, API купонов - @prisma/schema.prisma — изменить, добавление модели Coupon Обрабатывайте файлы в указанном порядке, после завершения каждого файла сообщайте мне. ``` ### Использование Extended Thinking Для сложных архитектурных решений попросите Claude использовать расширенное мышление: ``` [Использование модели Opus] Я думаю о миграции текущего REST API на GraphQL. Проведи глубокий анализ преимуществ и недостатков, учитывая следующие факторы: 1. Стоимость миграции 50+ существующих API-эндпоинтов 2. Выгода от оптимизации запросов на фронтенде 3. Изменение стратегии кэширования 4. Кривая обучения команды 5. План интеграции с существующим React Query Код писать не нужно, предоставь мне подробный технический анализ. ``` ### Попросите Claude самостоятельно проверить Выработайте привычку просить Claude проверять свои собственные изменения: ``` После завершения изменений, пожалуйста: 1. Запусти pnpm lint чтобы проверить форматирование 2. Запусти pnpm test чтобы убедиться что существующие тесты не сломаны 3. Если есть ошибки типов — исправь их самостоятельно ``` ## Частые заблуждения В заключение, вот некоторые практики, которых следует избегать: | Заблуждение | Правильный подход | |------|---------| | Вставлять весь содержимое файла в диалог | Использовать `@file path` для ссылки | | Просить Claude сделать 5 дел за один запрос | Делать одно дело за раз, пошагово | | Расплывчато описывать требования | Указывать конкретные файлы, поведение, ожидаемый результат | | Не использовать CLAUDE.md | Потратить 10 минут на написание, сэкономить бесчисленное количество времени в будущем | | Никогда не использовать /clear или /compact | /clear при смене темы, /compact когда диалог слишком длинный | | Не давать Claude понять код перед изменениями | Сначала прочитать код, потом планировать, затем выполнять | | Использовать только Opus для всех задач | Повседневные задачи — Sonnet, сложные решения — Opus | | При ошибке повторять одну и ту же команду | Изменить подход, предоставить больше контекста | Освоение этих лучших практик требует времени. Рекомендуем начать с самых базовых пунктов: создать CLAUDE.md, чётко описывать требования, делать одно дело за раз. Эти три пункта уже значительно улучшат ваш опыт использования. По мере углубления опыта постепенно применяйте всё больше продвинутых техник.