Настройка Claude Code: руководство для начинающих

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

Что такое Claude Code на самом деле

Claude Code — это CLI-инструмент от Anthropic. Вы устанавливаете его глобально через npm, запускаете claude в директории проекта и получаете интерактивную сессию, в которой ассистент может читать файлы, выполнять команды в shell, редактировать код и предлагать git-коммиты.

Это не чат-интерфейс. Разница принципиальная: вы не вставляете куски кода во вкладку браузера. Когда вы просите исправить баг, инструмент читает реальный исходный файл, вносит изменение и показывает вам diff. Вы решаете, что применять. Основной интерфейс — терминал, а не плагин для редактора, хотя интеграции с IDE тоже существуют.

Что нужно перед установкой

Прежде чем первая команда claude заработает, вам понадобятся две вещи.

Node.js 18 или выше

Claude Code распространяется как npm-пакет. Проверьте версию:

node --version

Если у вас ниже 18, обновитесь через nvm или системный пакетный менеджер. Node 20 LTS — надёжный выбор.

Заметка для пользователей Windows: Claude Code ненадёжно работает в нативном CMD или PowerShell. Используйте WSL2. Установите WSL2, настройте внутри Ubuntu и запускайте всё оттуда.

Аккаунт на Claude.ai

Для аутентификации нужен аккаунт на Claude.ai. Если его нет, создайте на claude.ai. Подписка Pro ($20 в месяц) включает использование Claude Code как фиксированную плату без дополнительных charges за токены. Если нужны большие объёмы, командный биллинг или контроль расходов по токенам, можно подключить Claude Code напрямую к Anthropic API с ключом из console.anthropic.com. Для большинства разработчиков на старте подписка Pro — более простой путь.

Установка и первый запуск Claude Code

Установите Claude Code глобально:

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

Проверьте, что установка прошла успешно:

claude --version

Вы должны увидеть строку с версией вида 1.x.x. Если появляется “command not found”, скорее всего глобальная директория npm bin не добавлена в PATH. Выполните echo $PATH и проверьте, есть ли там путь к глобальным бинарникам npm. Найти этот путь можна командой npm prefix -g — бинарники лежат в поддиректории bin/ этого пути. Если её нет, добавьте в профиль shell.

Теперь перейдите в директорию реального проекта и запустите сессию:

cd ~/projects/my-laravel-app
claude

При первом запуске откроется браузер с предложением войти через аккаунт Claude.ai. Завершите OAuth-flow, вернитесь в терминал — и вы внутри. Приглашение выглядит как простой REPL. Введите инструкцию и нажмите Enter. Чтобы выйти в любой момент, введите /exit или нажмите Ctrl+C.

Навигация в сессии: slash-команды, которые нужны каждый день

В Claude Code есть встроенные slash-команды для управления сессией. Вот четыре, которые реально нужны на старте.

/init

Запускайте один раз на проект, в корне репозитория. Инструмент читает структуру репозитория и генерирует файл CLAUDE.md с тем, что нашёл: стек, вероятные команды, структуру папок. Сгенерированный файл — отправная точка, а не готовый результат. Проверьте каждую строку и исправьте, что не так.

/help

Выводит список доступных команд с кратким описанием каждой. Полезно, когда забыли название команды или хотите посмотреть, что добавили в последнем обновлении.

/clear

Очищает историю разговора текущей сессии. Используйте, когда контекст разросся и ответы стали расплывчатыми. Начать заново на новой подзадаче часто эффективнее, чем продолжать раздутый тред.

/compact

Сжимает текущий разговор в более короткое представление без потери ключевых фактов. Это средний вариант между сохранением полной истории и её очисткой — полезно в длинных сессиях, когда вы ещё в середине задачи, но контекст становится дорогим.

CLAUDE.md: файл, который делает Claude Code полезным

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

Хороший CLAUDE.md отвечает на вопросы, которые вы бы объяснили новому инженеру в первый рабочий день: что это за проект, как его запустить, где что находится, что нельзя трогать. Вот реалистичный пример для Laravel-проекта:

# Project: MyApp API

Laravel 11, PHP 8.3, MySQL 8.0, Redis for queues and cache.

## Commands
- `php artisan serve` — local dev server
- `php artisan test` — run Pest test suite
- `./vendor/bin/pint` — code style (PER preset)
- `php artisan migrate` — run pending migrations

## Architecture
- API-only backend, no Blade views
- Controllers in app/Http/Controllers/, thin, delegate to Services
- Business logic in app/Services/
- Jobs in app/Jobs/ for anything async

## Conventions
- Short controller methods, fat service classes
- All DB writes go through a Service, never directly from a Controller
- Feature tests in tests/Feature/, unit tests in tests/Unit/

## Off-limits
- Do not edit files in vendor/
- Do not modify database/migrations/ that have already run in production
- Never commit .env changes

Пишите его так, как писали бы инструкцию для подрядчика. Агент использует его точно так же: как справочник перед тем, как задавать вопросы.

Модель разрешений: почему инструмент спрашивает перед выполнением команд

Когда вы просите Claude Code сделать что-то, что требует выполнения команды в shell или редактирования файла, он сначала запрашивает подтверждение. Это сделано намеренно, и отключать это не стоит.

Запрос подтверждения показывает вам точно, какую команду инструмент хочет выполнить, или демонстрирует diff перед применением правки. Ваша задача — читать это. Не просматривать, а читать.

