# Полное руководство Claude Code

Это руководство поможет вам освоить **Claude Code** — самый мощный AI-ассистент для программирования в 2026 году.

---

## 1. Что такое Claude Code

### Это не автодополнение кода, а агентный помощник

Claude Code — официальный CLI-инструмент Anthropic, **агентный помощник для программирования** (Agentic Coding Assistant). В отличие от классических средств автодополнения (например, GitHub Copilot), он работает как опытный разработчик:

- **Сам разбирается в задаче**: вы описываете требование, он составляет план работ
- **Работает с кодом напрямую**: читает, редактирует и создаёт любые файлы проекта
- **Выполняет команды в терминале**: запускает тесты, ставит зависимости, собирает проект
- **Глубоко понимает проект**: по умолчанию окно контекста на 200 тыс. токенов (`claude-opus-5` / `claude-sonnet-5` и другие расширяются до 1 млн)
- **Запускает субагентов**: делит сложную задачу между несколькими специализированными субагентами и обрабатывает их параллельно

### Кто им пользуется

С момента выпуска в мае 2025 года Claude Code стал основным инструментом разработки в ведущих мировых компаниях — среди них Netflix, Spotify, KPMG, L'Oréal и Salesforce. Отметки в 1 млрд долларов годовой выручки он достиг всего за 6 месяцев.

### Ключевые обновления 2025–2026

| Обновление | Описание |
|------|------|
| **Plan Mode** | Сначала анализ и исследование, потом план — меньше ошибок |
| **Agent Teams** | Параллельная работа нескольких агентов с изоляцией через git worktree |
| **Voice Mode** | Голосовой ввод: удерживайте пробел и говорите |
| **Computer Use** | Управление рабочим столом, браузером и инструментами разработки |
| **Система Hooks** | 17 событий жизненного цикла для автоматизации рабочих процессов |
| **Протокол MCP** | Подключение внешних инструментов и сервисов |
| **Skills** | Модули знаний — переиспользуемые шаблоны рабочих процессов |
| **Extended Thinking** | Для сложных задач сначала выполняется глубокое внутреннее рассуждение |
| **Opus 5 / Sonnet 5** | Текущий флагман и модель по умолчанию (4.8 / 4.6 остаются в продаже) |
| **1M Context Beta** | `claude-sonnet-5` / `claude-opus-5` и другие поддерживают контекст на 1 млн токенов |

### Зачем использовать через QCode.cc

При прямом использовании Claude Code из материкового Китая возникают две проблемы: сеть недоступна и стоимость высока. Через QCode.cc:

- **Низкая задержка на азиатских узлах**, без VPN и собственных прокси
- **Экономия до 80%** по сравнению с официальными ценами
- **Claude Code и Codex делят одну квоту тарифа** — один тариф на два инструмента
- **Высокая доступность за счёт нескольких узлов** (HK / Северная Америка / Европа / глобальный Route 53)

---

## 2. Установка и настройка

### Системные требования

| Требование | Описание |
|------|------|
| ОС | macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2) |
| Node.js | 18.0 или новее (рекомендуется 22 LTS) |
| Git | 2.x или новее |
| Место на диске | около 200 МБ |

### Установка Claude Code

