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.
- Entrevista. O
/grill-meme 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. - Protótipo. Quando a dúvida é "esse modelo de estado está certo?" ou "qual dessas telas é a certa?", o
/prototypeconstró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. - Mapa. Para o que não cabe numa sessão, o
/wayfinderquebra o esforço em tickets de decisão no issue tracker. É planejamento. Não entrega código, entrega decisões. - Spec. O
/to-specsintetiza a conversa numa especificação e publica no tracker. Sem nova entrevista, só o que já foi decidido. - Tickets. O
/to-ticketsfatia a spec em tickets "tracer bullet", cada um atravessando todas as camadas e declarando o que o bloqueia. - Implementação. O
/implementconstrói o que os tickets descrevem. Roda TDD nos pontos combinados, roda typecheck e testes, e termina com revisão antes do commit. - Revisão em contexto novo. O
/code-reviewabre 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.
- Protótipo
- Spec (#14)
- Prefactor (#15)
- Tracer bullet (#16)
- Camadas (#17 a #21)
- Revisão final (#22)
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 doAGENTS.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.