# Робота з Git через Claude Code: посібник для новачків

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

## 1. Що таке інтеграція Git у Claude Code

Claude Code має глибоку нативну інтеграцію з системою контролю версій Git. На відміну від звичайних AI-чатів, куди розробник змушений вручну копіювати вивід команд `git diff` або `git status`, термінальний агент Claude Code самостійно взаємодіє з вашим локальним репозиторієм через вбудований інструментарій виконання команд.

Агент аналізує структуру змін, відстежує історію проєкту, дотримується прийнятого стилю повідомлень та бере на себе рутинні операції: створення гілок, вибірковий стейджинг файлів, безпечний ребейз і навіть формування повних описів для Pull Request.

```mermaid
flowchart TD
    A["Запит розробника:<br><i>'Commit current changes'</i>"] --> B["Claude Code CLI"]
    B --> C["git status<br><i>(Перевірка змінених файлів)</i>"]
    B --> D["git diff<br><i>(Аналіз змісту та логіки)</i>"]
    B --> E["git log -n 5<br><i>(Визначення конвенції комітів)</i>"]
    C & D & E --> F["Інтелектуальний стейджинг<br><i>(Вибіркові git add &lt;file&gt;)</i>"]
    F --> G["Генерація опису коміту<br><i>(feat/fix згідно з контекстом)</i>"]
    G --> H{"Підтвердження користувача"}
    H -->|Схвалено| I["Виконання git commit"]
    H -->|Коригування| J["Оновлення повідомлення"]
```

### Переваги використання Git через Claude Code

| Критерій | Традиційний ручний Git | Робота через Claude Code |
| :--- | :--- | :--- |
| **Аналіз змін** | Ручний перегляд кожного файлу через `git diff` | Автоматичне розуміння семантики та зв'язків між файлами |
| **Опис комітів** | Часто неінформативні фрази на кшталт *"update"*, *"fix bug"* | Структуровані повідомлення за стандартом Conventional Commits |
| **Стейджинг** | Ризик випадково додати зайві або тимчасові файли через `git add .` | Точковий стейджинг тільки релевантних кодових файлів |
| **Конфлікти злиття** | Складне ручне співставлення маркерів `<<<<<<<` | Інтелектуальний аналіз бізнес-логіки обох гілок |
| **Створення PR** | Ручне написання заголовка, опису та чеклиста тестування | Автогенерація детального опису через зв'язку з `gh CLI` |

> [!NOTE]
> Claude Code виконує кожну команду в ізольованому контексті вашого локального репозиторію та завжди запитує підтвердження перед виконанням дій, що модифікують файли або історію гілок.

---

## 2. Створення комітів: інтелектуальний стейджинг та опис

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

```bash
Commit these changes with a descriptive message
```

### Що відбувається під капотом

Коли Claude отримує інструкцію зробити коміт, він виконує послідовну діагностику:

1. **Діагностика робочого дерева:** викликає `git status`, щоб отримати перелік змінених, видалених та нових невідстежуваних файлів.
2. **Семантичний аналіз коду:** запускає `git diff` для дослідження рядків, які зазнали правок, відокремлюючи бізнес-логіку від форматування.
3. **Вивчення конвенцій репозиторію:** перевіряє `git log -n 5`, з'ясовуючи, як прийнято іменувати коміти у вашій команді (наприклад, `feat(auth): ...` чи `Add auth module`).
4. **Точковий стейджинг:** додає до індексу Git тільки ті файли, які стосуються поточної задачі, пропускаючи конфігураційні чи секретні файли.
5. **Формулювання повідомлення:** генерує стислий заголовок та змістовний опис, що розкриває причини та наслідки змін.

:::tabs
@tab Conventional Commits
```text
feat(cart): implement instant item quantity counter in navbar

- Add reactive useCartCount hook to synchronize state across tabs
- Optimize database query to aggregate item count in a single request
- Add unit tests for edge cases when cart contains empty items
```
@tab Стислий опис (Simple)
```text
fix: resolve race condition in token refresh flow

Prevent multiple parallel requests from triggering duplicate OAuth
refresh cycles when access token expires.
```
@tab З прив'язкою до задач (Jira/Linear)
```text
PROJ-412: refactor notification worker queue

Migrate Redis connection pool to cluster mode to handle burst traffic.
Closes #184.
```
:::

