Tutorial 4 Prompting and Reviewing pt

Tutorial 4 · Prompts e Revisão

Meta: a meta-habilidade. Você já consegue construir uma funcionalidade com um agente — este capítulo é sobre fazer isso de forma tranquila e repetível: escrever prompts que acertam de primeira, revisar diffs com eficiência, iterar quando as coisas dão errado, e manter o ritmo entre sessões.

← Anterior: Tutorial 3 Sua Primeira Tarefa com o Agente · Próximo: Tutorial 5 Localização

---

Crie prompts como um líder, não como uma caixa de busca

O agente é um engenheiro júnior rápido, literal e entusiasmado. Lidere-o como você lideraria um bom engenheiro júnior:

• Declare o objetivo e as restrições. "Adicione endorse" é fraco. "Adicione endorse seguindo o padrão do connect, apenas RNG com semente, com testes, barreira continua verde" é forte. Restrições são como você consegue código que se encaixa.
• Aponte para exemplos. "Siga o padrão usado por renderConnect" supera um parágrafo de descrição. O código existente é a melhor especificação.
• Peça um plano antes de editar em qualquer coisa não trivial. É barato redirecionar um plano; é caro desfazer dez arquivos editados.
• Uma tarefa por prompt. Empacotar "adicione endorse, também refatore o RNG, também atualize o README" produz um diff emaranhado e difícil de revisar.
• Dê a ele a barreira de testes. "Rode npm test e não considere pronto até estar verde" transforma o agente em algo que verifica o próprio trabalho.

Revise o diff sempre

Velocidade é o ponto todo de um agente — mas velocidade sem leitura é como bugs são publicados. Construa um reflexo de revisão rápido e consistente:

1. Escopo: ele mudou só o que deveria? Linhas não relacionadas que se moveram são um sinal de alerta.
2. Padrões: combina com o código ao redor, sem dependências novas nem entrada/saída dentro de src/?
3. As regras do projeto: para este repositório, isso é apenas RNG com semente (procure Math.random no diff), texto visível ao usuário nos bundles de idioma (não incrustado), e linhas de cartão nunca excedem a largura para a qual o layout ajusta.
4. Acessibilidade: a saída nova sobrevive a --accessible? Rode lockedin --accessible <your command> e verifique que ela é lida como texto plano e limpo — sem novos glifos decorativos escapando do a11yFilter.
5. Testes: há um teste novo, e ele de fato falharia se a funcionalidade quebrasse? Pergunte: "Que linha eu mudaria para fazer este teste novo falhar?"
6. Rode: npm test, depois rode o comando e olhe a saída.

Você não precisa entender cada caractere — mas precisa entender cada decisão. Se não consegue explicar uma mudança, peça ao agente para explicar antes de aceitá-la.

Itere quando não estiver verde

Uma barreira vermelha é um passo normal, não um fracasso. O ajuste é feedback preciso:

"npm test falha com: [paste the exact error]. O teste de largura do renderEndorse espera que cada linha do cartão tenha ≤ 60 colunas visíveis. Corrija sem enfraquecer o teste."

Cole o texto real do erro. "Está quebrado" faz o agente adivinhar; o stack trace faz ele corrigir. E prefira continuar a mesma conversa em vez de começar do zero — o agente já tem o contexto do que acabou de escrever. Se duas ou três iterações não convergirem, dê um passo atrás e replaneje: a tarefa pode ser grande demais para um prompt só.

Mantenha o ritmo entre sessões

Trabalho de verdade abrange mais de uma sessão. Dois hábitos mantêm um agente eficaz ao longo do tempo:

• Memória / convenções. Se seu agente suporta memória durável ou um arquivo de instruções do projeto, registre ali as regras que ele deve sempre seguir (por exemplo, "toda aleatoriedade deve usar pick/shuffle", "rode npm test antes de declarar concluído"). Você declara uma convenção uma vez em vez de em cada prompt.
• Uma nota de handoff. Este repositório mantém um documento de status curto e higienizado em docs/HANDOFF.md: o que o projeto é, como é construído, como é testado e o que vem a seguir. Quando você voltar (ou passar o trabalho para um colega — ou outro agente), essa nota reconstrói o contexto em segundos. Peça ao seu agente para mantê-la atualizada como parte de uma mudança.

Salvaguardas que vale a pena manter

• A barreira não é negociável. Testes verdes antes de qualquer coisa ser publicada. É isso que te permite se mover rápido e confiar na saída.
• Você é o revisor de registro. O agente escreve; você decide. Aceitar um diff significa que você garante por ele.
• Passos pequenos e verificáveis superam um salto gigante. Cada mudança aceita deve deixar o app funcionando.

---

✅ Experimente com seu agente

1. Escreva uma especificação de um parágrafo para um comando mentor ("distribui conselhos não solicitados"), incluindo restrições, e faça o agente construí-lo com testes primeiro — plano, testes, código, barreira — revisando em cada passo.
2. Peça ao agente para atualizar o docs/HANDOFF.md mencionando o comando novo.
3. Quebre algo de propósito (por exemplo, apague uma entrada de um pool), rode npm test, e pratique passar ao agente a falha exata para corrigir.

---

Para onde ir a seguir

• Passe os olhos pelo código real em src/lockedin.js — agora você já conhece a forma dele.
• Leia docs/HANDOFF.md para as notas de status e arquitetura do próprio projeto.
• Aproveite as piadas na Referência de Comandos.

Esse é o tutorial. Você já consegue direcionar um agente de IA para construir e mudar software de verdade atrás de uma barreira de testes — usando o exemplo mais confiante imaginável. Concorda? 👇