# Гайд для Claude Code: налаштування для агентного програмування (для новачків)

> Повний практичний гайд із налаштування Claude Code: інсталяція CLI, конфігурація CLAUDE.md і settings.json, правила дозволів, автоматичні хуки, кастомна команда /truth та субагенти.

## 1. Встановлення Claude Code та підготовка середовища

Claude Code встановлюється як автономний інтерфейс командного рядка (CLI) для взаємодії з кодом через агентні моделі Anthropic. На відміну від звичайних чат-ботів, Claude Code безпосередньо взаємодіє з файловою системою, запускає термінальні команди, аналізує дерево проєкту та вносить атомарні правки.

### 1.1. Способи інсталяції CLI: нативний скрипт проти npm

Рекомендований розробниками спосіб інсталяції — нативний системний скрипт, який автоматично налаштовує бінарний файл та середовище виконання. Як альтернативу для робочих станцій із готовим Node.js-тулчейном можна використовувати глобальний пакет npm:

```bash
# macOS, Linux або WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Альтернативне встановлення через npm
npm install -g @anthropic-ai/claude-code
```

Після завершення встановлення перевірте працездатність команди, виконавши `claude --version` у вашому терміналі.

### 1.2. Прив'язка до директорії проєкту та автентифікація

Перед першим запуском критично важливо перейти безпосередньо в кореневу папку вашого робочого проєкту:

```bash
cd your-project-directory
claude
```

> 💡 **Чому це важливо:** Claude Code жорстко прив'язує довгострокову пам'ять, локальні правила та дозволи до поточної робочої директорії. Запуск із домашньої папки (`~`) або робочого столу призведе до втрати архітектурного контексту вашого репозиторію.

Під час першого запуску інструмент запропонує пройти автентифікацію:
- **OAuth-вхід через браузер** за наявності активної підписки Claude (Pro, Max або Team).
- **API-ключ Anthropic Console** для прямої посекундної оплати токенів за тарифами API.

Окрім чистого терміналу, Claude Code підтримує роботу через офіційне розширення для VS Code, плагін для JetBrains, десктопний застосунок та веб-інтерфейс на claude.ai. Усі ці інтерфейси використовують спільну файлову структуру конфігурації `.claude/`, тому всі правила залишаються незмінними незалежно від вибраного робочого середовища.

## 2. Три файли конфігурації: архітектура пам'яті та налаштувань

Claude Code використовує дворівневу ієрархію конфігурації: директорію проєкту `.claude/` (разом із файлом `CLAUDE.md` у корені) та глобальну директорію `~/.claude/` у домашній папці користувача. Глобальні налаштування застосовуються до всіх сесій на машині, а локальні мають пріоритет для поточного репозиторію.

### 2.1. CLAUDE.md та правила пам'яті репозиторію

`CLAUDE.md` — це постійна пам'ять проєкту, яку агент читає на початку кожної робочої сесії. Тут фіксуються архітектурні орієнтири, команди запуску тестів, правила стилю коду та технологічний стек.

| Механізм | Розташування | Призначення |
| --- | --- | --- |
| **Кореневий гайд** | `CLAUDE.md` | Головні інструкції та опис стеку (рекомендовано до 2500 токенів). |
| **Модульні правила** | `.claude/rules/*.md` | Специфічні інструкції, прив'язані до конкретних шляхів і файлів. |
| **Генератор пам'яті** | Команда `/init` | Автоматичний аналіз кодової бази та створення стартового файлу. |
| **Редактор пам'яті** | Команда `/memory` | Швидке інтерактивне редагування зафіксованих правил. |

> ⚠️ **Головний принцип пам'яті:** Інструкції, надані просто в чаті, неминуче губляться під час стиснення контексту в довгих сесіях. Будь-яке правило, яке має зберегтися між сесіями, повинно бути явно записано в `CLAUDE.md`.

### 2.2. settings.json та механізм автоматичної пам'яті (Auto memory)

Файл конфігурації `settings.json` (розташований у `.claude/settings.json` для проєкту або в `~/.claude/settings.json` для глобального рівня) визначає дозволи безпеки, системні хуки, змінні середовища та модель за замовчуванням.

Механізм **Auto memory** дозволяє Claude Code автоматично записувати робочі спостереження між сесіями без прямого втручання розробника. Цю поведінку можна контролювати параметром `"autoMemoryEnabled": false` або системною змінною оточення `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, якщо ви віддаєте перевагу виключно прозорому ручному контролю через `CLAUDE.md`.

## 3. Налаштування дозволів і хуків заздалегідь

Для забезпечення безпеки та усунення зайвих запитів на підтвердження Claude Code пропонує систему інтерактивних режимів і гранулярних правил у конфігурації.

### 3.1. Інтерактивні режими дозволів та матриця allow/ask/deny

Швидке перемикання режимів виконання здійснюється комбінацією клавіш `Shift+Tab`:
- **Default** — запитує підтвердження користувача перед кожною потенційно небезпечною операцією чи зміною файлу.
- **Auto-Accept Edits** — автоматично застосовує правки файлів, запитуючи підтвердження лише на системні команди.
- **Plan Mode** — режим читання без можливості зміни коду чи виконання bash-команд до схвалення загального плану.

Для усунення рутинних підтверджень у `.claude/settings.json` налаштовується декларативна матриця правил:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}
```

