Workflow Git com Claude Code: branches limpas, commits pequenos, CI e passagem de contexto

Quanto mais rápido o Claude Code escreve, mais disciplinado o Git precisa ser. A IA consegue produzir um diff útil em minutos, mas também pode misturar arquivos sem relação, criar commits grandes demais, resolver conflitos sem entender a intenção ou fazer push antes de rodar verificações locais.

Este guia mostra um workflow Git prático para uso solo e em equipe com Claude Code: loop de branch limpa, commits pequenos, ponto de revisão, higiene do worktree, conflitos, rollback seguro, CI antes do push e passagem de contexto diária. Também explicamos staging, commit e rebase de forma simples.

Git sem complicar

Working tree é a área onde os arquivos estão sendo editados. O Claude Code escreve ali. Staging area é a “cesta do próximo commit”: git add não salva tudo para sempre; ele escolhe o que entrará no próximo commit.

Um commit é um retrato nomeado das mudanças em staging. Um bom commit é pequeno e tem um motivo claro. Rebase pega os commits da sua branch e os recoloca em cima do main atualizado. O histórico fica mais limpo, mas reescrever uma branch já compartilhada pode atrapalhar outras pessoas.

Claude Code não deve ser apenas gerador de código. No workflow correto, ele também lê o diff, sugere o que colocar em staging, prepara a mensagem de commit, explica conflitos, roda checks locais e deixa uma passagem de contexto.

flowchart LR
  A["Definir objetivo"] --> B["Atualizar main e criar branch"]
  B --> C["Implementar fatia pequena"]
  C --> D["Ler diff e escolher staging"]
  D --> E["Review gate e CI local"]
  E --> F["Commit pequeno"]
  F --> G["Rebase ou PR"]
  G --> H["Handoff e rollback"]

Branch limpa antes da implementação

Antes de pedir edições, deixe o estado do repositório claro. “Limpo” não significa sempre zero mudanças; significa que não há mudanças fora do escopo misturadas.

git status --short
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c feature/checkout-coupon-validation
git status --short

No PowerShell, uma branch com data ajuda quando há várias sessões.

$topic = "checkout-coupon-validation"
$date = Get-Date -Format "yyyyMMdd"
git fetch origin
git switch main
git pull --ff-only origin main
git switch -c "feature/$date-$topic"
git status --short

O primeiro prompt deve limitar o escopo.

Goal: add coupon expiry validation to checkout.
Scope: edit only src/checkout, src/coupons, and matching tests.
Do not stage, commit, push, or edit unrelated files.
Before editing, read package.json and existing checkout tests.
After editing, show git diff --stat and the exact test commands you ran.

Masa viu esse problema no ClaudeCodeLab: uma tarefa de artigo acabava trazendo rascunhos de produto, scripts locais ou relatórios temporários. Mesmo com build verde, o diff ficava difícil de explicar. Declarar o que está fora do escopo evita muito retrabalho.

Staging intencional e commits pequenos

git add -A é prático, mas amplo demais para trabalho com IA. Ele pode incluir arquivos temporários, configuração local e mudanças de outra tarefa.

git diff --stat
git diff
git add src/checkout/validateCoupon.ts
git add tests/checkout/validateCoupon.test.ts
git diff --staged --stat
git diff --staged

Use mensagens claras.

git commit -m "feat(checkout): validate coupon expiry before payment"

Quando houver impacto em leitores, usuários ou receita, adicione um corpo.

git commit -m "fix(content): keep Claude Code Git workflow CTA localized" -m "Updates the localized article body, internal links, and review checklist so translated pages follow the same Git workflow."

Peça ao Claude Code apenas a sugestão.

Read only the staged diff.
Propose one Conventional Commits message.
Do not run git commit.
Mention the user impact in the body if the change affects readers or customers.

Regras no CLAUDE.md

CLAUDE.md é o manual operacional do Claude Code dentro do projeto.

# Claude Code Git rules

- Start every coding task with `git status --short` and report unrelated dirty files.
- Do not run `git add -A`, `git commit`, `git push`, `git reset --hard`, or `git clean -fd` unless the user explicitly asks.
- Keep commits small: one behavior change, one test update, or one content slug at a time.
- Before proposing a commit, show `git diff --stat` and `git diff --staged --stat`.
- If a conflict appears, explain both sides before editing the conflicted file.
- Run the closest local checks before push: lint, typecheck, test, build, or article metadata checks.
- Leave a handoff note with changed files, commands run, failing checks, and rollback option.

Em equipe, adicione um hook para bloquear comandos Git perigosos. Hooks do Claude Code são comandos definidos pelo usuário que rodam em eventos do ciclo de vida.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "node .claude/hooks/block-dangerous-git.mjs"
          }
        ]
      }
    ]
  }
}

// .claude/hooks/block-dangerous-git.mjs
import process from "node:process";

let raw = "";
for await (const chunk of process.stdin) raw += chunk;

const input = JSON.parse(raw || "{}");
const command = input.tool_input?.command ?? "";

const blocked = [
  /git\s+reset\s+--hard\b/,
  /git\s+clean\s+-[^\s]*f/,
  /git\s+push\s+--force(?!-with-lease)/,
  /git\s+checkout\s+--\s+\./,
  /git\s+restore\s+\.\b/
];

