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:

Попросіть 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-сесії

Для повсякденної розробки перейдіть у робочий каталог та активуйте інтерактивний цикл читання-виконання (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 компонент панелі моніторингу:

Зафіксуйте правила безпеки у .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> ); }