```bash
# Установка через npm (рекомендуется)
npm install -g @anthropic-ai/claude-code

# Для пользователей из Китая — ускорение через зеркало Taobao
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

### Настройка QCode.cc

Задайте переменные окружения в терминале:

```bash
# Добавьте в ~/.bashrc или ~/.zshrc
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
export ANTHROPIC_AUTH_TOKEN=cr_ваш_API_ключ
```

> **Почему `ANTHROPIC_AUTH_TOKEN`, а не `ANTHROPIC_API_KEY`**: ключ QCode.cc, начинающийся с `cr_`, — это **ключ стороннего шлюза**, а не официальный ключ Anthropic. Увидев `ANTHROPIC_AUTH_TOKEN`, Claude Code отправит его шлюзу в заголовке `Authorization: Bearer <token>`. С `ANTHROPIC_API_KEY` он отправит `x-api-key`, что может конфликтовать с OAuth уже выполненного входа в аккаунт Anthropic. **Использование `ANTHROPIC_AUTH_TOKEN` — официальная рекомендация QCode**.

> **API-ключ** можно получить в [консоли QCode.cc](https://qcode.cc/dashboard); он начинается с `cr_`.

> **Выбор точки входа**: по умолчанию `https://api.qcode.cc/api` (глобальный Route 53 сам выбирает ближайший узел). Пользователям из материкового Китая рекомендуется `asia.qcode.cc` (азиатский узел, ближайший из HK/JP, минимальная задержка). Остальные домены (`us` / `eu` / `asia`) и правила BASE_URL описаны в [Эндпоинты и форматы API](/docs/getting-started/endpoints-and-api-paths).

Примените настройки:

```bash
source ~/.bashrc  # или source ~/.zshrc
```

### Проверка установки

```bash
# Версия
claude --version
# Должен вывести номер версии (зависит от вашей установки, см. https://github.com/anthropics/claude-code/releases)

# Быстрая проверка
claude -p "Привет, расскажи о себе"
```

Если Claude ответил, установка и настройка прошли успешно.

### Автодополнение в shell (необязательно)

```bash
# Bash
claude completion bash >> ~/.bashrc

# Zsh
claude completion zsh >> ~/.zshrc

# Fish
claude completion fish > ~/.config/fish/completions/claude.fish
```

---

## 3. Первое использование

### Запуск

Выполните в любом каталоге проекта:

```bash
cd ~/my-project
claude
```

Claude Code автоматически просканирует структуру проекта и перейдёт в интерактивный режим.

### Как читать интерфейс

```text
╭─────────────────────────────────────────╮
│ claude                                   │
│                                          │
│ Проект: my-project                       │
│ Модель: claude-sonnet-5                  │
│ Контекст: 12,345 / 1,000,000 tokens      │
╰─────────────────────────────────────────╯

> _
```

Можно писать обычным языком — Claude поймёт и выполнит.

### Первая задача: разобраться в проекте

```text
> Проанализируй архитектуру этого проекта: какие основные модули и как они связаны
```

Claude автоматически:
1. Прочитает `package.json`, `README.md` и структуру каталогов
2. Просмотрит ключевые исходные файлы
3. Выдаст структурированный разбор архитектуры

### Подтверждение прав

Когда Claude собирается что-то выполнить, он запрашивает подтверждение:

```text
Claude хочет выполнить:
  Инструмент: Bash
  Команда: npm test

  [y] разрешить  [n] отклонить  [a] всегда разрешать в этой сессии
```

- **y**: разрешить один раз
- **n**: отклонить
- **a**: разрешать такие операции до конца сессии (удобно для повседневной разработки)

### Основные режимы прав

| Режим | Описание | Когда применять |
|------|------|---------|
| По умолчанию | Подтверждение на каждую операцию | Первое знакомство, чувствительные проекты |
| `--allowedTools` | Указать разрешённые инструменты | Автоматизация с ограниченной областью |
| `--dangerously-skip-permissions` | Пропускать все подтверждения | Изолированное окружение Docker, CI/CD |

---

## 4. Основные функции

### 4.1 Plan Mode (режим планирования)

В Plan Mode Claude сначала анализирует и исследует, а уже потом составляет план — это удобно для сложных задач.

```bash
# Войти в режим планирования
> /plan

# Либо задать это прямо в запросе
> Сначала проанализируй требования и составь план, код пока не меняй
```

**Как это работает**:
1. Claude анализирует кодовую базу и требования
2. Предлагает план (какие файлы создать/изменить, в каком порядке)
3. Вы проверяете план и вносите правки
4. После подтверждения Claude выполняет его

**Пример**:

