Pair programming com Claude Code: acelere com IA sem perder o controle

Fazer pair programming com Claude Code não é entregar todo o desenvolvimento para a IA. O fluxo que funciona melhor é mais controlado: a pessoa define objetivo, limites e critérios de aceite; Claude Code explora o repositório, propõe um plano, faz mudanças pequenas, executa verificações e ajuda a preparar a revisão.

A documentação oficial de Claude Code overview descreve Claude Code como uma ferramenta de codificação agêntica capaz de ler o codebase, editar arquivos, executar comandos e se integrar a ferramentas de desenvolvimento. Isso é poderoso, mas também torna prompts vagos mais perigosos. Se você pede apenas “melhore isso”, a ferramenta pode avançar rápido na direção errada.

Este guia é a continuação prática do guia de introdução ao Claude Code. O foco é transformar uso diário em um processo repetível para bugs, testes, refactors pequenos e pull requests.

Defina os papéis antes de codar

Antes de pedir uma implementação, decida quais decisões continuam humanas. Claude consegue ler muitos arquivos e escrever código rapidamente, mas não deve redefinir intenção de produto, fronteiras de segurança ou critérios de merge sem você.

Área	Responsabilidade humana	Responsabilidade do Claude Code
Objetivo	Dizer o que muda e o que não muda	Encontrar arquivos e caminhos possíveis
Pesquisa	Definir o escopo de leitura	Ler código, testes, diff e logs
Implementação	Aprovar tamanho e risco do diff	Fazer mudanças pequenas e focadas
Verificação	Definir sinal de sucesso ou falha	Rodar testes, lint, build ou screenshots
Revisão	Decidir se pode fazer merge	Listar riscos, testes faltantes e alternativas

Com essa divisão, Claude Code vira um par produtivo, não um substituto sem supervisão. Para iniciantes, também é melhor para aprender: comece por um bug, um arquivo de teste ou um componente antes de pedir uma feature inteira.

Prepare o repositório nos primeiros 10 minutos

Preparação costuma mudar mais o resultado do que um prompt bonito. As Claude Code best practices recomendam dar a Claude um caminho de verificação e separar exploração, planejamento, implementação e checagem. No dia a dia, uso três regras.

Primeiro, trabalhar em uma branch ou worktree, não diretamente na main. Segundo, manter um CLAUDE.md curto. A memory documentation explica que CLAUDE.md é carregado no início de cada sessão como instrução persistente. Terceiro, informar os comandos que provam que a mudança funciona.

# CLAUDE.md

## Project rules
- Before editing, summarize the files you plan to inspect.
- Prefer small diffs and explain risky changes before applying them.
- After code edits, run `npm run lint` and the narrowest relevant test.
- Do not read `.env*` files or change deployment settings without approval.

## Common commands
- `npm run lint`
- `npm run test`
- `npm run build`

Não transforme CLAUDE.md em uma enciclopédia. Quanto maior ele fica, mais as regras importantes se perdem. Procedimentos repetitivos podem virar Skills, que são carregadas apenas quando fazem sentido.

Use o ciclo explorar, planejar, implementar e verificar

O erro mais comum é pedir “implemente isso” antes de Claude entender o código existente. Um ciclo mais seguro é:

flowchart LR
  A[Descrever objetivo] --> B[Explorar arquivos relevantes]
  B --> C[Revisar plano]
  C --> D[Editar em passos pequenos]
  D --> E[Rodar checks e ler diff]
  E --> F{Passou?}
  F -- Não --> C
  F -- Sim --> G[Resumir para PR]

O primeiro prompt não precisa ser longo, mas deve incluir objetivo, escopo, proibições e verificação.

Objetivo: corrigir o erro 500 na página de perfil após login.
Escopo: começar por `src/auth` e `src/pages/profile`.
Não fazer: mudar a estratégia de autenticação, alterar schema de DB ou ler `.env`.
Processo: leia os arquivos relevantes, liste 3 causas prováveis e mostre um plano antes de editar.
Verificação: execute os testes de auth existentes e `npm run lint`.

Quando Claude propuser um plano, reduza antes de permitir edição.

O plano é razoável, mas escreva primeiro apenas o teste de reprodução.
Confirme que ele falha antes de alterar código de produção.
Depois proponha mudanças de produção um arquivo por vez.

Isso combina bem com TDD, ou desenvolvimento guiado por testes. A vantagem prática é simples: um teste falhando torna o problema visível e deixa a correção mais fácil de revisar.

Um exemplo pequeno para executar

Pratique com uma função pequena antes de mexer em código crítico. Salve o arquivo abaixo como pair-check.test.ts e rode com Vitest.