> [!TIP]
> Якщо ви хочете зафіксувати лише конкретний файл або частину змін, прямо вкажіть це у промпті: `Commit only the changes in src/components/Header.tsx with an appropriate message`.

---

## 3. Робота з гілками та перемикання контексту

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

### Створення та перемикання гілок

```bash
# Створити нову гілку та перейти на неї
Create a new branch named feature/instant-search and switch to it
```

Claude автоматично виконає команду `git checkout -b feature/instant-search` (або `git switch -c`).

### Поєднання створення гілки з реалізацією фічі

Найбільша ефективність досягається, коли ви об'єднуєте намір створити гілку з формулюванням інженерної задачі:

```bash
Create a branch called fix/email-validation, then fix the regex check in the signup form and write a test for it
```

### Загальноприйняті префікси для гілок

- `feature/` або `feat/` — нова функціональність або компонент (наприклад, `feature/stripe-payments`).
- `fix/` або `bugfix/` — виправлення помилки (наприклад, `fix/oauth-redirect`).
- `refactor/` — оптимізація структури коду без зміни поведінки (наприклад, `refactor/user-service`).
- `chore/` — оновлення залежностей, конфігурацій CI/CD або документації (наприклад, `chore/upgrade-nextjs-15`).

---

## 4. Вирішення конфліктів злиття (Merge Conflicts)

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

Claude Code аналізує обидва боки конфлікту, розуміє авторський намір кожної гілки та інтегрує зміни без втрати функціональності.

### Покроковий алгоритм вирішення конфлікту через Claude

1. **Запустіть процес злиття або ребейзу в терміналі:**
   ```bash
   git merge origin/main
   # або
   git rebase main
   ```
2. **Якщо з'явилися конфліктні маркери, передайте керування Claude Code:**
   ```bash
   I have merge conflicts after rebasing on main. Please inspect each conflicting file, analyze both sides of the changes, and resolve them cleanly.
   ```
3. **Аналіз маркерів:** Claude зчитує маркери `<<<<<<< HEAD`, `=======` та `>>>>>>>`, після чого формує синтезований варіант коду.
4. **Верифікація компіляції:** після видалення маркерів агент запускає перевірку типів (`tsc --noEmit`) або тести (`npm test`), щоб упевнитися в працездатності розв'язку.
5. **Стейджинг розв'язаних файлів:** агент виконує `git add <resolved-files>` і готує фінальний крок для завершення злиття.

```typescript
// Приклад конфлікту у файлі конфігурації:
<<<<<<< HEAD
export const API_TIMEOUT = 10000; // Збільшено таймаут для повільних мереж у гілці фічі
=======
export const API_TIMEOUT = 8000; // Оновлений стандарт бекенду з гілки main
export const RETRY_ATTEMPTS = 3;  // Нове поле, додане колегою у main
>>>>>>> origin/main
```

Claude запропонує оптимальне узгоджене рішення: зберегти збільшений таймаут `10000` з вашої гілки та водночас додати нову константу `RETRY_ATTEMPTS = 3` з гілки `main`.

---

## 5. Cherry-pick, Rebase та перенесення комітів

Іноді виникає потреба перенести окремий патч чи виправлення критичного дефекту в релізну гілку, не переносячи всю історію розробки. Для цього використовується механізм `cherry-pick`.

### Перенесення окремого коміту (Cherry-pick)

```bash
Cherry-pick commit a7b9c1d from branch feature/cart onto release/v1.2.0
```

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

### Інтелектуальний бекпортинг (Backport)

У великих проєктах із декількома стабільними версіями бекпортинг є рутинною процедурою. Ви можете доручити Claude весь комплекс дій:

```bash
Backport the security fix from commit 3f8a92 to the legacy-support branch. Verify that existing legacy tests still pass and commit the result.
```

### Rebase проти Merge: коли що обирати