```text
> /plan
> Хочу добавить в проект аутентификацию пользователей на JWT

Claude: Анализирую текущую структуру проекта и составляю план...

📋 План работ:
1. Создать src/middleware/auth.ts — middleware проверки JWT
2. Создать src/services/auth-service.ts — бизнес-логика аутентификации
3. Изменить src/routes/index.ts — добавить маршруты входа и регистрации
4. Создать src/models/user.ts — модель данных пользователя
5. Добавить зависимости: jsonwebtoken, bcrypt
6. Создать файлы тестов

План подходит? Нужны ли правки?
```

### 4.2 Extended Thinking (расширенное рассуждение)

В Opus 5 (а также в доступных 4.8 / 4.7) встроено расширенное рассуждение (рекомендуется использовать adaptive thinking вместе с параметром effort, подробнее — [Руководство по настройке Adaptive Thinking](/docs/usage/adaptive-thinking)): перед сложными задачами модель сначала глубоко рассуждает внутри себя.

```text
> Этот баг с конкурентностью я ловлю уже два дня. Разберись с гонкой в src/worker.ts

[Claude выполняет внутреннее рассуждение на тысячи токенов, разбирая пути выполнения, механизмы блокировок и тайминги]

Claude: Нашёл проблему. В worker.ts на строке 127...
```

**Когда срабатывает автоматически**:
- Сложная отладка
- Анализ уровня архитектуры
- Многошаговые цепочки рассуждений

### 4.3 Субагенты (Sub-agents)

Claude может порождать специализированных субагентов под конкретные задачи:

```text
> Сделай ревью этого PR и заодно проверь на уязвимости

Claude: Запускаю двух субагентов параллельно:
  - Субагент 1: ревью качества кода
  - Субагент 2: сканирование уязвимостей
```

Субагенты работают в отдельном контексте и не засоряют основную сессию.

### 4.4 Шпаргалка по командам

| Команда | Назначение | Пример |
|------|------|------|
| `/model` | Переключить модель | `/model opus` |
| `/plan` | Войти в режим планирования | `/plan` |
| `/compact` | Сжать контекст | `/compact` |
| `/cost` | Посмотреть текущие расходы | `/cost` |
| `/clear` | Очистить контекст | `/clear` |
| `/init` | Сгенерировать CLAUDE.md | `/init` |
| `/review` | Ревью кода | `/review` |
| `/help` | Справка | `/help` |
| `Esc` | Отменить текущую операцию | |
| `Ctrl+C` | Прервать ответ | |

### 4.5 Управление контекстом

Окно контекста Claude Code — 200K токенов. В длинных сессиях им нужно управлять:

```bash
# Посмотреть текущий расход контекста
/cost

# Сжать контекст (сохранить главное, освободить место)
/compact

# Начать полностью новую сессию
/clear
```

**Рекомендации**:
- Когда расход контекста превышает 70%, выполняйте `/compact`
- Между разными задачами начинайте новую сессию через `/clear`
- В сложных проектах держите справочную информацию в CLAUDE.md (её `/compact` не удаляет)

---

## 5. CLAUDE.md — как объяснить Claude ваш проект

### Зачем нужен CLAUDE.md

При каждом запуске Claude Code автоматически читает `CLAUDE.md` в проекте и узнаёт архитектуру, правила оформления кода и принятые договорённости. Без него придётся каждый раз заново объяснять контекст проекта.

### Быстрое создание

```bash
# Claude сам проанализирует проект и сгенерирует файл
/init
```

### Уровни файла

| Расположение | Область действия | Git |
|------|---------|---------|
| `~/.claude/CLAUDE.md` | Глобально (все проекты) | Не включать |
| `корень проекта/CLAUDE.md` | Этот проект | Коммитить в Git |
| `.claude/CLAUDE.md` | Этот проект (личный) | Добавить в .gitignore |
| `подкаталог/CLAUDE.md` | Только этот подкаталог | По необходимости |

