# Claude Code: база для початківця

> Повний посібник із роботи з Claude Code від Anthropic: встановлення CLI, автентифікація, керування дозволами, гарячі клавіші та покрокова розробка першого проєкту.

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

Цей посібник — стартова точка для швидкого старту з Claude Code. Матеріал поділено на три логічні блоки:
- **Модуль 1 — Встановлення та базова конфігурація:** розгортання CLI, автентифікація через API або OAuth, перший запуск та огляд конфігураційних файлів.
- **Модуль 2 — Робоча сесія та взаємодія:** керування контекстом, гарячі клавіші, слеш-команди, неінтерактивний режим та оптимізація пам'яті (`/compact`).
- **Модуль 3 — Безпека та модель прав:** налаштування файлів `settings.json`, створення списків дозволів (allow) та заборон (deny) для bash-команд.

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

---

## 1. Що таке Claude Code та системні вимоги

### 1.1. Що таке Claude Code та його відмінності від вебчату

Claude Code інтегрується у ваш щоденний розробницький стек як термінальний асистент. На відміну від традиційного вебчату, агент володіє набором інструментів (Tools):
- **Читання та пошук:** інспектує окремі файли, шукає входження через регулярні вирази (`grep`) та орієнтується у структурі проєкту (`glob`).
- **Модифікація коду:** генерує точкові модифікації файлів через механізм patch/diff, уникаючи повної перезапису великих файлів.
- **Виконання системних команд:** запускає тести, компілятори, лінтери та 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/міс), увійдіть без використання окремого API-ключа:

```bash
claude login
```

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

---

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

### 3.1. Перший запуск у проєкті та верифікація середовища

Перейдіть у каталог будь-якого вашого кодового проєкту та ініціалізуйте Claude Code:

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

Після запуску ви потрапите в інтерактивне командне середовище. Спробуйте надіслати базовий тестовий запит:

```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` — проєктні налаштування (фіксуються в системі контролю версій).
- `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. Покроковий алгоритм розгортання прототипу

Мета першої вправи — на практиці створити мінімальний клієнтський компонент Next.js / React за допомогою Claude Code:
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 (
    <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-сесії

Для повсякденної розробки перейдіть у робочий каталог та активуйте інтерактивний цикл читання-виконання (REPL):

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

Claude зберігає контекст розмови протягом сесії, пам'ятаючи змінені файли та виявлені помилки. Спілкування ведеться звичайною мовою без формалізованого синтаксису.

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

Робота агента підпорядкована п'ятиетапному циклу:

```mermaid
flowchart TD
    A["Користувач ставить завдання природною мовою"] --> B["Claude аналізує кодову базу та формує план"]
    B --> C["Агент запитує дозвіл на модифікацію файлів/команд"]
    C --> D["Виконання затверджених дій та валідація дифу"]
    D --> E["Користувач перевіряє результат та надає фідбек"]
```

Типовий фрагмент взаємодії:
- **Запит:** `Додай індикатор завантаження на сторінку дашборду.`
- **Аналіз:** Claude зчитує `app/dashboard/page.tsx`, виявляє відсутність обробки очікування даних.
- **Пропозиція:** Створення компонента `loading.tsx` та огортання блоку у межі `Suspense`.
- **Підсумок:** Агент демонструє точковий diff і очікує вашого схвалення.

---

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

### 6.1. Гарячі клавіші та слеш-команди для керування контекстом

Ефективна навігація в терміналі базується на системних скороченнях:

| Комбінація | Призначення |
| :--- | :--- |
| `Enter` | Відправка поточного повідомлення агенту |
| `Escape` | Миттєве скасування активної генерації або виконання інструменту |
| `Ctrl+C` | Коректне завершення роботи сесії Claude Code |
| `Up` / `Down` | Перегляд попередньої історії запитів |
| `Shift+Tab` | Перемикання між однорядковим та багаторядковим введенням |

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

### 6.2. Неінтерактивний режим та поради для ефективної роботи

Для використання Claude Code у скриптах автоматизації або одноразових операціях застосовуйте прапорець `-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 patterns):
- `Bash(npm test *)` — дозволяє запуск тестових пакетів без підтверджень.
- `Bash(git commit *)` — дозволяє фіксацію змін.
- `Bash(rm -rf *)` у списку `deny` — гарантує абсолютне блокування масового видалення даних.

Для перегляду дійсних правил у будь-який момент сесії виконайте команду `/permissions`.

---

## 10. Найкращі практики безпеки та роботи

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

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

### 10.2. Захист секретів середовища та ретельний аудит дифів

- **Ізоляція токенів:** Claude Code має доступ до змінних оточення поточної оболонки. Не тримайте у робочій сесії критичні ключі від production-баз даних.
- **Перегляд дифу перед затвердженням:** Завжди аналізуйте запропонований 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<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>
  );
}
```