SKIP TO CONTENT

This text is written in Portuguese.

Como trabalho com o Claude Code

O fluxo que uso em qualquer repositório: entrevista antes de codar, protótipo descartável, spec, tickets, implementação com teste e revisão em contexto novo.

On this note

Não uso o Claude Code como um autocomplete grande. Uso como um colega que executa rápido e que, sem direção, executa rápido a coisa errada. O método abaixo existe para tirar a direção da minha cabeça e colocá-la num lugar onde eu consiga revisar antes de qualquer linha de código.

Ele vem dos skills do mattpocock/skills, instalados de forma global em ~/.claude/skills/. Valem para qualquer projeto que eu abra, não para um repositório específico. Este texto é um registro vivo. Quando um passo deixa de fazer sentido, eu troco.

O fluxo

Para trabalho que não é trivial, a ordem é esta.

  1. Entrevista. O /grill-me me interroga sobre o plano até cada ramo da árvore de decisão estar resolvido. A pergunta que mais economiza tempo é a que eu não sabia que precisava responder.
  2. Protótipo. Quando a dúvida é "esse modelo de estado está certo?" ou "qual dessas telas é a certa?", o /prototype constrói algo descartável. Um app de terminal para testar lógica, ou várias rotas lado a lado para comparar interface. Ninguém se apega a um protótipo.
  3. Mapa. Para o que não cabe numa sessão, o /wayfinder quebra o esforço em tickets de decisão no issue tracker. É planejamento. Não entrega código, entrega decisões.
  4. Spec. O /to-spec sintetiza a conversa numa especificação e publica no tracker. Sem nova entrevista, só o que já foi decidido.
  5. Tickets. O /to-tickets fatia a spec em tickets "tracer bullet", cada um atravessando todas as camadas e declarando o que o bloqueia.
  6. Implementação. O /implement constrói o que os tickets descrevem. Roda TDD nos pontos combinados, roda typecheck e testes, e termina com revisão antes do commit.
  7. Revisão em contexto novo. O /code-review abre dois sub-agentes em paralelo. Um confere se o código segue os padrões documentados do repositório. O outro confere se entrega o que a issue pediu. Eles não herdam a conversa de implementação, e é por isso que funcionam.

Por que a revisão precisa de contexto novo

Quem implementou carrega as justificativas. Se eu peço a mesma sessão para revisar o próprio trabalho, ela encontra razões para cada escolha que fez. Um revisor que só recebe o diff e a spec não tem essas razões e acha o que ficou fora do lugar.

Um caso inteiro: o vídeo wall do matrix-rain

O matrix-rain ganhou o modo vídeo wall, em que vários terminais viram uma tela só. Foi o trabalho em que mais segui o fluxo à risca, e o repositório guarda cada etapa.

  1. Protótipo
  2. Spec (#14)
  3. Prefactor (#15)
  4. Tracer bullet (#16)
  5. Camadas (#17 a #21)
  6. Revisão final (#22)
Oito tickets filhos da mesma spec, cada um bloqueado pelo anterior que ele precisa.

Protótipo primeiro. Antes de escrever qualquer spec, um protótipo descartável validou o modelo: um terminal vira host, roda a simulação no canvas inteiro e cada tile mostra a sua fatia. O veredito, escrito na própria spec, foi que com a posição declarada os terminais lado a lado parecem uma tela só, e que a única coisa que sobra é a moldura entre as janelas. O protótipo ficou numa branch e não entrou no código final.

Spec depois. A issue #14 tem o problema, a solução, 37 histórias de usuário e uma seção de decisões de implementação. Duas delas mostram o tipo de decisão que a entrevista força a tomar antes do código:

  • O frame é enviado inteiro a cada quadro, sem diferença entre quadros. Se aparecer lag, vira um ticket separado.
  • O formato de mensagem é JSON em linhas, porque funciona em Python 3.6 e não depende de versão. O risco fica registrado: o custo de CPU do JSON para frames de milhares de células. Se pesar na medição, a troca é uma decisão pequena e contida.

Fatias verticais. O #15 é um prefactor, sem comportamento novo: o App ganha a noção de canvas virtual e o Screen ganha o método de ser fatiado. O #16 é o tracer bullet, o menor wall que funciona, ainda feio. Os cinco tickets seguintes acrescentam uma coisa cada. Posição em grade com --at, entrar e sair com a tecla J, modo de layout, intervalo entre janelas e sucessão de host.

Revisão em contexto novo. Cada ticket passou por revisão antes de entrar, e os commits de correção dizem o que foi achado:

  • #16: eleição de host com flock, limites de tamanho e de buffer.
  • #18: a constante SNAPSHOT_KEYS, os rótulos do painel e a precisão do README e do AGENTS.md.
  • #21: um limite máximo de rank e um prazo medido com relógio monotônico.
  • #22: vazamento de listener e de socket, e a medição do custo do JSON, que deu 7 ms para 11 mil células contra um orçamento de 30 ms.

Onde o método falha

Ele pesa para coisa pequena. Para renomear uma variável, entrevista é teatro, e eu pulo direto para a edição. A regra que uso é simples: se existe uma decisão em aberto que custaria caro desfazer, começo pela entrevista. Se não existe, só faço.

O segundo ponto fraco é o contrário. Uma spec bem escrita dá a sensação de que o problema está resolvido, e a sensação engana. O protótipo existe para lembrar que o terreno ainda pode discordar do mapa.

Esse último ponto não é exclusivo de engenharia. Eu o escrevi com mais calma em Menos estátuas, mais mapas.

Como trabalho com o Claude Code