Skip to main content

Git e Workflows de Desenvolvimento

O Claude Code vive no seu terminal, tem acesso ao seu git, ao seu shell e ao seu filesystem. Quando você combina isso com o fluxo natural de desenvolvimento — branch, diff, commit, PR, CI — o resultado é um nível de integração que vai além de "IA que escreve código". Essa página cobre os padrões mais úteis pra desenvolvimento real.

Análise de Diff​

A combinação git diff | claude é uma das mais produtivas. Funciona em qualquer estágio:

# Revisar staged antes de commitar
git diff --staged | claude -p "revise esse diff por bugs, edge cases e problemas de segurança. Seja direto e específico."

# Revisar todas as mudanças não-commitadas
git diff | claude -p "esse diff está coerente? Tem algo que parece fora do lugar?"

# Comparar contra outra branch
git diff main...HEAD | claude -p "liste os arquivos de maior risco nessas mudanças e explique por quê."

# Analisar mudança específica de arquivo
git diff HEAD src/auth/jwt.ts | claude -p "essa mudança pode introduzir vulnerabilidade de autenticação?"

O --name-only é útil quando você quer primeiro entender o escopo antes de mergulhar no conteúdo:

git diff main --name-only | claude -p "dada essa lista de arquivos, qual a probabilidade de impacto em produção? Ordene por risco."

Commit Messages​

Ad-hoc​

git diff --staged | claude -p "gere uma mensagem de commit no formato Conventional Commits. Responda só a mensagem, sem explicação."

Saída esperada:

feat(auth): add refresh token rotation with 7-day expiry

Implements sliding window refresh token strategy. Old tokens are
invalidated on use and replaced with new ones. Adds cleanup job
for expired tokens older than 30 days.

Via alias Git​

git config --global alias.msg '!git diff --staged | claude -p "gere uma mensagem de commit Conventional Commits. Só a mensagem."'

Uso: git msg → copia e usa em git commit -m "...".

Via hook prepare-commit-msg​

# .git/hooks/prepare-commit-msg (ou via Husky)
#!/bin/bash

COMMIT_MSG_FILE=$1
COMMIT_SOURCE=$2

# Só roda quando não tem mensagem pré-definida (amend, merge, etc)
if [ -n "$COMMIT_SOURCE" ]; then
  exit 0
fi

# Gera sugestão baseada no diff staged
SUGGESTION=$(git diff --staged | claude -p "gere uma mensagem de commit Conventional Commits. Só a mensagem, sem markdown ou explicação.")

if [ -n "$SUGGESTION" ]; then
  echo "$SUGGESTION" > "$COMMIT_MSG_FILE"
fi

Ao abrir o editor de commit, a mensagem já está preenchida. Você edita se quiser, ou aceita.

Code Review​

Review local antes do PR​

# Review focado em segurança
git diff main | claude -p "foque apenas em problemas de segurança: autenticação, autorização, injection, dados sensíveis expostos. Ignore estilo."

# Review de qualidade geral
git diff main | claude -p "revise esse diff como um engenheiro sênior faria. Procure: lógica incorreta, edge cases não tratados, inconsistência com padrões do código ao redor, falta de tratamento de erro."

# Checklist de PR
git diff main | claude -p "gere um checklist de itens que o reviewer desse PR deveria verificar especificamente."

Review interativo na sessão​

Em vez de pipes, você pode pedir dentro da sessão interativa do Claude:

Revise as mudanças no branch atual comparado ao main. 
Foque em: lógica de negócio incorreta, tratamento de erro, e qualquer mudança de comportamento implícita.

O Claude usa Bash(git diff main) e Read nos arquivos que achar relevante examinar com mais profundidade.

GitHub Actions — Review automático em PR​

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Claude Review
        uses: anthropics/claude-code-action@v1
        with:
          claude_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          direct_prompt: |
            Revise esse PR. Foque em:
            1. Bugs e edge cases não tratados
            2. Problemas de segurança (autenticação, autorização, injection)
            3. Performance (queries N+1, operações bloqueantes no caminho crítico)
            4. Consistência com o restante do codebase
            Não elogie o que está correto. Seja direto com o que precisa de atenção.

GitLab CI/CD​

# .gitlab-ci.yml (trecho)
claude-review:
  stage: review
  only:
    - merge_requests
  script:
    - git diff $CI_MERGE_REQUEST_TARGET_BRANCH_NAME | claude -p "revise esse diff por problemas críticos. Saída em JSON: {issues: [{file, line, severity, description}]}"
  allow_failure: true

Investigação de Histórico​

Quando você precisa entender por que algo foi feito de certa forma ou quando um bug foi introduzido:

# Resumo do histórico recente de um arquivo
git log --oneline -20 src/payment/processor.ts | claude -p "resume a história de evolução desse arquivo com base nos commits."