| Операція | Коли використовувати | Переваги | Що робить Claude |
| :--- | :--- | :--- | :--- |
| **`git rebase main`** | Під час оновлення локальної гілки свіжими змінами з `main` | Лінійна та чиста історія комітів без зайвих merge-комітів | Перевіряє кожен коміт по черзі, автоматично виправляє тривіальні конфлікти |
| **`git merge main`** | При злитні завершеної гілки фічі у спільну гілку релізу | Зберігає точний хронологічний порядок розробки | Створює єдиний merge-коміт із вичерпним переліком об'єднаних змін |

---

## 6. Управління тимчасовими змінами через Git Stash

Якщо вам терміново потрібно перемкнутися на критичний багфікс або перевірити роботу іншої гілки, але поточна робота ще не готова до оформлення в коміт, на допомогу приходить `git stash`.

Claude Code здатен виконувати багатокрокові послідовності операцій зі сховищем незавершених змін:

```bash
Stash my current changes with a label 'wip-checkout', switch to main, pull latest changes, and report back
```

### Повернення до збереженого стану

Після завершення перевірки або термінового фіксу поверніть свої напрацювання:

```bash
Switch back to feature/checkout, pop the stash 'wip-checkout', and resolve any conflicts if the base changed
```

> [!TIP]
> Завдяки семантичному аналізу, Claude автоматично перевірить, чи не було видалено файли під час оновлення базової гілки, і коректно застосує збережені зміни.

---

## 7. Створення Pull Requests та інтеграція з GitHub CLI (gh)

Якщо у вашій системі встановлена офіційна утиліта GitHub CLI (`gh`), Claude Code перетворюється на повноцінного асистента створення та рецензування Pull Request.

### Автоматичне оформлення PR через Claude

Замість заповнення форми в браузері вручну, введіть:

```bash
Push current branch to origin and create a pull request with gh CLI. Include summary, list of changes, and testing instructions.
```

### Зразок згенерованого Pull Request

Claude автоматично формує markdown-шаблон високої якості:

```markdown
## Summary
This PR implements user session invalidation on password reset to prevent
unauthorized access from stolen legacy tokens.

## Changes
- Add `revokeAllUserSessions` service in `src/services/auth.ts`
- Update password reset controller to call invalidation hook
- Add Redis blacklist mechanism for active JWT tokens
- Cover revocation flow with integration tests in `auth.test.ts`

## Testing Instructions
1. Login from two different browsers (simulate active sessions)
2. Trigger "Forgot Password" flow in Browser A
3. Verify that Browser B gets redirected to `/login` on next API call
4. Run test suite: `npm run test:auth`

Fixes #284
```

> [!IMPORTANT]
> Переконайтеся, що ви авторизовані в GitHub CLI за допомогою команди `gh auth status` перед створенням запитів на злиття.

---

## 8. Вбудовані правила безпеки та захисні механізми

Git — потужний інструмент, але недбале використання окремих прапорців може призвести до безповоротної втрати коду або перезапису спільної історії. Claude Code має вбудовані правила захисту від подібних помилок.

```mermaid
flowchart LR
    subgraph Небезпечні_дії["Заблоковано без прямої команди"]
        D1["git push --force в main"]
        D2["git add -A / git add ."]
        D3["git commit --amend (чужі коміти)"]
        D4["git commit --no-verify"]
    end
    subgraph Безпечні_альтернативи["Стандарт Claude Code"]
        S1["Звичайний push або новий коміт"]
        S2["Точковий стейджинг окремих файлів"]
        S3["Створення нового фіксуючого коміту"]
        S4["Виправлення помилок лінтера/тестів"]
    end
    D1 -.-> S1
    D2 -.-> S2
    D3 -.-> S3
    D4 -.-> S4
```

### Чотири золоті правила безпеки Claude Code