### Практический шаблон: проект React + TypeScript

```markdown
# MyApp

## Технологический стек
- React 19 + TypeScript 5.x + Vite
- Стили: Tailwind CSS v4
- Управление состоянием: Zustand
- Тесты: Vitest + Testing Library

## Частые команды
- Разработка: `pnpm dev`
- Тесты: `pnpm test`
- Сборка: `pnpm build`
- Lint: `pnpm lint`

## Правила кода
- Компоненты писать функциональными, Props описывать через interface
- Тип any запрещён
- CSS — только utility-классы Tailwind
- Формат коммитов: feat: / fix: / docs:

## Структура проекта
- src/components/ — переиспользуемые компоненты
- src/pages/ — компоненты страниц
- src/hooks/ — собственные хуки
- src/lib/ — вспомогательные функции
- src/api/ — обёртки над API-запросами

## Примечания
- Node.js 22+, пакетный менеджер — pnpm
- Все запросы к API идут через src/api/client.ts
```

> Полное руководство по CLAUDE.md — [Конфигурация CLAUDE.md](/docs/usage/claude-md).

---

## 6. Практическое руководство по выбору модели

### Сравнение трёх моделей

Цены — снимок, снятый 2026-08-16 со страницы [qcode.cc/models](https://qcode.cc/models); **источником истины является она**. Модели 4.x остаются в продаже, просто больше не используются по умолчанию.

| Параметр | Opus 5 | Sonnet 5 | Haiku 4.5 |
|--------|----------|------------|-----------|
| **Позиционирование** | Текущий флагман | По умолчанию | Лёгкая и быстрая |
| **Способность рассуждать** | Очень высокая | Высокая | Средняя |
| **Качество кода** | Очень высокое | Высокое | Среднее |
| **Скорость ответа** | Медленнее | Средняя | Быстрая |
| **Контекст** | 1M / 128K | 1M / 128K | 200K |
| **Цена входа** | $5.00/M | $2.00/M | $1.00/M |
| **Цена выхода** | $25.00/M | $10.00/M | $5.00/M |

### Переключение модели

```bash
# Переключение в интерактивном режиме
/model opus    # перейти на Opus
/model sonnet  # перейти на Sonnet
/model haiku   # перейти на Haiku

# Указание при запуске
claude --model claude-opus-5
```

### Рекомендации по сценариям

| Сценарий | Рекомендуемая модель | Почему |
|------|---------|------|
| Проектирование архитектуры | **Opus** | Глубокие рассуждения, видит картину целиком |
| Повседневная разработка | **Sonnet** | Лучшее соотношение цены и качества |
| Исправление багов | **Sonnet** | Достаточно и быстро |
| Сложная отладка | **Opus** | Extended Thinking |
| Форматирование кода | **Haiku** | Простые задачи — самой дешёвой моделью |
| Ревью PR | **Sonnet** | Баланс скорости и качества |
| Крупный рефакторинг | **Opus** | Нужно понимание всей картины |
| Написание документации | **Sonnet** | Достаточно |

### Смешанная стратегия (рекомендуется)

```text
Распределение моделей за день:
├── Sonnet 5 (70%) — повседневная разработка, багфиксы, тесты
├── Opus 5  (15%) — архитектурные решения, сложные задачи
└── Haiku 4.5 (15%) — форматирование, простые вопросы, массовые операции
```

Переключаться можно в любой момент диалога:

```bash
# Сначала строим план на Opus
/model opus
> Проанализируй архитектуру этого модуля и составь план рефакторинга

# После утверждения плана переходим на Sonnet и выполняем
/model sonnet
> Выполни первый шаг плана
```

---

## 7. Продвинутые приёмы

### Система Hooks

Автоматические хуки настраиваются в `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}
```

> Полное руководство — [Система Hooks](/docs/advanced/hooks).

### Серверы MCP

Подключение внешних инструментов по протоколу Model Context Protocol:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    }
  }
}
```

### Система Skills

Skills — это переиспользуемые модули знаний:

```bash
# Посмотреть доступные skills
/skills

