# Claude Code: база для начинающих > Полное руководство по Claude Code от Anthropic: установка CLI, аутентификация, управление правами доступа, горячие клавиши и пошаговая разработка первого проекта. 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: 1. Попросите Claude создать новый файл страницы `app/practice/page.tsx`. 2. Поручите агенту реализовать кнопку и асинхронный обработчик запроса. 3. Проверьте результат в браузере по адресу `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 (

Практическое упражнение 1: Прототип

{result && (
{result}
)}
); } ``` --- ## 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(null); const [error, setError] = useState(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 (

Практическое упражнение 2: Доработка

Тестирование обработки исключений и динамических состояний.

{error && (
{error}
)} {result && (
{result}
)}
); } ``` --- ## 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 компонент: 1. Зафиксируйте правила безопасности в `.claude/settings.json`. 2. Поручите Claude провести финальный рефакторинг с полной поддержкой TypeScript и валидацией ответов сервера. 3. Выполните проверку сборки командой `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(null); const [error, setError] = useState(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 (

Практическое упражнение 3: Финальная версия

Безопасный клиентский компонент, оптимизированный через Claude Code.

{error && (
Ошибка: {error}
)} {data && (
Статус: {data.status}
Сообщение: {data.message}
Временная метка: {data.timestamp}
)}
); } ```