1. **Заборона деструктивного Force Push:** Claude ніколи не виконує `git push --force` або `-f` у захищені гілки (`main`, `master`, `release`) без вашого багаторазового явного підтвердження.
2. **Адресний стейджинг:** агент уникає сліпих команд `git add .` або `git add -A`. Кожен файл стейджиться за його точним шляхом, що запобігає випадковому витоку файлів `.env`, ключів шифрування або локальних дампів бази даних.
3. **Збереження цілісності історії:** агент віддає перевагу створенню нового коригувального коміту замість модифікації історії через `git commit --amend`, особливо якщо зміни вже були відправлені на віддалений сервер.
4. **Повага до Pre-commit Hooks:** Claude не використовує прапорець `--no-verify` для обходу перевірок Husky, ESLint чи Prettier. Якщо хук блокує коміт, агент знаходить причину помилки лінтера чи тестів, виправляє її і повторює спробу за правилами.

> [!WARNING]
> Ніколи не просіть штучний інтелект виконувати неперевірені команди `git reset --hard HEAD~N` на спільних гілках. Завжди використовуйте `git stash` або створення тимчасової гілки-бекапу перед масштабними змінами історії.

---

## 9. Практичний воркшоп: повний цикл від гілки до PR

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

### Крок 1. Перевірка стану та створення робочої гілки

Відкрийте термінал у вашому репозиторії, запустіть `claude` та дайте завдання:

```bash
Check git status, pull latest changes from main, and create a feature branch called feature/user-avatar
```

Claude переконається, що робоча директорія чиста, підтягне свіжі оновлення та створить нову локальну гілку.

### Крок 2. Реалізація задачі

Поставте задачу агенту:

```bash
Add an Avatar component in src/components/Avatar.tsx that renders a user image with fallback initials if the image URL is missing.
```

### Крок 3. Перевірка та точковий коміт

Після створення файлу дайте команду зафіксувати результат:

```bash
Review what was created, make sure tests pass, and commit only the avatar component files with a clear conventional commit message
```

Claude перевірить працездатність, додасть до індексу `src/components/Avatar.tsx` (разом з тестовим файлом) і сформує коміт:

```text
feat(ui): add Avatar component with initials fallback

- Render user image with rounded profile styling
- Fallback to calculated two-letter initials on missing src or error
- Add unit test coverage for invalid image source handling
```

### Крок 4. Пуш та відкриття Pull Request

Завершіть робочий цикл фінальним промптом:

```bash
Push this branch to GitHub and create a draft PR using gh CLI describing the changes
```

---

## 10. Швидка самоперевірка та підсумковий чек-лист

Перевірте рівень засвоєння матеріалу за допомогою короткого тесту.

### Контрольні питання

> **1. Чому Claude Code стейджить файли за їхніми точними іменами замість виконання `git add .`?**
>
> > [!TIP]
> > **Відповідь:** Щоб запобігти випадковому додаванню до репозиторію конфіденційних даних (`.env`), тимчасових системних файлів (`.DS_Store`) та локальних збірок, які могли бути пропущені у `.gitignore`.

> **2. Як Claude Code вирішує, у якому форматі написати повідомлення коміту?**
>
> > [!TIP]
> > **Відповідь:** Агент автоматично аналізує останні коміти репозиторію через `git log`, адаптуючись до існуючого командного стилю (Conventional Commits, префікси тактів Jira чи стислі описи).

> **3. Що станеться, якщо Pre-commit Hook (Husky/ESLint) завершиться з помилкою під час коміту через Claude?**
>
> > [!TIP]
> > **Відповідь:** Claude не буде обходити перевірку прапорцем `--no-verify`. Натомість він проаналізує вивід лінтера чи тестів, усуне порушення в коді та повторно виконає безпечний коміт.

### Підсумковий чек-лист ефективної роботи з Git

- [ ] Використовуйте єдину фразу `Commit these changes` замість ручного ланцюжка команд `status -> add -> commit`.
- [ ] Поєднуйте створення гілки з бізнес-задачею в одному промпті для збереження цілісного контексту.
- [ ] Довіряйте Claude первинний аналіз та вирішення складних конфліктів злиття після `rebase` чи `merge`.
- [ ] Завжди використовуйте `git stash` через Claude перед терміновим перемиканням на іншу гілку.
- [ ] Встановіть `gh CLI`, щоб делегувати Claude генерацію структурованих описів для Pull Request.
- [ ] Ніколи не вимикайте правила безпеки: перевіряйте фінальний дифф перед відправленням змін на віддалений сервер.