Claude Code — это официальный интерфейс командной строки от Anthropic, способный читать исходный код, вносить правки, запускать команды и управлять git прямо в терминале через обычный диалог на естественном языке. Это не отдельное окно веб-чата, откуда код приходится копировать вручную, а полноценный автономный агент, работающий непосредственно внутри вашего проекта.

Данное руководство служит отправной точкой для уверенного старта с Claude Code. Материал структурирован по трём логическим модулям:

Модуль 1 — Установка и базовая конфигурация: установка CLI, аутентификация через API-ключ или OAuth, первый запуск и структура файлов настроек.
Модуль 2 — Рабочая сессия и взаимодействие: управление контекстом, горячие клавиши, слеш-команды, неинтерактивный режим и оптимизация токенов через /compact.
Модуль 3 — Безопасность и модель разрешений: настройка файлов settings.json, создание списков разрешений (allow) и запретов (deny) для системных команд.

Каждый модуль закрепляется практическим упражнением по созданию, доработке и финализации веб-компонента на Next.js.

1. Что такое Claude Code и системные требования

1.1. Что такое Claude Code и его отличия от веб-чата

Claude Code встраивается в повседневный процесс разработки в качестве терминального ассистента. В отличие от стандартного веб-чата, агент обладает инструментами прямого взаимодействия с системой:

Чтение и поиск: исследует файлы, выполняет регулярный поиск через grep и сканирует файловую структуру с помощью glob.
Точечная модификация кода: применяет аккуратные патчи к файлам без необходимости полной перезаписи больших модулей.
Выполнение системных команд: запускает тесты, сборщики, линтеры и команды git с автоматическим анализом кодов завершения и ошибок.

1.2. Системные требования и подготовка окружения

Перед установкой убедитесь в соответствии системы базовым требованиям:

Операционная система: macOS, актуальный дистрибутив Linux или Windows через подсистему WSL2.
Среда выполнения: Node.js версии 18.0 или выше (проверьте командой node -v).
Контроль версий: Git версии 2.20+ (проверьте командой git --version).
Доступ к моделям Anthropic: активный API-ключ Anthropic Console либо подписка Claude Max.

2. Установка и аутентификация

2.1. Установка CLI через npm и менеджеры пакетов

Claude Code устанавливается глобально через реестр npm:

bash

npm install -g @anthropic-ai/claude-code

Проверьте корректность установки бинарного файла:

bash

claude --version

Если терминал сообщает command not found, значит путь к глобальным пакетам npm отсутствует в переменной среды PATH. Инструкция по исправлению приведена в блоке диагностики ниже.

2.2. Аутентификация и привязка учётной записи Anthropic

Поддерживается два способа авторизации:

Вариант 1 — Ключ Anthropic API:
Задайте токен через переменную окружения:

bash

export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api"

Чтобы сохранить переменную между сессиями терминала, добавьте её в конфигурационный файл оболочки:

bash

echo 'export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api"' >> ~/.zshrc source ~/.zshrc

Вариант 2 — Подписка Claude Max (OAuth):
При наличии подписки Claude Max ($100 или $200/мес) войдите через браузер:

bash

claude login

Команда откроет сессию в браузере по умолчанию для подтверждения прав доступа.

3. Первый запуск и базовая конфигурация

3.1. Первый запуск в проекте и проверка окружения

Перейдите в каталог любого рабочего проекта и запустите Claude Code:

bash

cd ~/my-project claude

После запуска вы попадёте в интерактивную среду REPL. Отправьте первый тестовый запрос:

text

Summarize the structure of this project and list the main technologies used.

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

3.2. Базовая конфигурация и устранение неполадок (Troubleshooting)

Файлы конфигурации располагаются в директории ~/.claude/:

~/.claude/settings.json — глобальные разрешения и политики вызова утилит.
~/.claude/CLAUDE.md — персональные системные инструкции пользователя.
.claude/settings.json — настройки уровня проекта (коммитятся в git).
CLAUDE.md — инструкции конкретного репозитория (стандарты кода, линтинг).

