Best Practices для Claude Code

10 приёмов работы с Claude Code — от настройки до автоматизации

Базовый

Базовые вещи — с них стоит начать

Планирование: интервью → спецификация → код

Переведите Claude в Plan Mode (Shift+Tab дважды) и попросите задавать вам вопросы — про архитектуру, edge cases, трейдоффы, существующие паттерны. Результат зафиксируйте в SPEC.md. Затем откройте новую сессию: «Реализуй по SPEC.md». Когда планирование отделено от написания кода, результат предсказуем.

# Шаг 1: Plan Mode (Shift+Tab x2)
"Мне нужна система реферальных ссылок.
Задавай вопросы прежде чем планировать."

# Claude спрашивает:
- Какой процент комиссии?
- Реферал получает бонус при регистрации?
- Как обрабатывать самореферал?
- Нужна ли многоуровневая система?

# Шаг 2: Результат → SPEC.md

# Шаг 3: Новая сессия
"Реализуй систему рефералов по SPEC.md.
После каждого шага запускай pnpm test."

CLAUDE.md — трёхуровневая иерархия

CLAUDE.md работает как иерархия. Global (~/.claude/CLAUDE.md) — личные предпочтения для всех проектов. Project (./CLAUDE.md) — командные конвенции, коммитится в репозиторий. Subdirectory — правила для отдельных пакетов в монорепо. При этом CLAUDE.md — это подсказка, а hook — правило: инструкции из CLAUDE.md Claude может проигнорировать, хуки выполняются детерминированно.

# ~/.claude/CLAUDE.md (глобальный)
- Никаких fallback-ов, ошибки явные
- Минимум абстракций
- Всегда проверяй актуальные версии

# ./CLAUDE.md (проектный, в git)
## Команды
pnpm dev / build / test

## Архитектура
Monorepo: apps/web (Next.js), apps/api (Express)
packages/db (Prisma), packages/shared (types)

## Правила
- Переводы: en.json + ru.json всегда вместе
- API: Express 5, роуты в src/routes/

# apps/api/CLAUDE.md (поддиректория)
- Тесты: Jest + Supertest
- Миддлвары: userAuth, adminAuth

Тесты как механизм самокоррекции

Тесты замыкают цикл обратной связи: Claude пишет код, запускает тесты, видит ошибки, исправляет. Без тестов он не знает, что код не работает. Лучше всего работает TDD: сначала пишете тесты с ожидаемым поведением, затем просите Claude писать код, пока всё не пройдёт. По словам Boris Cherny — это «single biggest quality boost».

# TDD-подход

"Напиши тесты для калькулятора скидок:
- Процентная скидка 20% от 1000 = 800
- Фиксированная скидка 150 от 1000 = 850
- Скидка не может превышать цену
- Купон с лимитом использований

Потом реализуй calculateDiscount(),
пока все тесты не пройдут.
После каждого изменения: pnpm test"

# Claude сам итерирует:
# implement → test → fail → fix → test → pass

Промпты: «Что» и «Почему», не «Как»

В промпте укажите: что сделать, где в коде это находится, какие ограничения, как проверить результат. Пошаговые инструкции не нужны — опишите результат, а не путь. Ссылайтесь на существующие паттерны через @файл. Отдельно указывайте, чего делать не надо — Claude склонен к лишним абстракциям, ненужному рефакторингу и добавлению фич, о которых не просили.

