Concluir significa provar

A situação: “terminei” sem saber o que passou

Um agente informa: “Implementei a aprovação da ordem de serviço; todos os testes passaram”. A frase soa tranquilizadora, mas ainda não permite aceitar o trabalho. Quais testes? Eles já passavam antes? O cenário de usuário sem permissão foi executado? O agente alterou somente a fatia pedida? Houve uma falha de rede ignorada? Existe forma de desfazer a mudança?

Código escrito é um artefato. Trabalho concluído é uma afirmação sobre comportamento, escopo e risco, sustentada por evidências reproduzíveis. A autoria não altera esse padrão: código humano e código gerado por inteligência artificial (IA) passam pelos mesmos controles.

Neste capítulo, você aprenderá um ciclo curto para implementar um ticket e demonstrar que ele satisfaz a especificação. Não é necessário conhecer uma ferramenta de testes específica; os exemplos explicam o papel de cada verificação.

Vocabulário essencial

• Especificação, abreviada informalmente como spec, descreve problema, comportamento esperado, limites e critérios de aceite.
• Baseline é o estado observado antes da mudança. A tradução literal “linha de base” é correta, mas o termo inglês é comum em engenharia.
• Diff é a diferença entre duas versões de arquivos. Ele mostra o que mudou, não se a mudança está correta.
• Regressão é um comportamento que funcionava antes e deixou de funcionar depois.
• Typecheck verifica relações de tipos sem necessariamente executar o comportamento.
• Lint procura padrões de código, erros prováveis e violações de estilo definidas pela equipe.
• Teste unitário observa uma unidade pequena; teste de integração, a cooperação entre componentes; teste ponta a ponta, também abreviado como E2E, a jornada pelo sistema montado.
• Eval é uma avaliação usada especialmente quando a saída é probabilística ou admite julgamento graduado.
• Rollback é o plano ou mecanismo para voltar a um estado seguro.
• Evidência negativa demonstra que uma ação proibida não aconteceu ou que um invariante permaneceu verdadeiro.
• SAST — Static Application Security Testing é análise estática de segurança do código. CI — integração contínua é o fluxo automatizado que verifica mudanças integradas.
• LLM — Large Language Model é um modelo de linguagem de grande porte. Harness é o entorno que fornece contexto, ferramentas, permissões, limites e verificações a um agente.
• API — Application Programming Interface é uma interface pela qual programas colaboram; HTTP — Hypertext Transfer Protocol é o protocolo comum de APIs web; ERP — Enterprise Resource Planning é um sistema integrado de gestão empresarial.
• Retry é uma nova tentativa automática. Uma operação idempotente pode receber a mesma solicitação repetida sem multiplicar o efeito de negócio.

Modelo mental: uma alegação com recibos

Pense numa manutenção elétrica. Dizer “troquei o disjuntor” descreve uma ação. A entrega só fica defensável quando há identificação do circuito, teste adequado, medições, inspeção e registro do que foi alterado. Em software, comandos, resultados, artefatos e revisão do diff funcionam como recibos de uma alegação.

A analogia não autoriza tratar testes como garantia absoluta. Um instrumento pode estar inadequado e um teste pode cobrir o cenário errado. Evidências aumentam confiança dentro de um escopo declarado; não provam ausência de todo defeito possível.

Comece no baseline e siga para a direita. O retorno do revisor à especificação indica uma lacuna: corrigir a frase de conclusão sem corrigir o comportamento não resolve o problema.

Etapa 1 — registre o baseline

Antes de editar, execute o menor conjunto de verificações que cobre a área. Se o ticket altera aprovação de OS, rode os testes de domínio e contrato relacionados. Registre comando, ambiente e resultado.

Antes da mudança
Comando: pnpm test -- approve-order
Resultado: 18 aprovados, 1 falhou
Falha preexistente: timeout no teste erp-sandbox, issue INC-42
Commit observado: 7d3a9f1

O baseline não torna o código futuro correto. Ele permite separar regressão de falha anterior. Se o ambiente não consegue executar o teste, registre o impedimento e não transforme “não executei” em “passou”.

Em trabalho assistido por IA, o agente deve ler AGENTS.md ou instruções equivalentes, localizar comandos reais no repositório e inspecionar padrões antes de sugerir dependências. Um comando inventado que termina rapidamente não é evidência.

Etapa 2 — converta aceite e risco em verificações

Para cada critério da spec, pergunte qual observação separa sucesso de falha. Depois adicione cenários de risco:

Afirmação	Verificação adequada	O que ainda não prova
alçada insuficiente é negada	teste de domínio	contrato HTTP e interface
API responde 403 sem alterar a OS	teste de integração	aparência da mensagem
duas aprovações não se sobrescrevem	teste de concorrência	recuperação do ERP
retry não duplica o evento	teste de idempotência	retenção de auditoria
botão e mensagem são compreensíveis	teste da interface do usuário (UI) e acessibilidade	autorização no servidor
classificador de IA melhorou	conjunto de evals versionado	ausência de deriva futura

Nenhuma ferramenta única prova tudo. Typecheck não demonstra regra de negócio. Captura de tela não demonstra autorização. SAST não demonstra que o produto satisfaz o usuário. A qualidade vem da composição proporcional ao risco.

Etapa 3 — implemente a menor mudança coerente

Uma fatia vertical pode tocar domínio, API e teste, mas ainda deve permanecer focada. Evite “aproveitar” o ticket para reorganizar módulos não relacionados. Mudanças misturadas tornam o diff difícil de revisar e a regressão difícil de localizar.

Este exemplo TypeScript contém a regra mínima da alçada. Salve-o como can-approve.mts:

type Decision =
  | { ok: true }
  | { ok: false; reason: "INSUFFICIENT_LIMIT" | "INVALID_STATE" };

export function canApprove(limit: number, cost: number, status: string): Decision {
  if (status !== "WAITING_APPROVAL") {
    return { ok: false, reason: "INVALID_STATE" };
  }
  if (limit < cost) {
    return { ok: false, reason: "INSUFFICIENT_LIMIT" };
  }
  return { ok: true };
}

O tipo Decision limita resultados possíveis. A primeira condição protege a máquina de estados. A segunda compara alçada e custo. O retorno positivo acontece somente depois das duas pré-condições. Essa função não autentica usuário, grava banco nem publica evento; esses controles pertencem a outras fronteiras e precisam de testes próprios.

O exemplo pressupõe que valores monetários já foram validados. Em produção, represente dinheiro segundo o contrato do domínio — por exemplo, inteiro em centavos ou tipo decimal — e rejeite valor negativo, não finito ou fora de limite antes de chamar a regra.

Salve o teste focado como test-can-approve.mts:

import assert from "node:assert/strict";
import { canApprove } from "./can-approve.mts";

assert.deepEqual(
  canApprove(5_000, 8_000, "WAITING_APPROVAL"),
  { ok: false, reason: "INSUFFICIENT_LIMIT" },
);

O contexto é uma ordem de oito mil e um supervisor limitado a cinco mil. A saída esperada é negação explícita. Com Node.js 22.18 ou posterior, execute node test-can-approve.mts; esse modo remove tipos para executar, mas não substitui o typecheck do projeto, conforme a documentação de TypeScript no Node.js. A asserção usa o módulo oficial node:assert/strict. Um resultado aprovado prova apenas esse cenário e essa implementação.

Etapa 4 — teste focado, depois verificações amplas

O teste focado oferece feedback rápido. Depois dele, execute os portões afetados: suíte do módulo, contrato, integração, typecheck, lint, segurança e build quando aplicáveis. A ordem evita esperar dez minutos para descobrir um erro localizado, mas não permite encerrar depois do primeiro teste verde.

Provoque uma falha controlada para validar o teste: troque temporariamente < por > na comparação e confirme que o cenário falha. Desfaça imediatamente a mutação. Se o teste continua verde, ele não observa a regra que afirma proteger.

Para saídas de LLM, um teste exato pode ser inadequado. Use casos versionados, rubrica, limiares e calibração de graders. Para autorização, cálculo e transação determinísticos, prefira testes determinísticos. Não use um juiz probabilístico para decidir se um usuário pode acessar dados.

Etapa 5 — revise o diff como se fosse de outra pessoa

Leia cada arquivo alterado e faça perguntas concretas:

1. toda linha serve ao ticket?
2. alguma mudança remove uma proteção existente?
3. segredos, tokens ou dados pessoais apareceram?
4. snapshots foram atualizados porque o comportamento mudou de propósito?
5. uma dependência nova é realmente necessária?
6. comentários e nomes explicam a regra sem esconder complexidade?
7. existe caminho de rollback?

Também verifique arquivos não planejados. Um agente pode alterar configuração ou lockfile — arquivo que trava versões de dependências — como efeito colateral. O diff mostra esse fato; a revisão decide se ele é legítimo.

Evidência negativa: provar o que não aconteceu

O caminho nominal de aprovação não demonstra segurança. Você precisa observar negações e invariantes:

• usuário de outra unidade recebe negação uniforme;
• status da OS permanece inalterado após a negação;
• log de auditoria não contém token ou senha;
• retry usa a mesma chave e não duplica evento;
• timeout não transforma resultado desconhecido em sucesso;
• comentário malicioso é armazenado e exibido segundo a política definida.