Проблема при запуске	Причина	Инженерное решение
`claude: command not found`	Каталог npm bin не включён в `PATH`	Добавьте путь в профиль оболочки: `export PATH="$(npm config get prefix)/bin:$PATH"`
Ошибка авторизации `401 Unauthorized`	Недействительный или просроченный API-ключ	Выполните `claude logout`, проверьте `ANTHROPIC_API_KEY` и заново запустите `claude login`
Медленный первый запуск	Первичная индексация репозитория	Первый запуск индексирует проект; последующие сессии используют локальный кэш

4. Практика: создание первого приложения

4.1. Пошаговый алгоритм создания прототипа

Цель первой практической части — с помощью Claude Code создать минимальный клиентский компонент Next.js / React:

Попросите Claude создать новый файл страницы app/practice/page.tsx.
Поручите агенту реализовать кнопку и асинхронный обработчик запроса.
Проверьте результат в браузере по адресу http://localhost:3000/practice.

4.2. Стартовый шаблон кода и проверка на локальном сервере

Исходный код прототипа:

tsx

// app/practice/page.tsx 'use client'; import { useState } from 'react'; export default function PracticePage() { const [result, setResult] = useState(''); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); try { const response = await fetch('/api/test'); const data = await response.json(); setResult(data.message || 'Запрос успешно выполнен'); } catch { setResult('Ошибка выполнения тестового запроса'); } finally { setLoading(false); } } return ( <div className="p-8 max-w-2xl mx-auto font-sans"> <h1 className="text-3xl font-bold mb-6">Практическое упражнение 1: Прототип</h1> <button onClick={runTest} disabled={loading} className="bg-black text-white px-6 py-3 rounded-lg hover:bg-neutral-800 disabled:opacity-50 transition" > {loading ? 'Выполняется...' : 'Запустить тест'} </button> {result && ( <div className="mt-6 p-4 bg-neutral-100 rounded-lg border border-neutral-200"> {result} </div> )} </div> ); }

5. Рабочая сессия и цикл диалога

5.1. Запуск интерактивной REPL-сессии

Для ежедневной разработки перейдите в корень проекта и запустите сессию:

bash

cd ~/my-project claude

Claude сохраняет контекст диалога на протяжении всей сессии, отслеживая отредактированные файлы и выводы компилятора. Общение строится на обычном человеческом языке.

5.2. Цикл диалога: планирование, вызов инструментов и проверка

Работа агента строится по пятиэтапному циклу:

mermaid

flowchart TD A["Пользователь ставит задачу естественным языком"] --> B["Claude исследует код и составляет план действий"] B --> C["Агент запрашивает подтверждение перед вызовом утилит"] C --> D["Выполнение одобренных действий и отображение diff"] D --> E["Пользователь проверяет результат и даёт обратную связь"]

Пример диалога:

Запрос: Добавь индикатор загрузки на страницу дашборда.
Анализ: Claude читает app/dashboard/page.tsx и обнаруживает отсутствие состояния ожидания данных.
Предложение: Создаёт loading.tsx и оборачивает блок в границы React Suspense.
Подтверждение: Показывает построчный diff и ожидает согласия пользователя.

6. Горячие клавиши, команды и режимы работы

6.1. Основные горячие клавиши и слеш-команды управления контекстом

Удобная навигация в терминале опирается на быстрые комбинации:

Сочетание клавиш	Назначение
`Enter`	Отправить сообщение агенту
`Escape`	Отменить текущую генерацию или выполнение утилиты
`Ctrl+C`	Выйти из Claude Code
`Up` / `Down`	Навигация по истории команд
`Shift+Tab`	Переключение между однострочным и многострочным вводом

Встроенные слеш-команды для управления сессией:

/help — список доступных команд.
/clear — очистить историю диалога.
/compact — сжать историю сообщений для освобождения контекстного окна.
/model — переключить активную модель (например, между Sonnet и Opus).
/permissions — просмотреть и настроить действующие разрешения.