Правило `deny` завжди має найвищий пріоритет: навіть якщо маска `Read(**)` дозволяє читання файлів, явна заборона `Read(.env)` гарантує, що конфіденційні змінні оточення ніколи не потраплять у контекст моделі.

### 3.2. Автоматизація через хуки PostToolUse та PreToolUse

Хуки дозволяють запускати локальні сценарії до або після виклику вбудованих інструментів агента. 

Наприклад, хук **PostToolUse** автоматично форматує відредаговані файли через Prettier:

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

А хук **PreToolUse** дозволяє програмно перехоплювати та блокувати небезпечні bash-команди на рівні Python-скрипта до їх фактичної передачі в оболонку:

```python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json
import re
import sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: command matches dangerous security pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)
```

Код повернення `2` сигналізує Claude Code про аварійне блокування виклику без виконання команди в системі.

## 4. Команди, які варто вивчити першими

Вбудована бібліотека Claude Code містить понад шістдесят слеш-команд, проте для повсякденної продуктивної роботи достатньо базового ядра.

### 4.1. Зведена таблиця базових та просунутих слеш-команд

Нижче наведено структурований довідник найважливіших команд CLI:

| Команда | Категорія | Призначення та поведінка |
| --- | --- | --- |
| `/init` | Налаштування | Сканує проєкт та створює первинний `CLAUDE.md`. |
| `/memory` | Налаштування | Відкриває файл пам'яті проєкту для прямого редагування. |
| `/clear` | Контекст | Скидає поточну бесіду, зберігаючи пам'ять проєкту. |
| `/compact [focus]` | Контекст | Стискає історію сесії, залишаючи вказані ключові аспекти. |
| `/context` | Контекст | Показує детальний стан заповнення контекстного вікна. |
| `/plan` | Планування | Перемикає CLI в режим лише для читання та проєктування кроків. |
| `/diff` | Перевірка | Відображає інтерактивний перегляд усіх змін за поточну сесію. |
| `/code-review [--fix]` | Перевірка | Аналізує незакомічені зміни на наявність логічних помилок. |
| `/security-review` | Перевірка | Спеціалізований аудит коду на наявність вразливостей. |
| `/resume [session]` | Навігація | Відновлює попередню сесію за її ідентифікатором або назвою. |
| `/branch [name]` | Навігація | Створює окрему гілку бесіди без перезапуску сесії. |
| `/rewind` | Навігація | Відкочує стан файлів або діалогу до попереднього чекпоінту. |
| `/model` | Продуктивність | Перемикає робочу модель (Sonnet, Haiku, Opus) посеред розмови. |
| `/effort` | Продуктивність | Регулює глибину ланцюжка міркувань моделі (від low до max). |
| `/cost` | Продуктивність | Виводить статистику витрат токенів та баланс сесії. |
| `/agents` | Делегування | Керує спеціалізованими субагентами та фоновими задачами. |
| `/permissions` | Конфігурація | Інтерактивне меню перегляду та зміни списку дозволів. |
| `/hooks` | Конфігурація | Панель діагностики зареєстрованих системних хуків. |
| `/doctor` | Діагностика | Комплексна перевірка оточення, мережі та системних ключів. |

![Огляд та навігація вбудованих слеш-команд у Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-01.webp)

### 4.2. Тріада щоденної продуктивності: /compact, /plan та /diff

Для швидкого освоєння рекомендується закріпити три обов'язкові інструменти:
1. **`/plan`** — завжди запускайте на початку складного завдання. Це усуває хаотичні неконтрольовані редагування коду без чіткого розуміння наслідків.
2. **`/compact`** — використовуйте кожні 20–30 хвилин активного діалогу або після завершення підзадачі, щоб запобігти падінню швидкості та втраті уваги моделі.
3. **`/diff`** — відкривайте перед будь-яким комітом для покрокової візуальної верифікації згенерованого коду.

## 5. Створення власної команди /truth

Команда `/truth` не входить до стандартного постачання Claude Code, проте вона розв'язує фундаментальну проблему агентного програмування — схильність моделі звітувати про успіх без фактичної перевірки результатів у файловій системі.

### 5.1. Концепція верифікації фактів проти кодової бази

Коли агент стверджує: *«Я оновив тип у файлі X і перевірив імпорти у файлі Y»*, він нерідко спирається на власні проміжні наміри з контексту. Концепція команди `/truth` полягає у примусовому перезавантаженні реальних файлів з диска та звірці кожного твердження з `git diff`.