if (blocked.some((pattern) => pattern.test(command))) {
  process.stderr.write(`Blocked risky Git command: ${command}\n`);
  process.exit(2);
}

Hook não substitui review e CI. Ele apenas reduz acidentes previsíveis.

CI local antes do push

Crie um preflight que rode os scripts existentes.

// scripts/claude-git-preflight.mjs
import { execSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

const run = (command) => {
  console.log(`\n$ ${command}`);
  execSync(command, { stdio: "inherit", shell: true });
};

run("git diff --check");
run("git diff --cached --check");
run("git status --short");

const pkg = existsSync("package.json")
  ? JSON.parse(readFileSync("package.json", "utf8"))
  : { scripts: {} };

for (const script of ["lint", "typecheck", "test", "build"]) {
  if (pkg.scripts?.[script]) run(`npm run ${script}`);
}

node scripts/claude-git-preflight.mjs

Prompt:

After implementation, run the local preflight.
If a command fails, stop and explain the first failing command, likely cause, and smallest next fix.
Do not push until the preflight is green.

pre-commit e GitHub Actions

pre-commit roda checks antes de criar o commit.

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: git-diff-check
        name: git diff whitespace check
        entry: git diff --check
        language: system
        pass_filenames: false
      - id: npm-test
        name: npm test when available
        entry: node scripts/claude-git-preflight.mjs
        language: system
        pass_filenames: false

python -m pip install pre-commit
pre-commit install
pre-commit run --all-files

No PR, repita os checks com GitHub Actions.

# .github/workflows/claude-code-pr-gate.yml
name: Claude Code PR Gate

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: git diff --check origin/main...HEAD
      - run: npm run lint --if-present
      - run: npm run typecheck --if-present
      - run: npm test --if-present
      - run: npm run build --if-present

Conflitos, rebase e rollback

Conflito significa que o Git não sabe escolher entre duas mudanças. Peça ao Claude Code para explicar os dois lados antes de editar.

git fetch origin
git rebase origin/main
git status --short
git diff --name-only --diff-filter=U

We are in a rebase conflict.
For each conflicted file, explain what our branch changed and what origin/main changed.
Resolve only after explaining the business intent.
After editing, run the narrowest relevant test.
Do not continue the rebase until I approve the resolved diff.

git add src/checkout/validateCoupon.ts
npm test -- --runInBand validateCoupon
git rebase --continue

Se parecer errado:

git rebase --abort

Para commits compartilhados, prefira git revert.

git log --oneline -5
git revert --no-edit HEAD
git status --short

Para arquivos sem commit:

git restore --staged src/checkout/validateCoupon.ts
git restore src/checkout/validateCoupon.ts

Casos de uso e falhas

Uso 1: feature solo. Crie feature/yyyyMMdd-topic, limite arquivos e testes, mantenha um comportamento por commit e rode preflight antes do push.

Uso 2: PR em equipe. A sessão de implementação não cria commits. A sessão de review lê apenas o staged diff. Uma pessoa valida título, CI, risco e rollback.

Uso 3: conteúdo e produto. No ClaudeCodeLab, artigos, links Gumroad, CTA de treinamento e links internos afetam receita. Trabalhe por slug e locale, verificando description, hero, CTA, links e localização.

Uso 4: refactor longo. Primeiro testes, depois implementação interna, por último remoção.

Falha	Causa	Prevenção
`git add -A` inclui arquivos fora do escopo	A IA alterou arquivos demais	Adicionar por caminho
Commit gigante	Muitos assuntos juntos	Um objetivo por commit
Conflito mal resolvido	Intenção não foi entendida	Explicar ours/theirs
Push perigoso após rebase	Histórico divergiu	`--force-with-lease` com regra de equipe
PR vermelho	Sem check local	Preflight
Rollback destrutivo	`reset --hard`	`git revert` para commit compartilhado

Passagem de contexto diária

## Handoff: 2026-06-02

Branch: feature/20260602-checkout-coupon-validation
Goal: validate coupon expiry before payment authorization

Changed:
- src/checkout/validateCoupon.ts
- tests/checkout/validateCoupon.test.ts

Checks:
- npm run lint: passed
- npm test -- --runInBand validateCoupon: passed
- npm run build: not run, no UI/build config touched

Risk:
- Coupon timezone boundary still needs one integration test.

Rollback:
- Revert commit `abc1234` if production checkout rejects valid coupons.

Próximo passo

Se você trabalha sozinho, comece pelo cheatsheet gratuito de Claude Code. Para prompts reutilizáveis, regras CLAUDE.md e modelos de review, veja os produtos ClaudeCodeLab. Para equipes que precisam adaptar branches, CI, permissões, rollback e passagem de contexto a um repositório real, use treinamento e consultoria Claude Code.

Resultado na prática

Aplicado ao ClaudeCodeLab, esse loop reduziu a review de “reler tudo” para verificar slug, locale, metadados, CTA e escopo do diff. git diff --staged --stat e a passagem de contexto foram os maiores ganhos porque mostram o que foi realmente verificado.