Лучшие практики¶
Этот документ объединяет обширный опыт, накопленный пользователями 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:
# Название моего проекта
## Обзор
Это система управления интернет-магазином на основе 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 на ненужные файлы.
# .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 понимает структуру директорий, он знает, где искать файлы и где их создавать:
## Структура проекта
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 метод отмены заказа с проверкой статуса на возможность отмены.
Способы использования @:
@src/services/auth.ts # ссылка на один файл
@src/components/ # ссылка на всю директорию
@package.json # ссылка на конфигурационный файл
@https://nextjs.org/docs # ссылка на онлайн-документацию (содержимое будет извлечено)
Совет по экономии: Активно используйте
@для указания релевантных файлов — это дешевле, чем заставлять Claude искать по всему проекту. При поиске Claude читает большое количество файлов, что消耗额外的 token.
Делайте одно дело за раз¶
Избегайте перегрузки одного запроса большим количеством задач. 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¶
Эти две команды — ключевые инструменты управления контекстом:
/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¶
Рекомендуемый рабочий процесс:
# 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-репозиторий, чтобы все члены команды использовали единую конфигурацию проекта:
# 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 выполнял согласованную проверку:
## Стандарты PR Review
При проверке кода обращайте внимание на следующие аспекты:
1. **Функциональная корректность**: полностью ли реализованы требования
2. **Обработка ошибок**: покрыты ли исключительные ситуации
3. **Безопасность**: есть ли риски SQL-инъекций, XSS, обхода прав доступа
4. **Производительность**: есть ли ненужные запросы к базе данных, утечки памяти
5. **Покрытие тестами**: есть ли соответствующие тесты для нового кода
6. **Стиль кода**: соответствует ли стандартам проекта
7. **Документация**: есть ли JSDoc-комментарии для публичных API
Единообразие стиля кода¶
Обеспечьте统一代码风格 через CLAUDE.md:
## Стиль кода
- Именование: компоненты — PascalCase, функции/переменные — camelCase, константы — UPPER_SNAKE_CASE
- Имена файлов: файлы компонентов — PascalCase (например, UserAvatar.tsx), остальные — kebab-case
- Порядок импортов: React → сторонние библиотеки → внутренние модули → типы → стили
- Максимальное количество строк в функции: 50, если больше — разбить
- Если у props компонента больше 3 свойств — использовать interface
Сводка продвинутых техник¶
Вот несколько продвинутых техник, накопленных опытными пользователями:
Пользовательские Slash-команды¶
Создайте пользовательские шаблоны команд в директории .claude/commands/:
# .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, чётко описывать требования, делать одно дело за раз. Эти три пункта уже значительно улучшат ваш опыт использования. По мере углубления опыта постепенно применяйте 更多 продвинутых техник.