Essa é a evidência negativa. Ela não tenta provar um universo infinito de ausências; seleciona ações proibidas e efeitos que o modelo de ameaça e a especificação declararam relevantes.

O pacote de evidência

Uma entrega reproduzível contém:

Resultado: alçada insuficiente e outra unidade são negadas sem mudar a OS.
Escopo: domínio de aprovação, endpoint e testes; identidade não alterada.
Arquivos: lista ou link para o diff.
Comandos: exatamente como foram executados.
Resultados: contagem, duração e caminhos para relatórios.
Falha provocada: mutante da comparação fez o teste focado falhar.
Segurança: secret scan e cenários de autorização executados.
Limitações: sandbox do ERP permaneceu indisponível.
Rollback: reverter o commit e desativar a flag `approval-v2`.

“Todos os testes passaram” sem comando, escopo e ambiente é fraco. Copiar milhares de linhas de log também é ruim: dificulta localizar a evidência e pode vazar dados. Resuma, preserve o artefato e forneça o caminho.

Falhas recorrentes e diagnóstico

Sintoma	Causa provável	Como diagnosticar
suíte verde, regra quebrada	teste observa mock ou detalhe errado	provoque mutação na regra
falha apareceu depois da edição	baseline ausente	reproduza no commit anterior em ambiente isolado
snapshot enorme mudou	atualização automática sem revisão	leia diferença sem regenerar
agente diz que passou, mas não há log	comando não executado ou saída perdida	repita comando e registre código de saída
teste E2E instável	tempo, dado ou dependência não controlada	repetir com trace e identificar fronteira
correção exige dependência nova	padrão existente não foi investigado	buscar uso equivalente no repositório

Se um portão não puder ser executado, declare parcialmente verificado e forneça comando e responsável restantes. Honestidade operacional é parte da qualidade.

Segurança e cadeia de suprimentos

Use o Secure Software Development Framework do NIST, SP 800-218 como referência oficial para organizar práticas de desenvolvimento seguro; adapte a implementação ao risco, à tecnologia e às políticas da organização.

Uma dependência nova amplia a cadeia de confiança. Verifique necessidade, origem, licença, manutenção, integridade e vulnerabilidades. Código produzido por IA passa por revisão, SAST, secret scanning, testes e política de dados. Não envie repositório ou incidente a serviço externo sem autorização.

Para mudanças de alto risco, separe criador e aprovador. O mesmo agente pode encontrar erros próprios, mas essa autoavaliação não é independente. Use revisão humana ou outro contexto de avaliação com acesso à spec, ao diff e às evidências.

Antes e agora

Antes, produtividade era frequentemente narrada por linhas de código ou velocidade de digitação. Com geração automática, essa métrica perdeu ainda mais valor. O resultado útil é a fatia aceita, reproduzível, segura e com baixo retrabalho.

Agentes tornam o pacote de evidência mais importante, não menos. Eles podem executar testes e resumir resultados, mas o harness deve limitar permissões, preservar logs e impedir que uma conclusão textual substitua os portões determinísticos.

Exercício guiado

1. escolha um critério de aceite pequeno;
2. registre baseline e commit;
3. escreva um teste nominal e uma evidência negativa;
4. implemente a menor mudança;
5. provoque uma mutação e confirme a falha;
6. execute teste focado e verificações amplas;
7. revise o diff linha a linha;
8. produza o pacote de evidência.

O exercício passa quando outra pessoa repete os comandos e chega à mesma conclusão sem consultar a conversa original.

Desafio independente

Implemente o ticket de aprovação T-014 numa branch ou worktree isolada. Cubra caminho nominal, alçada, outra unidade, conflito de versão, repetição e indisponibilidade do ERP. Inclua um risco que permaneceu aberto e explique por que ele não invalida — ou invalida — a entrega.

Não marque como concluído se qualquer teste obrigatório não foi executado. A entrega pode estar correta e ainda assim não estar suficientemente verificada.

Conclusão

Concluir significa ligar uma alegação a evidências proporcionais ao risco. Você aprendeu a registrar baseline, transformar aceite em verificações, implementar com foco, testar do específico ao amplo, procurar efeitos proibidos, revisar o diff e entregar resultados reproduzíveis. O próximo passo é separar conformidade com a especificação de conformidade de engenharia durante a revisão independente.

Fontes

• OpenAI — Codex
• Google Testing Blog
• NIST — Secure Software Development Framework, SP 800-218
• Node.js — TypeScript
• Node.js — Assert