import { describe, expect, it } from "vitest";

type ClaudeMode = "direct" | "plan-first" | "human-review";

export function decideClaudeMode(input: {
  changedFiles: number;
  touchesSecrets: boolean;
  hasReliableTests: boolean;
}): ClaudeMode {
  if (input.touchesSecrets) return "human-review";
  if (input.changedFiles > 3) return "plan-first";
  if (!input.hasReliableTests) return "plan-first";
  return "direct";
}

describe("decideClaudeMode", () => {
  it("allows direct work for small, well-tested changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("direct");
  });

  it("requires a plan for broad changes", () => {
    expect(
      decideClaudeMode({
        changedFiles: 5,
        touchesSecrets: false,
        hasReliableTests: true,
      }),
    ).toBe("plan-first");
  });

  it("requires human review for secret-related work", () => {
    expect(
      decideClaudeMode({
        changedFiles: 1,
        touchesSecrets: true,
        hasReliableTests: true,
      }),
    ).toBe("human-review");
  });
});

npm install -D vitest typescript
npx vitest run pair-check.test.ts

Depois peça a Claude Code para adicionar uma regra: “se tocar billing, exigir human-review”. Peça que adicione o teste primeiro, confirme a falha, implemente a regra e rode Vitest novamente. O exercício é pequeno, mas treina a mesma disciplina usada em handlers de API, componentes React e scripts de migração.

Quatro casos de uso úteis

O primeiro caso é adicionar uma condição pequena a uma funcionalidade existente, como “ocultar exportação CSV para contas gratuitas”. Isso força a verificar UI, permissões e testes sem redesenhar o produto.

O segundo caso é investigação de bugs. Cole erro, passos de reprodução e comportamento esperado. A página oficial Common workflows recomenda fornecer comandos de reprodução e stack traces para guiar Claude até a causa raiz.

O terceiro caso é expansão de testes. Faça Claude ler o estilo de testes existente e depois peça casos de sucesso, sem permissão, entrada inválida e dados vazios. Para sistematizar, combine com o testing strategies guide.

O quarto caso é a auto-revisão antes do PR. Peça para Claude ler git diff e priorizar segurança, compatibilidade, testes faltantes e nomes confusos. A documentação do GitHub sobre pull request reviews mostra como comentários, aprovações e pedidos de mudança protegem a qualidade. Claude Code prepara a revisão humana, mas não a substitui.

Armadilhas concretas e como evitar

Armadilha	O que acontece	Hábito mais seguro
“Melhore isso”	Refactors não solicitados entram	Definir escopo, não objetivos e aceite
Diff grande demais	Revisão fica lenta e bugs se escondem	Uma tarefa, um diff, um plano
Sem verificação	A mudança só parece pronta	Exigir testes, lint, build ou screenshot
CLAUDE.md gigante	Regras importantes ficam escondidas	Mover procedimentos para Skills
Permissões amplas	Secrets ou produção ficam acessíveis	Usar permissões e hooks

O risco silencioso é fadiga de aprovação. Se tudo pede confirmação, as pessoas aprovam no automático. Se quase tudo está liberado, um prompt ruim pode ir longe demais. A regra prática é confiança alta para trabalho reversível e atrito alto para trabalho irreversível. Veja padrões no approval and sandbox guide.

Transforme a sessão em um PR revisável

Em equipe, não deixe o valor preso no chat. Termine pedindo um resumo de pull request.

Resuma este diff para uma pull request.
Inclua:
- Por que a mudança foi feita
- Arquivos principais alterados
- Comandos de verificação e resultados
- Riscos que revisores devem olhar com atenção
- Áreas deixadas fora de propósito

Claude pode escrever o rascunho, mas a versão final deve ser humana. Em segurança, pagamentos, privacidade e exclusão de dados, confiança do modelo não é evidência. Evidência é diff, saída dos testes, logs e discussão de revisão.

Resultado ao testar o fluxo

Quando Masa usou este ciclo em uma pequena correção Next.js, a revisão foi mais rápida do que com um prompt simples de “implemente isso”. O motivo não foi código perfeito. O primeiro prompt limitou arquivos, declarou proibições e exigiu lint mais testes. Claude Code tocou menos arquivos irrelevantes e deixou a verificação na conversa. Em mudanças visuais com poucos testes, revisão humana ainda foi necessária. A conclusão é direta: pair programming com Claude Code não é delegar responsabilidade, é desenhar qual parte da responsabilidade pode ser delegada.

Na próxima sessão, escolha uma tarefa pequena e siga explorar, planejar, implementar e verificar. Para prompts compartilhados e critérios de revisão em equipe, veja ClaudeCodeLab training.