# Плохой промпт
"Создай файл utils/validate.ts с функцией
validateEmail используя regex /^[a-z...$/"

# Хороший промпт
"Добавь валидацию email на форму регистрации.

Что: инлайн-валидация с ошибкой под полем
Где: @src/components/register-form.tsx
Паттерн: как в @src/components/login-form.tsx
Ограничения:
- НЕ создавай отдельный файл утилит
- НЕ добавляй валидацию других полей
- НЕ меняй существующие стили
Проверка: pnpm test && pnpm build"

Средний

Для тех, кто разобрался с основами

Управление контекстом: Document-and-Clear

Контекстное окно конечно, и за ним стоит следить. Document-and-Clear: попросите Claude записать текущее состояние работы в файл (что сделано, что осталось, ключевые решения), затем /clear, затем «прочитай STATUS.md и продолжи». Для /compact можно задать инструкцию: «Сохрани детали про систему оплаты, суммаризируй остальное». Ориентиры: до 50% контекста — работаете как обычно, 50–70% — пора делать /compact, больше 70% — /clear.

# Document-and-Clear Workflow

# Шаг 1: Сохрани прогресс
"Запиши в STATUS.md:
- Что сделано
- Что осталось
- Ключевые решения и почему
- Файлы которые были изменены"

# Шаг 2: Очистка
/clear

# Шаг 3: Продолжение
"Прочитай STATUS.md и продолжи
с того места, где остановился."

# /compact с инструкцией
/compact Сохрани детали про API эндпоинты
и схему БД, суммаризируй остальное.

Custom Slash Commands

Slash commands — markdown-файлы, которые работают как шаблоны промптов. .claude/commands/ — личные, .claude/commands/ в проекте — общие для команды. Поддерживаются $ARGUMENTS для параметров, @file для включения файлов, !`command` для bash. Примеры: /spec (спецификация фичи), /commit (коммит с осмысленным сообщением), /review (код-ревью), /catchup (что изменилось). Команды должны оставаться простыми шорткатами — не пытайтесь строить в них сложные workflow.

# .claude/commands/spec.md
Мне нужно реализовать: $ARGUMENTS

Задай 5-10 уточняющих вопросов прежде
чем предлагать план. Спроси про:
- Edge cases и ошибки
- Существующие паттерны в проекте
- Ограничения и трейдоффы

# .claude/commands/catchup.md
Проанализируй последние изменения:
!`git log --oneline -20`
!`git diff HEAD~5 --stat`

Кратко опиши: что изменилось, зачем,
и на что обратить внимание.

# Использование
> /spec система реферальных ссылок
> /catchup

Hooks — правила, которые нельзя обойти

Hooks — shell-команды, которые срабатывают на события инструментов Claude. Примеры: PostToolUse (Write|Edit) — запуск prettier после записи файла, PreToolUse (Bash git commit) — блокировка коммита, если тесты не прошли, Stop — проверка, что задача завершена. Exit code 2 блокирует выполнение инструмента — удобно для жёстких ограничений. Хуки считываются при старте сессии — после изменения нужен перезапуск Claude Code.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "command": "npx prettier --write $CLAUDE_FILE_PATH"
    }],
    "PreToolUse": [{
      "matcher": "Bash(git commit)",
      "command": "pnpm test || exit 2"
      // exit 2 = блокирует коммит
    }],
    "Stop": [{
      "matcher": "",
      "command": "echo 'Задача завершена'"
    }]
  }
}

# Exit codes:
# 0 — OK, продолжай
# 2 — БЛОК, не выполняй инструмент

Продвинутый

Для опытных пользователей и работы в команде

Параллелизация: Git Worktrees

Git worktree создаёт отдельную рабочую директорию с общей историей коммитов. В каждом worktree можно запустить свою сессию Claude Code под отдельную задачу. Полезный приём — выделить один worktree только под анализ: чтение логов, метрик, данных, без коммитов. Учитывайте, что node_modules не разделяется между worktree — pnpm install нужен в каждом. После слияния — очистка через git worktree remove.

# Создаём 3 параллельных worktree
git worktree add -b feat/api ../proj-api main
git worktree add -b feat/ui ../proj-ui main
git worktree add -b analysis ../proj-read main

# В каждом — отдельная сессия Claude
cd ../proj-api && pnpm install && claude
cd ../proj-ui && pnpm install && claude
cd ../proj-read && claude  # только чтение

# Cleanup после слияния
git worktree remove ../proj-api
git worktree remove ../proj-ui
git worktree remove ../proj-read
git worktree prune

Субагенты для исследований

При работе с большой кодовой базой Claude может запустить субагент — отдельный процесс с собственным контекстом. Результат возвращается в основную сессию краткой сводкой. Запустить можно явно: «исследуй через субагент». Чтобы снизить расход токенов, задайте CLAUDE_CODE_SUBAGENT_MODEL=haiku — субагенты переключатся на Haiku, а основная сессия останется на Opus/Sonnet.

# Явный запрос субагента
"Исследуй через субагент, как работает
система оплаты — какие сервисы, как
связаны, где обрабатываются вебхуки."

# Claude запускает Task(Explore):
# → читает десятки файлов
# → возвращает краткое саммари
# → основной контекст чистый

# Экономия токенов на исследованиях
export CLAUDE_CODE_SUBAGENT_MODEL=haiku

# Субагенты: haiku (быстро, дёшево)
# Основная сессия: opus (качество)

Statusline — контекст сессии на виду

Statusline — скрипт, вывод которого закреплён внизу терминала. Показывает заполненность контекста (цветная шкала: зелёный <70%, жёлтый 70–89%, красный 90+%), стоимость сессии, текущую ветку и количество изменений. Можно добавить интеграцию с трекером задач (Linear/Jira), метрики самооценки, длительность сессии.

# ~/.claude/statusline.sh
#!/bin/bash
BRANCH=$(git branch --show-current 2>/dev/null)
MOD=$(git diff --shortstat 2>/dev/null)

# Контекст (из переменных Claude Code)
PCT=${CLAUDE_CONTEXT_PERCENT:-0}
if [ "$PCT" -lt 70 ]; then
  BAR="\033[32m"   # зелёный
elif [ "$PCT" -lt 90 ]; then
  BAR="\033[33m"   # жёлтый
else
  BAR="\033[31m"   # красный
fi

echo -e "${BAR}${PCT}%\033[0m | $BRANCH $MOD"

# Расширяйте: добавьте стоимость сессии,
# Linear-задачу, eval-метрики, таймер