![Інтерактивне керування контекстом, сесіями та командами Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-02.webp)

### 5.2. Реалізація скіла .claude/skills/truth/SKILL.md

Кастомні команди оформлюються як навички (skills). Створіть файл `.claude/skills/truth/SKILL.md` у вашому проєкті:

```markdown
---
description: "Verify Claude's most recent claims and edits against the actual codebase"
allowed-tools: ["Read", "Grep", "Glob", "Bash(git diff:*)"]
---

Re-examine everything you just told me in this conversation against what actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config value, an import, a dependency version), verify it against the real file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described changing.
4. Report back plainly: which claims checked out, which didn't, and exactly what the discrepancy was for anything that failed. Do not soften or hedge a discrepancy you find, state it directly.
```

Завдяки ізоляції в `allowed-tools` команда фізично не має права змінювати файли — вона працює виключно як незалежний аудитор.

## 6. Субагенти та паралельна робота

Під час роботи над великими проєктами виникає проблема перевантаження контексту: читання десятків файлів та запуск важких тестів швидко заповнюють доступне контекстне вікно.

### 6.1. Ізоляція контексту та спеціалізовані субагенти (/agents)

Субагент — це окремий екземпляр Claude Code з власним ізольованим контекстом, набором інструментів та вузьким системним промптом. Він вирішує поставлену підзадачу автономно та повертає в основну сесію лише лаконічний підсумок.

```bash
# Відкрити інтерактивне меню субагентів усередині сесії
/agents
```

Ви також можете декларативно описати постійного субагента у файлі `.claude/agents/code-reviewer.md`:
- Надати йому доступ лише на читання (`Read`, `Grep`, `Glob`).
- Призначити швидку та економну модель.
- Заборонити самостійне внесення змін у код, перетворивши його на надійного рецензента.

### 6.2. Масштабування завдань через worktree та пакетне виконання (/batch)

Для паралельного виконання кількох не пов'язаних між собою задач Claude Code підтримує режим Git Worktree та команду `/batch`:
- **Паралельні дерева (`--worktree`):** кілька агентів працюють в окремих ізольованих робочих копіях репозиторію без конфліктів файлових блокувань.
- **Пакетний режим (`/batch`):** виконання однотипних завдань рефакторингу чи генерації документації у фоновому потоці.

## 7. Готовий шаблон CLAUDE.md та settings.json

Ось перевірені на практиці конфігураційні файли, які варто закомітити в репозиторій вашого проєкту для створення стабільного виробничого середовища.

### 7.1. Базовий шаблон пам'яті CLAUDE.md

Збережіть наступний вміст у файлі `CLAUDE.md` в корені вашого репозиторію:

```markdown
# Project Context

### Stack
- Language/Framework: [Node.js, TypeScript, Next.js / Python, FastAPI]
- Styling: [Tailwind CSS]
- Database: [PostgreSQL / SQLite via Drizzle ORM]

### Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Conventions
- Strict TypeScript typing without `any`
- Functional React components with named exports
- Keep business logic in services or hooks, not inside UI components

### Before finishing any task
- Run test suite and confirm 100% pass rate
- Run `/truth` if the task involved modifying multiple files
```

### 7.2. Виробничий конфіг .claude/settings.json з хуками

Збережіть конфігурацію в `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Для локальних налаштувань, специфічних для вашої машини, використовуйте `.claude/settings.local.json`, додавши його до `.gitignore`.

## 8. Висновок та чекліст готовності

Якісне середовище для агентного програмування відрізняється від хаотичного чату попереднім налаштуванням захисних механізмів, правил пам'яті та чітких протоколів перевірки.

### 8.1. Ключові принципи агентного програмування

1. **Контекст має бути чистим:** регулярно використовуйте `/compact` і виносьте тривалі задачі в субагенти.
2. **Пам'ять має бути записана:** якщо правило важливе — зафіксуйте його в `CLAUDE.md`, а не повторюйте в повідомленнях.
3. **Дії мають перевірятися:** задійте `/truth` та `/diff` перед фіксацією змін у системі контролю версій.

### 8.2. Чекліст первинного налаштування робочого простору

| Етап | Дія | Статус готовності |
| --- | --- | --- |
| **Інсталяція** | Встановлено нативний CLI Claude Code та пройдено автентифікацію | `Обов'язково` |
| **Пам'ять проєкту** | Створено `CLAUDE.md` з описом стеку, команд та конвенцій | `Обов'язково` |
| **Дозволи** | Сформовано списки `allow`, `ask` та `deny` у `settings.json` | `Обов'язково` |
| **Хук форматування** | Налаштовано `PostToolUse` для автоматичного виклику Prettier | `Рекомендовано` |
| **Скрипт безпеки** | Підключено `block-dangerous-bash.py` через `PreToolUse` | `Рекомендовано` |
| **Кастомний скіл** | Створено команду верифікації `.claude/skills/truth/SKILL.md` | `Рекомендовано` |