# Использовать конкретный skill
> /commit    # сгенерировать коммит через commit skill
> /review    # проверить код через review skill
```

### Режим --bare

Вызов из скриптов без интерактивных возможностей:

```bash
claude --bare -p "Перечисли все комментарии TODO" --output-format json
```

---

## 8. Практические примеры

### Пример 1: разобраться в новом проекте

```bash
cd ~/unfamiliar-project
claude
```

```text
> Проанализируй этот проект:
> 1. какой технологический стек используется
> 2. основные модули и их зона ответственности
> 3. направление потоков данных
> 4. нарисуй простую схему архитектуры (ASCII)
```

Claude сам просмотрит package.json, каталоги с исходниками и файлы конфигурации и выдаст полную карту проекта.

### Пример 2: реализовать функцию через Plan Mode

```text
> /plan
> Нужно добавить в API ограничение частоты запросов. Требования:
> - не более 60 запросов в минуту на пользователя
> - счётчики хранить в Redis
> - при превышении возвращать 429 и заголовок Retry-After

Claude:
📋 План работ:
1. Установить зависимость: ioredis
2. Создать src/middleware/rate-limiter.ts
3. Создать src/config/rate-limit.ts (параметры)
4. Изменить src/app.ts (зарегистрировать middleware)
5. Создать tests/rate-limiter.test.ts
6. Обновить docker-compose.yml (добавить сервис Redis)

Подтвердите, и я приступаю.

> План подходит, выполняй
```

### Пример 3: отладка сложного бага

```text
/model opus
> Пользователи сообщают, что «при одновременных заказах остаток на складе иногда уходит в минус».
> Проанализируй src/services/order-service.ts и src/services/inventory-service.ts,
> найди баг с конкурентностью и исправь его.

[Opus включает Extended Thinking и разбирает пути выполнения, механизмы блокировок и уровни изоляции транзакций]

Claude: Нашёл проблему. В inventory-service.ts на строке 45 проверка остатка и его списание выполняются не в одной транзакции —
это состояние гонки типа TOCTOU. Исправление: использовать SELECT FOR UPDATE...
```

### Пример 4: массовый рефакторинг

```text
> Все class-компоненты в проекте нужно переписать на функциональные компоненты + Hooks.
> Обработай по очереди все файлы .tsx в src/components/.

Claude сделает следующее:
1. Найдёт все class-компоненты
2. По очереди преобразует их в функциональные
3. Переведёт методы жизненного цикла в useEffect
4. Переведёт this.state в useState
5. Запустит тесты и убедится, что ничего не сломано
```

### Пример 5: написать полный набор тестов

```text
> Напиши полный набор модульных тестов для src/services/user-service.ts:
> - покрыть все публичные методы
> - включить нормальные и исключительные сценарии
> - замокать внешние зависимости (базу данных, кэш)
> - целевое покрытие 90%+
```

### Пример 6: автоматизация в CI/CD

```bash
# Использование в GitHub Actions
claude -p "Проверь изменения кода в этом PR, обрати внимание на безопасность и производительность" \
  --output-format json \
  --max-turns 3 \
  --allowedTools Read,Glob,Grep
```

> Больше примеров для CI/CD — [Автоматизация и CI/CD](/docs/advanced/headless).

---

## 9. Совместное использование Claude Code и Codex

Claude Code и OpenAI Codex CLI — два самых мощных инструмента AI-разработки 2026 года, и у каждого свои сильные стороны.

**Лучшая связка**: Claude Code планирует и проверяет, Codex выполняет и делает массовые операции.

```bash
# 1. Claude Code составляет план
claude
> /plan
> Спроектируй план внедрения системы прав пользователей