# Identificar commit que introduziu bug
git log --oneline -30 | claude -p "temos um bug de race condition no processamento de pagamentos. Algum desses commits tem cara de ter introduzido isso?"

# Analisar commit específico
git show a3f9d12 | claude -p "o que exatamente esse commit mudou e qual o impacto potencial?"

# Blame + análise
git blame src/auth/session.ts | claude -p "quais partes desse arquivo têm o histórico mais antigo e são candidatas a refatoração?"

Resolução de Conflitos​

# Entender a origem do conflito
git diff --diff-filter=U | claude -p "explique cada conflito de merge. Para cada um, descreva o que o branch atual e o branch que está sendo merged estão tentando fazer."

# Estratégia de resolução
git diff --diff-filter=U | claude -p "para cada conflito listado, sugira a estratégia de resolução correta considerando que nosso objetivo é [descreva o objetivo do merge]."

Importante: o Claude não deve resolver conflitos automaticamente — a decisão é sempre do desenvolvedor. Mas entender o que cada lado quer fazer economiza muito tempo.

Worktrees para Desenvolvimento Paralelo​

Git worktree é uma funcionalidade nativa que permite ter múltiplos branches do mesmo repositório em diretórios separados simultaneamente. Com Claude Code, isso vira paralelismo real.

Setup básico​

# Cria worktree pra uma feature longa
git worktree add ../projeto-feature-auth feature/auth

# Cria worktree pra um hotfix urgente
git worktree add ../projeto-hotfix hotfix/payment-crash

# Lista worktrees ativos
git worktree list

Sessões Claude independentes por worktree​

# Terminal 1 — feature
cd ../projeto-feature-auth
claude -n "feature-auth"

# Terminal 2 — hotfix (em paralelo)
cd ../projeto-hotfix
claude -n "hotfix-payment"

Cada sessão tem:

  • Contexto próprio (janela de contexto separada)
  • Histórico de conversa próprio
  • CLAUDE.md do projeto (compartilhado, vem do repo)
  • CLAUDE.local.md (pode ser diferente por worktree)

Limpeza após merge​

git worktree remove ../projeto-hotfix
git worktree prune

Caso de uso real: incidente em produção durante feature de longo prazo​

# Você está trabalhando numa feature de autenticação há dias
# De repente: incidente em produção, gateway de pagamento caindo

# Sem precisar abandonar a feature:
git worktree add ../hotfix-payment hotfix/payment-gateway

cd ../hotfix-payment
claude -n "hotfix-payment"
# Claude Code começa aqui, contexto limpo, sem nada da feature de auth
# Investiga, corrige, testa, faz PR

# Depois, volta pra feature sem perder nada
cd ../projeto-feature-auth
claude --resume feature-auth

Debugging com Git​

Bisect assistido​

git bisect é poderoso mas trabalhoso. Com Claude Code na sessão:

Preciso fazer git bisect pra encontrar qual commit introduziu um bug de memory leak. 
O último commit bom que conheço é v2.3.0 (tag). Ajuda a conduzir o processo, 
testando cada commit com `node --inspect src/worker.js` e avaliando se o leak aparece.

O Claude executa o bisect step a step, roda os testes, observa output e vai marcando good/bad.

Análise de log de release​

git log v2.3.0..v2.4.0 --oneline | claude -p "identifique os commits de maior risco nessa release e explique por quê cada um pode causar problema em produção."

Útil antes de fazer deploy de uma versão nova.

Workflows de CI/CD​

Análise de falha de CI​

Quando o CI quebra e você quer contexto antes de investigar:

# Pega o log do último run via GitHub CLI
gh run view --log-failed | claude -p "identifique a causa raiz da falha. Sugira o arquivo e a linha onde começar a investigar."

Release notes automático​

git log --oneline v2.3.0..HEAD | claude -p "gere release notes em português baseado nesses commits. Agrupe por: novas funcionalidades, correções, melhorias de performance e breaking changes. Use markdown."

Auditoria de dependências​

cat package.json | claude -p "identifique dependências que: 1) provavelmente não são mais necessárias, 2) têm versões muito antigas conhecidas por vulnerabilidades, 3) poderiam ser consolidadas"

Complementa o npm audit com análise de semântica.

CLAUDE.md para Times que Usam Git Intensivamente​

Seção específica pra incluir no CLAUDE.md do projeto:

## Git

### Branch naming
- Features: `feat/<description>`
- Fixes: `fix/<description>`
- Hotfixes: `hotfix/<description>`
- Chores: `chore/<description>`

