# Trabalhando com Git via Claude Code: Guia para Iniciantes

> Guia prático completo sobre a integração entre Git e Claude Code: staging inteligente, descrições automáticas de commits, resolução de conflitos de merge, GitHub CLI e padrões de segurança.

## 1. O que é a integração do Git no Claude Code

O Claude Code possui uma integração nativa profunda com o sistema de controle de versão Git. Diferentemente dos chats de IA convencionais, onde o desenvolvedor é obrigado a copiar manualmente a saída de comandos `git diff` ou `git status`, o agente de terminal Claude Code interage diretamente com seu repositório local por meio de um conjunto de ferramentas embutido para execução de comandos.

O agente analisa a estrutura das alterações, rastreia o histórico do projeto, adere ao estilo de mensagens adotado e assume as operações rotineiras: criação de branches, staging seletivo de arquivos, rebase seguro e até mesmo a elaboração de descrições completas para Pull Requests.

```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["Оновлення повідомлення"]
```

### Vantagens de usar o Git através do Claude Code

| Critério | Git manual tradicional | Trabalho via Claude Code |
| :--- | :--- | :--- |
| **Análise de alterações** | Revisão manual de cada arquivo via `git diff` | Compreensão automática da semântica e das relações entre arquivos |
| **Descrição de commits** | Frases frequentemente pouco informativas como *"update"*, *"fix bug"* | Mensagens estruturadas seguindo o padrão Conventional Commits |
| **Staging** | Risco de adicionar acidentalmente arquivos supérfluos ou temporários via `git add .` | Staging pontual apenas dos arquivos de código relevantes |
| **Conflitos de merge** | Complexa reconciliação manual dos marcadores `<<<<<<<` | Análise inteligente da lógica de negócio de ambos os branches |
| **Criação de PR** | Escrita manual do título, descrição e checklist de testes | Autogeração de descrição detalhada via integração com `gh CLI` |

> [!NOTE]
> O Claude Code executa cada comando em um contexto isolado do seu repositório local e sempre solicita confirmação antes de executar ações que modificam arquivos ou o histórico de branches.

---

## 2. Criação de commits: staging inteligente e descrição

O fluxo de trabalho diário mais comum do desenvolvedor é registrar alterações no repositório. Em vez de invocar sequencialmente três ou quatro comandos de terminal, você pode solicitar ao Claude Code com uma única frase simples em linguagem natural:

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

### O que acontece nos bastidores

Quando o Claude recebe a instrução de fazer um commit, ele executa um diagnóstico sequencial:

1. **Diagnóstico da árvore de trabalho:** chama `git status` para obter a lista de arquivos alterados, excluídos e novos não rastreados.
2. **Análise semântica do código:** executa `git diff` para examinar as linhas que sofreram edições, separando a lógica de negócio da formatação.
3. **Estudo das convenções do repositório:** verifica `git log -n 5`, identificando como são nomeados os commits na sua equipe (por exemplo, `feat(auth): ...` ou `Add auth module`).
4. **Staging pontual:** adiciona ao índice do Git apenas os arquivos relacionados à tarefa atual, ignorando arquivos de configuração ou sensíveis.
5. **Formulação da mensagem:** gera um título conciso e uma descrição substancial que revela as causas e consequências das mudanças.