# 2. Codex выполняет по плану
codex "По плану из PLAN.md реализуй шаги 1-3"
```

> **Один тариф QCode.cc, общая квота на два инструмента** — переключение ничего не стоит.
> Подробное сравнение — [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code).
> Руководство по Codex — [Полное руководство по Codex](/docs/ide/codex).

---

> **Работаете командой?** Для команд от 3 человек рекомендуем [корпоративный тариф](https://qcode.cc/enterprise) — отдельный домен `e-xxx.qcode.cc`, управление дочерними API Key, защита от блокировок, банковский перевод и счета. Подробнее — [Руководство по корпоративной версии](/docs/reference/enterprise-guide).

## 10. Частые вопросы

### Ошибка установки

**Q: `npm install -g` выдаёт ошибку прав доступа**

```bash
# Способ 1: через sudo
sudo npm install -g @anthropic-ai/claude-code

# Способ 2: управлять Node.js через nvm (рекомендуется)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
npm install -g @anthropic-ai/claude-code
```

### Проблемы с сетью

**Q: таймаут или отказ в соединении**

```bash
# Проверить корректность настроек
echo $ANTHROPIC_BASE_URL    # должно быть https://api.qcode.cc/api
echo $ANTHROPIC_AUTH_TOKEN  # должно начинаться с cr_

# Проверить доступность
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models
# → 200 + JSON-список моделей = адрес, ключ и сеть в порядке
```

### Контроль расходов

**Q: беспокоюсь, что выйдет дорого**

- Для повседневной работы используйте **Sonnet** (на 60% дешевле Opus)
- В любой момент смотрите расходы через `/cost`
- Сжимайте контекст через `/compact`, чтобы тратить меньше токенов
- Простые задачи отдавайте **Haiku** (самая дешёвая)
- См. [Руководство по оптимизации расходов](/docs/usage/cost-optimization)

### Claude не понимает проект

**Q: Claude постоянно неверно трактует структуру проекта или правила**

Создайте файл `CLAUDE.md` (см. главу 5) и запишите туда контекст проекта, правила и частые команды. Claude читает его автоматически при каждом запуске.

### Отличия от других инструментов

**Q: чем Claude Code отличается от Cursor / Copilot?**

| Инструмент | Тип | Особенности |
|------|------|------|
| **Claude Code** | CLI-агент | Самостоятельно планирует и выполняет, понимает проект целиком |
| **Cursor** | IDE | Глубокая интеграция с редактором, дополнение в реальном времени |
| **Copilot** | Плагин к IDE | Построчное дополнение, простые подсказки |

Claude Code — это помощник уровня агента (способен самостоятельно выполнять сложные задачи), а не инструмент построчного дополнения. Их можно совмещать: Cursor — для правок и дополнения в реальном времени, Claude Code — для планирования и выполнения сложных задач.

> **Примечание**: один и тот же ключ `cr_` от QCode.cc работает не только с Claude Code и Codex CLI, но и с множеством IDE / CLI / десктопных приложений, включая Cursor. Настройка Cursor (пользовательский Base URL + API Key) описана в [Подключении редактора Cursor](/docs/ide/cursor), матрица протоколов и полный список — в [Обзоре совместимости инструментов](/docs/ide/tool-compatibility).

---

## Связанные документы

- [Руководство по установке](/docs/getting-started/installation) — подробные шаги установки
- [Конфигурация CLAUDE.md](/docs/usage/claude-md) — полное руководство по настройке проекта
- [Система Hooks](/docs/advanced/hooks) — подробно про хуки автоматизации
- [Автоматизация и CI/CD](/docs/advanced/headless) — работа в headless-режиме
- [Руководство по выбору модели](/docs/usage/model-selection) — подробное сравнение моделей
- [Оптимизация расходов](/docs/usage/cost-optimization) — приёмы контроля затрат
- [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code) — сравнение двух инструментов
- [Полное руководство по Codex](/docs/ide/codex) — всё об использовании Codex
- [Тарифы и цены](https://qcode.cc/pricing) — тарифные планы QCode.cc