Tutorial 3 Your First Agent Task pt BR

Tutorial 3 · Sua Primeira Tarefa com o Agente

Meta: adicionar um comando totalmente novo à CLI — de ponta a ponta — direcionando seu agente. Vamos adicionar lockedin endorse: ele endossa completos estranhos por habilidades que quase certamente eles não têm. Na marca.

Este é o coração do tutorial. Você vai praticar o ciclo de verdade: especificação → testes → implementação → barreira verde → revisão.

← Anterior: Tutorial 2 Como o Código Funciona · Próximo: Tutorial 4 Prompts e Revisão

---

Passo 0 — Decida como é o "pronto"

Antes de escrever qualquer prompt, escreva você mesmo a especificação em linguagem simples. Pedidos vagos geram código vago — vindo de um humano ou de um agente.

endorse imprime de 5 a 7 linhas, cada uma endossando uma pessoa escolhida aleatoriamente (reutilize o pool NAMES existente) por uma habilidade de jargão corporativo escolhida aleatoriamente (um pool novo). Termina com uma frase de efeito satírica. Deve ser acessível como lockedin endorse, como o /endorse dentro da sessão, e aparecer em help. Toda a aleatoriedade deve usar os helpers com semente pick/ shuffle para que a saída permaneça determinística. npm test deve continuar verde, e deve haver um teste novo que fixe pelo menos uma invariante.

Esse parágrafo é o que você vai entregar ao agente. Note que ele nomeia as restrições do Capítulo 2 (RNG com semente, a barreira de testes, o hábito das invariantes).

Passo 1 — Peça ao agente para planejar, não codificar

Comece pedindo um plano. Esta é sua chance de pegar uma abordagem ruim antes que qualquer arquivo mude.

"Quero adicionar um comando endorse ao LockedIn CLI. Aqui está a especificação: [paste your spec]. Antes de escrever código, me diga quais arquivos você vai mudar e sua abordagem, para que eu aprove. Siga os padrões existentes de um comando como connect."

Um bom plano menciona: um pool SKILLS novo + um renderEndorse() em src/lockedin.js, conectá-lo em dispatch() e handleSlash(), adicionar uma linha em renderHelp(), exportar a nova função/pool, e adicionar testes em ambos os arquivos de teste. Se o plano perder a regra do RNG com semente ou os testes, diga isso agora.

Passo 2 — Testes primeiro

Peça ao agente para escrever os testes antes da implementação. Testes primeiro transformam sua especificação em algo executável, e mantêm o agente honesto.

"Ótimo. Primeiro, adicione apenas testes que falham: um teste unitário de que renderEndorse() retorna texto mencionando uma habilidade conhecida e pelo menos 5 endossos, e um teste em cli.test.js de que lockedin endorse sai com 0 e imprime um endosso. Use uma semente fixa. Não implemente renderEndorse ainda — vamos ver os testes falharem primeiro."

Rode-os e observe-os falhar pelo motivo certo (a função ainda não existe):

npm test

Passo 3 — Deixe o agente implementar

Agora dê sinal verde para a implementação:

"Agora implemente para que esses testes passem, seguindo o padrão do connect. Adicione um pool SKILLS de ~25 habilidades de jargão corporativo, um renderEndorse() que retorna uma string, conecte dispatch e handleSlash, adicione uma linha em help, e exporte o que você adicionou. Use apenas pick/shuffle para a aleatoriedade."

O que o agente produzir deve se parecer bastante com o resto do arquivo. Por exemplo, um pool SKILLS e um renderizador:

const SKILLS = [
  'Thought Leadership', 'Sinergia', 'Storytelling', 'Vibes',
  'Soneca Estratégica', 'Alinhamento de Stakeholders', 'Sinceridade Radical', /* ...~25 no total... */
];

function renderEndorse() {
  const people = shuffle(NAMES).slice(0, 5 + Math.floor(rand() * 3)); // 5–7
  const skills = shuffle(SKILLS);
  const out = [''];
  people.forEach((n, i) =>
    out.push('  ✔ Endossou ' + n + ' por ' + skills[i % skills.length]));
  out.push('', '  Você endossou 6 desconhecidos por habilidades que não consegue verificar. Eles vão endossar você de volta em até uma hora.');
  return out.join('\n');
}

…mais uma linha em dispatch() e handleSlash(), uma linha em renderHelp(), e SKILLS, renderEndorse adicionados a module.exports.

Passo 4 — A barreira

npm test

Verde? Você acabou de publicar uma funcionalidade com um agente, com testes primeiro. Não verde? Isso é normal — vá para o ciclo de iteração do Capítulo 4 e diga ao agente exatamente o que falhou.

Depois, dê uma olhada na coisa real (os testes verificam texto, mas você deve continuar olhando):

node bin/lockedin.js endorse
LOCKEDIN_SEED=1 node bin/lockedin.js endorse   # reprodutível

Passo 5 — Revise antes de aceitar

Nunca aceite um diff que você não leu. Passe os olhos especificamente por isto:

• Seguiu o padrão? O comando novo deve espelhar o connect — sem dependências novas, sem console.log dentro de src/.
• Só RNG com semente? Procure Math.random no diff. Não deve haver nenhum.
• Tocou em algo que não devia? A mudança deve ser aditiva; linhas não relacionadas não deveriam se mover.
• O teste novo é significativo? Deve falhar se alguém depois quebrar a funcionalidade — não apenas verificar true.

Se algo estiver errado, peça um ajuste (Capítulo 4). Se estiver bom, você terminou.

---

✅ Experimente com seu agente

Faça o ciclo completo acima de verdade. Depois, como crédito extra, peça ao agente para estendê-lo:

• "Faça o endorse aceitar um nome opcional: lockedin endorse Ada deveria endossar a Ada especificamente. Adicione um teste, mantenha a barreira verde."

Você acabou de construir uma funcionalidade de ponta a ponta. O último capítulo é sobre fazer isso de forma tranquila — criando prompts e revisando como um engenheiro líder.

Próximo: Tutorial 4 Prompts e Revisão