:::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 Descrição Concisa (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 Com vínculo a tarefas (Jira/Linear)
```text
PROJ-412: refactor notification worker queue

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

> [!TIP]
> Se você quiser registrar apenas um arquivo específico ou parte das alterações, indique isso explicitamente no prompt: `Commit only the changes in src/components/Header.tsx with an appropriate message`.

---

## 3. Trabalho com branches e troca de contexto

Isolar o código em branches separados é uma regra fundamental do desenvolvimento colaborativo. O Claude Code permite criar um branch e iniciar a implementação da funcionalidade simultaneamente, sem a rotina tediosa de alternar entre o terminal e o editor.

### Criação e troca de branches

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

O Claude executará automaticamente o comando `git checkout -b feature/instant-search` (ou `git switch -c`).

### Combinando a criação do branch com a implementação da feature

A maior eficiência é alcançada quando você une a intenção de criar um branch à formulação da tarefa de engenharia:

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

### Prefixos amplamente aceitos para branches

- `feature/` ou `feat/` — nova funcionalidade ou componente (ex.: `feature/stripe-payments`).
- `fix/` ou `bugfix/` — correção de erro (ex.: `fix/oauth-redirect`).
- `refactor/` — otimização da estrutura do código sem alterar o comportamento (ex.: `refactor/user-service`).
- `chore/` — atualização de dependências, configurações de CI/CD ou documentação (ex.: `chore/upgrade-nextjs-15`).

---

## 4. Resolução de conflitos de merge (Merge Conflicts)

Conflitos de merge surgem quando o mesmo trecho de código foi modificado em dois branches diferentes. Resolver essas situações manualmente frequentemente resulta na remoção acidental de código útil ou em erros de sintaxe.

O Claude Code analisa ambos os lados do conflito, compreende a intenção original de cada branch e integra as alterações sem perda de funcionalidade.

### Algoritmo passo a passo para resolver conflitos via Claude

1. **Inicie o processo de merge ou rebase no terminal:**
   ```bash
   git merge origin/main
   # або
   git rebase main
   ```
2. **Se surgirem marcadores de conflito, passe o controle ao 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. **Análise dos marcadores:** o Claude lê os marcadores `<<<<<<< HEAD`, `=======` e `>>>>>>>`, e então forma uma variante sintetizada do código.
4. **Verificação de compilação:** após remover os marcadores, o agente executa a checagem de tipos (`tsc --noEmit`) ou testes (`npm test`) para garantir a viabilidade da solução.
5. **Staging dos arquivos resolvidos:** o agente executa `git add <resolved-files>` e prepara o passo final para concluir o merge.

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

O Claude proporá a solução harmonizada ótima: manter o timeout aumentado `10000` do seu branch e, simultaneamente, adicionar a nova constante `RETRY_ATTEMPTS = 3` do branch `main`.

---

## 5. Cherry-pick, Rebase e migração de commits

Às vezes surge a necessidade de migrar um patch específico ou corrigir um defeito crítico para um branch de release, sem trazer todo o histórico de desenvolvimento. Para isso, utiliza-se o mecanismo `cherry-pick`.

### Migração de um commit individual (Cherry-pick)

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

Se durante a migração do commit surgirem incompatibilidades na base de código, o Claude localiza automaticamente os diffs, ajusta caminhos de importação ou variáveis e propõe uma resolução limpa.

### Backporting inteligente (Backport)

Em grandes projetos com várias versões estáveis, o backporting é um procedimento rotineiro. Você pode delegar ao Claude todo o complexo de ações:

```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 vs Merge: quando escolher qual

| Operação | Quando usar | Vantagens | O que o Claude faz |
| :--- | :--- | :--- | :--- |
| **`git rebase main`** | Durante a atualização do branch local com mudanças recentes do `main` | Histórico linear e limpo de commits, sem merge-commits desnecessários | Verifica cada commit em sequência, corrigindo automaticamente conflitos triviais |
| **`git merge main`** | Ao integrar um branch de feature concluído no branch de release compartilhado | Preserva a ordem cronológica exata do desenvolvimento | Cria um único merge-commit com uma listagem exaustiva das mudanças integradas |

---

## 6. Gerenciamento de alterações temporárias via Git Stash

Se você precisa urgentemente trocar para um bugfix crítico ou verificar o funcionamento de outro branch, mas o trabalho atual ainda não está pronto para ser registrado como commit, o `git stash` vem em socorro.

O Claude Code é capaz de executar sequências multi-etapa de operações com o stash de alterações incompletas:

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

### Retorno ao estado salvo

Após concluir a verificação ou o registro urgente, recupere seu trabalho:

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

> [!TIP]
> Graças à análise semântica, o Claude verificará automaticamente se arquivos foram removidos durante a atualização do branch base e aplicará corretamente as alterações salvas.

---

## 7. Criação de Pull Requests e integração com GitHub CLI (gh)

Se a utilitária oficial GitHub CLI (`gh`) estiver instalada no seu sistema, o Claude Code transforma-se em um assistente completo para criação e revisão de Pull Requests.

### Formatação automática de PR via Claude

Em vez de preencher o formulário no navegador manualmente, insira:

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

### Exemplo de Pull Request gerado

O Claude formata automaticamente um template markdown de alta qualidade:

```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]
> Certifique-se de estar autenticado no GitHub CLI usando o comando `gh auth status` antes de criar solicitações de merge.

---

## 8. Regras de segurança embutidas e mecanismos de proteção

O Git é uma ferramenta poderosa, mas o uso descuidado de certas flags pode levar à perda irreversível de código ou à sobrescrita do histórico compartilhado. O Claude Code possui regras embutidas de proteção contra esses erros.

```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
```

### As quatro regras de ouro de segurança do Claude Code

1. **Proibição de Force Push destrutivo:** o Claude nunca executa `git push --force` ou `-f` em branches protegidos (`main`, `master`, `release`) sem sua confirmação explícita múltipla.
2. **Staging direcionado:** o agente evita comandos cegos como `git add .` ou `git add -A`. Cada arquivo é staged pelo seu caminho exato, prevenindo vazamentos acidentais de arquivos `.env`, chaves de criptografia ou dumps locais de banco de dados.
3. **Preservação da integridade do histórico:** o agente prefere criar um novo commit corretivo em vez de modificar o histórico via `git commit --amend`, especialmente se as mudanças já tiverem sido enviadas ao servidor remoto.
4. **Respeito aos Pre-commit Hooks:** o Claude não usa a flag `--no-verify` para burlar verificações do Husky, ESLint ou Prettier. Se um hook bloquear o commit, o agente identifica a causa do erro do linter ou dos testes, corrige-a e repete a tentativa conforme as regras.

> [!WARNING]
> Nunca peça à inteligência artificial para executar comandos não verificados `git reset --hard HEAD~N` em branches compartilhados. Sempre use `git stash` ou crie um branch de backup temporário antes de mudanças massivas no histórico.

---

## 9. Workshop prático: ciclo completo do branch ao PR

Vamos percorrer todo o ciclo de trabalho do desenvolvedor em um projeto real — desde o recebimento da tarefa até o envio do código pronto para review utilizando o Claude Code.

### Passo 1. Verificação do estado e criação do branch de trabalho

Abra o terminal no seu repositório, execute `claude` e dê a tarefa:

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

O Claude certificará que o diretório de trabalho está limpo, puxará as atualizações recentes e criará um novo branch local.

### Passo 2. Implementação da tarefa

Defina a tarefa para o agente:

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

### Passo 3. Verificação e commit pontual

Após criar o arquivo, dê o comando para registrar o resultado:

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

O Claude verificará a funcionalidade, adicionará ao índice `src/components/Avatar.tsx` (junto com o arquivo de teste) e formulará o commit:

```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
```

### Passo 4. Push e abertura do Pull Request

Conclua o ciclo de trabalho com o prompt final:

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

---

## 10. Autoavaliação rápida e checklist resumido

Verifique seu nível de absorção do material com um breve teste.

### Perguntas de controle

> **1. Por que o Claude Code faz staging dos arquivos pelos seus nomes exatos em vez de executar `git add .`?**
>
> > [!TIP]
> > **Resposta:** Para prevenir a adição acidental ao repositório de dados confidenciais (`.env`), arquivos temporários do sistema (`.DS_Store`) e builds locais que possam ter sido omitidos no `.gitignore`.

> **2. Como o Claude Code decide em qual formato escrever a mensagem do commit?**
>
> > [!TIP]
> > **Resposta:** O agente analisa automaticamente os últimos commits do repositório via `git log`, adaptando-se ao estilo existente da equipe (Conventional Commits, prefixos de tickets Jira ou descrições concisas).

> **3. O que acontece se um Pre-commit Hook (Husky/ESLint) falhar com erro durante um commit via Claude?**
>
> > [!TIP]
> > **Resposta:** O Claude não burlará a verificação com a flag `--no-verify`. Em vez disso, analisará a saída do linter ou dos testes, eliminará as violações no código e executará novamente o commit seguro.

### Checklist resumido para trabalho eficiente com Git

- [ ] Use uma única frase `Commit these changes` em vez da cadeia manual de comandos `status -> add -> commit`.
- [ ] Combine a criação do branch com a tarefa de negócio em um único prompt para preservar o contexto holístico.
- [ ] Confie no Claude para a análise primária e resolução de conflitos complexos de merge após `rebase` ou `merge`.
- [ ] Sempre use `git stash` via Claude antes de trocar urgentemente para outro branch.
- [ ] Instale o `gh CLI` para delegar ao Claude a geração de descrições estruturadas para Pull Requests.