Tutorial 2 How the Code Works pt

Tutorial 2 · Como o Código Funciona

Meta: entender o punhado de decisões de design que tornam este projeto fácil — e seguro — de mudar com um agente de IA. Você não precisa decorar o código; precisa do modelo mental, para poder direcionar o agente com precisão.

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

---

O mapa

lockedin-cli/
├── bin/lockedin.js      # ponto de entrada — a ÚNICA parte que faz entrada/saída
├── src/lockedin.js      # o núcleo — funções puras que retornam strings
├── test/
│   ├── unit.test.js     # testa as funções do núcleo diretamente
│   └── cli.test.js      # inicia o binário real e verifica sua saída
├── tools/screenshot.js  # renderiza os SVGs que você vê em docs/
└── package.json         # metadados + o script `npm test`

Quatro ideias fazem tudo funcionar. Aprenda-as e você poderá pedir ao agente quase qualquer mudança com confiança.

Ideia 1 — Um núcleo puro que retorna strings

Abra src/lockedin.js. Note que as funções de renderização não imprimem — elas retornam strings:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...monta um array de linhas...
  return out.join('\n');   // retorna texto; não imprime nada
}

Toda a impressão de fato (e a leitura das suas teclas) acontece em bin/lockedin.js. Essa separação "o núcleo retorna dados, a borda faz entrada/saída" é a coisa mais importante aqui, porque uma função que só retorna uma string é trivial de testar:

const out = app.renderConnect();
assert.ok(out.includes("“Adoraria adicionar você à minha rede profissional.” — enviado para "));

Sem simular um terminal, sem capturar o stdout. Quando você pede ao agente para adicionar uma funcionalidade, é por isso que ele também consegue adicionar um teste rápido e confiável para ela.

Ideia 2 — Pools de conteúdo

As piadas vivem em arrays simples perto do topo de src/lockedin.js:

const HOOKS = [ 'Opinião impopular:', 'Deixa isso assentar.', /* ...~25 no total... */ ];
const LESSONS = [ '→ Sua rede é seu patrimônio líquido.', /* ... */ ];

Os geradores escolhem a partir desses pools. Na v1.2.0 cada pool cresceu para ~25 variações, e uma segunda camada de pools de template foi adicionada (coisas como POST_REVEALS e REFLECT_TAGSETS) para que a estrutura de cada saída varie, não só as palavras. Adicionar conteúdo costuma ser tão simples quanto adicionar strings a um array — uma primeira tarefa perfeita para dar a um agente.

Ideia 3 — Aleatoriedade com semente = testes determinísticos

Saída aleatória e testes automatizados parecem incompatíveis. Este projeto resolve esse dilema com um gerador de números aleatórios com semente:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → mesma semente, mesmo post

Toda escolha aleatória passa pelos helpers compartilhados pick() / shuffle(), que tiram desse gerador com semente. Defina LOCKEDIN_SEED=42 e a CLI fica totalmente reproduzível. A regra de ouro para qualquer mudança: uma nova aleatoriedade deve usar pick / shuffle, nunca Math.random diretamente — senão o determinismo (e os testes) quebram. Guarde isso no bolso; você vai lembrar o agente disso no Capítulo 3.

Ideia 4 — Duas camadas de testes

• test/unit.test.js chama funções do núcleo e verifica as strings que elas retornam (rápido, preciso).
• test/cli.test.js de fato inicia bin/lockedin.js e verifica seu stdout e código de saída reais (prova que tudo funciona de ponta a ponta).

Juntos, eles são a barreira. Também codificam invariantes — promessas que o app faz. Por exemplo, um post sempre abre com um gancho conhecido e sempre contém pelo menos três lições →; a tela de "connect" sempre diz incalculable. Quando um agente muda o código, esses testes pegam qualquer coisa que quebre silenciosamente uma promessa.

---

Por que isso importa ao trabalhar com um agente

Junte as quatro ideias e você tem um código onde um agente consegue:

1. Adicionar uma funcionalidade como uma função pura que retorna uma string,
2. Adicionar um teste para ela sem nenhuma ginástica de entrada/saída,
3. Manter a saída reprodutível via o RNG com semente, e
4. Provar que não quebrou nada rodando a barreira existente.

Esse é o ciclo que você vai rodar no próximo capítulo.

✅ Experimente com seu agente

Peça ao seu agente para verificar sua compreensão — lendo, não editando:

1. "Liste todo pool de conteúdo em src/lockedin.js e quantas entradas cada um tem."
2. "Me mostre uma invariante que test/unit.test.js impõe sobre generatePost, e explique o que a quebraria."
3. "Onde o RNG com semente é definido, e quais funções precisam usá-lo em vez de Math.random? Não mude nada — só explique."

Quando as respostas do agente baterem com este capítulo, você está pronto para construir.

Próximo: Tutorial 3 Sua Primeira Tarefa com o Agente