6.2. Неинтерактивный режим и советы по эффективной работе

Для скриптов автоматизации и разовых вызовов используйте флаг -p (print):

bash

# Получить быстрый ответ по архитектуре проекта claude -p "Какую базу данных использует этот проект?" # Передать лог ошибок через конвейер cat error.log | claude -p "Найди первопричину сбоя и предложи исправление"

💡 Рекомендации по эффективности:

Формулируйте задачи конкретно: вместо «почини форму» пишите «добавь debounce к кнопке отправки формы».

Регулярно используйте /compact, когда длина диалога превышает 30–40 сообщений.

7. Практика: доработка приложения

7.1. Рефакторинг и оптимизация кодовой базы с помощью Claude

Во второй части доработаем созданный прототип, поручив Claude улучшить типизацию и обработку исключений.

Отправьте агенту следующий промпт:

text

Открой app/practice/page.tsx. Добавь строгую типизацию TypeScript, обработку ошибок try/catch с выводом сообщения на красном фоне и анимированный CSS-спиннер во время загрузки.

7.2. Расширение функционала: стилизация, обработка ошибок и анимации

Обновлённый код компонента:

tsx

// app/practice/page.tsx - Доработанная версия 'use client'; import { useState } from 'react'; export default function PracticePage() { const [result, setResult] = useState<string | null>(null); const [error, setError] = useState<string | null>(null); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); setError(null); try { const response = await fetch('/api/test'); if (!response.ok) throw new Error(`Ошибка сервера: код ${response.status}`); const data = await response.json(); setResult(data.message || 'Операция успешно завершена'); } catch (err: unknown) { setError(err instanceof Error ? err.message : 'Произошла непредвиденная ошибка'); } finally { setLoading(false); } } return ( <div className="p-8 max-w-2xl mx-auto font-sans"> <h1 className="text-3xl font-bold mb-4">Практическое упражнение 2: Доработка</h1> <p className="text-neutral-600 mb-6">Тестирование обработки исключений и динамических состояний.</p> <button onClick={runTest} disabled={loading} className="flex items-center gap-2 bg-black text-white px-6 py-3 rounded-lg hover:bg-neutral-800 disabled:opacity-50 transition" > {loading && ( <span className="w-4 h-4 border-2 border-white border-t-transparent rounded-full animate-spin" /> )} {loading ? 'Обработка запроса...' : 'Выполнить действие'} </button> {error && ( <div className="mt-6 p-4 bg-red-50 text-red-700 rounded-lg border border-red-200"> {error} </div> )} {result && ( <div className="mt-6 p-4 bg-neutral-100 text-neutral-800 rounded-lg border border-neutral-200"> {result} </div> )} </div> ); }

8. Модель разрешений и безопасность

8.1. Архитектура модели разрешений и уровни риска инструментов

Система безопасности Claude Code делит операции на две категории в зависимости от степени потенциального риска:

Категория доступа	Разрешённые инструменты	Механизм исполнения
Безопасные (Read-only)	`Read`, `Grep`, `Glob`, просмотр каталогов	Выполняются автоматически без подтверждения
Потенциально опасные	`Edit`, `Write`, `Bash`, удаление файлов, `git push`	Требуют явного подтверждения пользователя

8.2. Механика подтверждения и отклонения опасных действий

Перед вызовом опасного инструмента Claude приостанавливает работу и запрашивает согласие:

text

Claude wants to run: npm install express Allow? (y/n/always)

Варианты ответа:

y (yes) — разрешить конкретное разовое действие.
n (no) — отклонить действие с указанием причины.
always (или a) — разрешить этот инструмент до завершения текущей сессии.

9. Файлы настроек и управление правами

9.1. Глобальные и проектные файлы настроек (settings.json)

Для сохранения постоянных правил создайте или отредактируйте ~/.claude/settings.json:

json

{ "permissions": { "allow": [ "Read", "Glob", "Grep", "Edit", "Write", "Bash(npm run *)", "Bash(git status)" ], "deny": [ "Bash(rm -rf *)", "Bash(sudo *)" ] } }

9.2. Паттерны для bash-команд и проверка через /permissions

Массив permissions.allow поддерживает гибкие glob-шаблоны:

Bash(npm test *) — запускает тесты без запросов подтверждения.
Bash(git commit *) — разрешает фиксацию изменений.
Bash(rm -rf *) в списке deny — гарантирует блокировку рекурсивного удаления данных.

Текущий статус действующих правил можно проверить в любой момент командой /permissions.

10. Best practices по безопасности и работе

10.1. Стратегия контроля доступа: принцип наименьших привилегий

Постепенное расширение прав: Начинайте работу с полным ручным контролем. Добавляйте команды в allow только после проверки предсказуемости действий агента.
Запрет wildcard для bash: Никогда не добавляйте "Bash(*)" в список разрешений — это полностью отключает защитную песочницу.
Явные запреты через deny: Блокируйте опасные утилиты (sudo, mkfs, dd), чтобы исключить риск случайного подтверждения.

10.2. Изоляция секретов окружения и аудит диффов перед выполнением

Защита секретов: Claude Code наследует переменные окружения родительской оболочки. Не запускайте сессии с переменными, содержащими ключи от боевых баз данных.
Аудит диффов: Всегда внимательно проверяйте предложенный diff перед подтверждением редактирования файла.

11. Практика: финальная версия приложения

11.1. Безопасный рабочий процесс и валидация готовности

В финальном модуле соберём полноценный production-ready компонент:

Зафиксируйте правила безопасности в .claude/settings.json.
Поручите Claude провести финальный рефакторинг с полной поддержкой TypeScript и валидацией ответов сервера.
Выполните проверку сборки командой npm run build.

11.2. Финальный код компонента и чек-лист перед деплоем

Итоговая версия компонента:

tsx

// app/practice/page.tsx - Финальная production-ready версия 'use client'; import { useState } from 'react'; interface ApiResponse { message: string; status: 'ok' | 'error'; timestamp: string; } export default function PracticePage() { const [data, setData] = useState<ApiResponse | null>(null); const [error, setError] = useState<string | null>(null); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); setError(null); try { const response = await fetch('/api/test'); if (!response.ok) throw new Error(`Ошибка сервера: код ${response.status}`); const payload: ApiResponse = await response.json(); setData(payload); } catch (err: unknown) { setError(err instanceof Error ? err.message : 'Непредвиденный сбой выполнения'); } finally { setLoading(false); } } return ( <main className="min-h-screen bg-neutral-50 py-12 px-4 sm:px-6 lg:px-8 font-sans"> <div className="max-w-xl mx-auto bg-white p-8 rounded-xl shadow-sm border border-neutral-200"> <h1 className="text-2xl font-semibold text-neutral-900 mb-2">Практическое упражнение 3: Финальная версия</h1> <p className="text-sm text-neutral-500 mb-6">Безопасный клиентский компонент, оптимизированный через Claude Code.</p> <button onClick={runTest} disabled={loading} className="w-full flex justify-center items-center gap-2 bg-neutral-900 text-white py-3 px-4 rounded-lg font-medium hover:bg-neutral-800 disabled:opacity-50 transition" > {loading && ( <span className="w-4 h-4 border-2 border-white border-t-transparent rounded-full animate-spin" /> )} {loading ? 'Выполняется проверка...' : 'Запустить диагностику'} </button> {error && ( <div className="mt-6 p-4 bg-red-50 text-red-700 text-sm rounded-lg border border-red-200"> <strong>Ошибка:</strong> {error} </div> )} {data && ( <div className="mt-6 p-4 bg-neutral-50 text-neutral-800 text-sm rounded-lg border border-neutral-200 space-y-1"> <div><strong>Статус:</strong> {data.status}</div> <div><strong>Сообщение:</strong> {data.message}</div> <div className="text-xs text-neutral-400"><strong>Временная метка:</strong> {data.timestamp}</div> </div> )} </div> </main> ); }