Вы можете одобрить конкретное действие, отклонить его или разрешить всегда выполнять определённый класс команд в рамках текущей сессии — например, всегда разрешать команды php artisan. На старте будьте осторожны с опцией “always allow”. Легко одобрить широкий класс команд, который потом окажется шире, чем вы ожидали.

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

Три первых задачи, которые дадут больше, чем любой туториал

Абстрактные объяснения возможностей Claude Code менее полезны, чем три реальных задачи в знакомом проекте. Вот три отправные точки, упорядоченные от наименее к наиболее рискованным.

Задача 1: объяснить функцию

Найдите функцию в кодовой базе, которую вы не писали, или ту, что со временем разрослась. Спросите:

Explain what the `processInvoice` method in app/Services/BillingService.php does.
Focus on the side effects: what does it write to the database, what events does it fire?

Эта задача читает файлы, но ничего не пишет. Безопасный способ проверить, насколько хорошо модель понимает вашу кодовую базу. Если объяснение неточное или поверхностное, скорее всего вашему CLAUDE.md не хватает контекста об архитектуре.

Задача 2: исправить баг

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

In app/Http/Controllers/UserController.php, the `update` method does not validate
that `email` is unique before saving. Add the unique validation rule,
but exclude the current user's own email from the uniqueness check.

Внимательно проверьте diff перед тем, как применять. Убедитесь, что изменено именно то, что вы описали, и ничего лишнего. Это привычка к ревью, которую нужно выработать сейчас, пока задачи ещё небольшие.

Задача 3: написать тест

Попросите написать тест для логики, которая пока не покрыта:

Write a Pest feature test for the POST /api/users endpoint.
Cover: successful creation, validation failure when email is missing,
and a 409 response when the email already exists.

Тесты — хорошая цель для делегирования на старте, потому что результат легко проверить. Запустите тест. Если проходит — код, скорее всего, правильный. Если падает — прочитайте сообщение об ошибке и попросите исправить.

Типичные ошибки новичков

Вот паттерны, из-за которых Claude Code кажется ненадёжным, хотя проблема в промпте или рабочем процессе, а не в инструменте.

Расплывчатые промпты

“Исправь баг в user service” не говорит модели почти ничего. Указывайте конкретный файл, метод, симптом и ожидаемое поведение. Чем больше контекста вы даёте, тем меньше времени уходит на исправление результата.

Не читать diff

Самый частый способ внести регрессию с AI-инструментом — применить изменение, не прочитав его. Claude Code показывает diff перед применением. Это момент, чтобы поймать нежелательные правки. Пропустить его — всё равно что смержить PR, не посмотрев на него.

Широкие разрешения слишком рано

Если в первой же сессии вы разрешаете широкий класс команд через “always allow”, вы теряете защитную сетку, которая делает делегирование безопасным. Начните с подтверждением каждого действия. Когда поймёте, как инструмент ведёт себя в вашем проекте, расширяйте разрешения там, где это реально экономит усилия.

Давать задачи, требующие контекста, которого нет в файлах

Claude Code хорошо справляется с ограниченными, описуемыми задачами. Плохо — с теми, что требуют организационного контекста, которого нет ни в одном файле: почему конкретный workaround добавили для конкретного клиента, или что решение по продукту полугодовой давности означает для кодовой базы. Такие задачи оставляйте себе.

Что читать дальше

Когда проведёте несколько сессий и выстроите нормальный CLAUDE.md, следующий шаг — понять более широкий рабочий процесс: как структурировать задачи, чтобы агент оставался продуктивным, как работать с код-ревью, что делегировать, а что оставить себе. Моё руководство по AI-агентам в рабочем процессе разработчика разбирает это подробно, включая пять правил, которым я следую в каждом проекте.

Когда будете готовы идти дальше — к специализированным субагентам для исследования, планирования и ревью, руководство по субагентам Claude Code и оптимизации токенов продолжает с того места, где заканчивается это.

Часто задаваемые вопросы

Нужен ли API-ключ для использования Claude Code?

Нет. По умолчанию используется OAuth-вход через браузер с аккаунтом Claude.ai. API-ключ нужен только если вы хотите подключить Claude Code напрямую к Anthropic API для кастомного биллинга или повышенных лимитов использования.

Работает ли Claude Code на Windows?

Ненадёжно в нативном CMD или PowerShell. Используйте WSL2 с Ubuntu. Установите WSL2, запускайте все команды из терминала Ubuntu — всё будет работать как описано в документации.

Как выйти из сессии Claude Code?

Введите /exit в приглашении или нажмите Ctrl+C.

Что такое CLAUDE.md и нужен ли он?

Это текстовый файл в корне проекта, который Claude Code читает в начале каждой сессии. Он даёт агенту постоянный контекст о вашем стеке, командах и соглашениях. Без него можно начать работу, но придётся заново объяснять проект в каждой сессии. Запустите /init, чтобы сгенерировать черновик.

Claude Code бесплатный?

Использование Claude Code включено в подписку Claude.ai Pro без дополнительной платы за токены. Если использовать прямой путь через API, оплата идёт за токены по стандартным тарифам Anthropic API.

Как Claude Code получает доступ к моим файлам?

Он читает и записывает файлы напрямую на вашей локальной файловой системе, в рамках директории, из которой вы его запустили. Каждое редактирование файла и каждая команда в shell требуют вашего явного подтверждения перед выполнением.