### Commit format
Conventional Commits obrigatório:
- `feat:` nova funcionalidade
- `fix:` correção de bug
- `perf:` melhoria de performance
- `refactor:` refatoração sem mudança de comportamento
- `test:` adiciona/altera testes
- `chore:` mudanças de build/CI/deps

### PR process
- Sempre contra `develop`, nunca contra `main`
- Título = commit message do squash final
- Requer 2 aprovações antes de merge
- CI deve passar — não faça merge com checks vermelhos

### O que NUNCA commitar
- `.env` com valores reais
- Tokens ou API keys (mesmo de dev)
- `console.log` de debug
- Arquivos gerados (`dist/`, `build/`, `.next/`)

### Comandos úteis que o Claude pode rodar
- `git log --oneline -20` — histórico recente
- `git diff main` — comparar com main
- `git status` — estado atual
- `gh pr list` — PRs abertos
- `gh issue list` — issues abertas

Automações Avançadas​

Skill de fix-issue completo​

.claude/skills/fix-issue/SKILL.md:

---
name: fix-issue
description: Resolve uma issue do GitHub do começo ao fim
disable-model-invocation: true
allowed-tools: Bash(gh *) Bash(git *) Bash(npm test) Bash(npm run lint) Read Write Edit Glob Grep
---

Resolva a issue do GitHub #$ARGUMENTS:

1. `gh issue view $ARGUMENTS` — leia os detalhes completos
2. Entenda o problema e pergunte se algo não estiver claro
3. Busque os arquivos relevantes no codebase
4. Implemente a correção
5. Escreva testes que cobrem o caso reportado
6. Rode `npm test` — corrija qualquer falha
7. Rode `npm run lint` — corrija qualquer aviso
8. `git add` nos arquivos modificados
9. Gere mensagem de commit Conventional Commits e confirme comigo antes de commitar
10. `git push` e abre o PR com `gh pr create`

Uso: /fix-issue 1234

Skill de PR review​

.claude/skills/pr-review/SKILL.md:

---
name: pr-review
description: Faz review detalhado de um PR
context: fork
agent: Explore
allowed-tools: Bash(gh *) Bash(git *) Read Glob Grep
---

## Contexto do PR #$ARGUMENTS
- Diff: !`gh pr diff $ARGUMENTS`
- Commits: !`gh pr view $ARGUMENTS --json commits -q '.commits[].messageHeadline'`
- Arquivos: !`gh pr diff $ARGUMENTS --name-only`
- Descrição: !`gh pr view $ARGUMENTS --json body -q '.body'`

## Sua tarefa

Faça um review completo desse PR. Verifique:

1. **Correção**: a implementação resolve o que a PR diz que resolve?
2. **Edge cases**: há cenários não tratados?
3. **Segurança**: autenticação, autorização, injection, dados sensíveis?
4. **Performance**: queries N+1, operações bloqueantes, alocação de memória desnecessária?
5. **Consistência**: segue os padrões do codebase? Leia os arquivos adjacentes para comparar.
6. **Testes**: os testes cobrem os casos relevantes? Faltam cenários?

Organize o feedback por severidade: crítico, importante, sugestão.

Uso: /pr-review 456

Loop de verificação contínua​

Útil quando você está desenvolvendo e quer validação constante:

/loop 3m "rode npm test e me avise se algum teste novo quebrou. Se quebrou, identifique a causa provável."

A cada 3 minutos o Claude roda os testes e reporta. Você fica focado no código sem precisar trocar de contexto pra ver o CI.

Integração com Ferramentas CLI​

O Claude Code já sabe usar CLIs comuns que você tem instaladas:

# GitHub CLI
gh issue list | claude -p "qual issue tem maior impacto técnico pra resolver primeiro?"
gh pr list | claude -p "tem algum PR que parece bloqueado ou precisando de ação?"

# AWS CLI (em sessão interativa)
aws cloudwatch get-metric-statistics ... | claude -p "o que esses números dizem sobre a saúde da aplicação?"

# Kubernetes
kubectl get pods | claude -p "tem algum pod em estado problemático?"
kubectl logs deployment/api --tail=100 | claude -p "tem alguma anomalia nesses logs?"

CLIs são mais eficientes que MCP pra maioria desses casos: não adicionam tool listing no contexto e usam suas credenciais locais.

Conclusão​

Git + Claude Code não é só conveniência. É uma mudança de como você interage com o histórico do projeto, com o processo de review, e com o ciclo de deploy. Os padrões aqui não exigem mudanças drásticas no workflow — você vai adicionando um por vez e vendo o que funciona no seu contexto.

A regra que eu sigo: se eu me pego fazendo a mesma operação de git + análise mais de três vezes, eu transformo num alias, num hook ou numa skill. O objetivo é que o fluxo mental fique limpo pra o que importa.

Próximo: Recursos e Próximos Passos

Referências: