Da intenção à especificação verificável

A situação: uma frase que parece clara, mas não é

O gerente diz: “Precisamos aprovar ordens de serviço pelo aplicativo”. A frase comunica uma intenção útil, porém ainda não descreve um comportamento que possa ser implementado com segurança. Quem pode aprovar? Toda ordem pode ser aprovada? O custo altera a autoridade necessária? A aprovação acontece antes ou depois da confirmação no sistema integrado de gestão empresarial (ERP)? O que ocorre se duas pessoas agirem ao mesmo tempo? Como provar quem decidiu?

Se uma pessoa ou um coding agent começar a programar agora, terá de inventar respostas. O código pode compilar e mesmo assim resolver o problema errado. Este capítulo ensina a remover essa “névoa” até restar um contrato observável: entradas conhecidas, regras explícitas, resultados verificáveis e falhas previstas.

Você não precisa dominar uma norma de requisitos para começar. Precisa saber procurar evidência, formular uma decisão por vez e escrever o que outra pessoa conseguirá testar.

Vocabulário antes do método

• Intenção é a mudança desejada: “aprovar OS pelo aplicativo”.
• Requisito (requirement) descreve uma capacidade ou restrição necessária para atingir essa intenção.
• Stakeholder é uma pessoa ou grupo afetado ou responsável pela decisão, como supervisor, manutenção, auditoria e equipe do ERP.
• Evidência é algo observável: código atual, contrato de API, tela, teste, log, incidente ou decisão aprovada.
• Hipótese é uma explicação ainda não confirmada: “talvez todo supervisor possa aprovar qualquer valor”.
• Spec, abreviação de specification, é a especificação que organiza o comportamento acordado.
• Pré-condição é o que precisa ser verdadeiro antes da ação; pós-condição, o que precisa ser verdadeiro depois.
• Invariante é uma regra que deve permanecer verdadeira, como “uma pessoa não aprova uma OS de outra unidade”.
• Critério de aceite (acceptance criterion) é um exemplo verificável que separa resultado aceito de resultado rejeitado.
• ADR, Architecture Decision Record, registra uma decisão arquitetural importante, seu contexto e consequências.
• Fluxo nominal (happy path) é o percurso esperado quando as pré-condições são satisfeitas; caso limite (edge case) é uma situação rara ou situada na fronteira de uma regra.
• Concorrência ocorre quando duas operações disputam o mesmo estado. Idempotência significa que repetir uma operação com a mesma identidade não duplica seu efeito.
• Outbox é um padrão que grava a mudança de negócio e o evento a publicar na mesma transação local, para que a integração possa tentar o envio novamente sem perder a decisão.

Os nomes /grill-with-docs e /to-spec aparecem nas skills de Matt Pocock. Eles não são comandos universais do Codex, Claude Code ou ChatGPT. O método por trás deles é portável: investigar, perguntar progressivamente, registrar decisões e produzir uma especificação verificável.

Modelo mental: a especificação como mapa de fronteiras

Imagine uma planta elétrica. Ela não manda o eletricista segurar cada ferramenta de uma forma específica; mostra circuitos, proteções e pontos de conexão que não podem ser confundidos. Uma boa spec faz algo semelhante: define responsabilidades, estados, interfaces e limites, mas deixa detalhes locais reversíveis para a implementação.

A analogia tem um limite. Requisitos mudam com aprendizado, enquanto uma planta aprovada tende a ser mais estável. Por isso a especificação é um artefato vivo, versionado junto das evidências que a sustentam. “Vivo” não significa reescrever silenciosamente depois que o código falhou; significa registrar mudanças e revisar os testes afetados.

Leia o fluxo da esquerda para a direita. O retorno dos testes para as lacunas não significa implementar primeiro; significa usar exemplos para descobrir ambiguidades antes de autorizar a construção.

Etapa 1 — investigue antes de perguntar

Comece procurando o que o projeto já sabe. Para aprovação de OS, examine:

1. entidades e estados no domínio;
2. telas e mensagens já apresentadas ao usuário;
3. schemas e contratos da API;
4. regras de autorização;
5. testes existentes;
6. ADRs e documentação de integração;
7. logs e incidentes relacionados;
8. contrato oficial do ERP.

Registre cada achado em duas colunas: evidência e interpretação. Por exemplo, status = WAITING_APPROVAL no schema é evidência. Concluir que esse é o único estado elegível é interpretação até que regra, teste ou responsável confirme.

Crie também um glossário pequeno. “Aprovar”, “liberar”, “autorizar” e “confirmar no ERP” podem significar eventos diferentes. Se duas equipes usam a mesma palavra para ações distintas, a especificação herdará o conflito.

Etapa 2 — conduza uma entrevista progressiva

Não envie cinquenta perguntas genéricas. Faça uma pergunta por vez quando a resposta muda regra, arquitetura, segurança ou aceite. Antes de perguntar, mostre o que encontrou, explique a consequência e recomende uma opção quando houver evidência suficiente.

Uma pergunta forte seria:

O domínio possui WAITING_APPROVAL e os testes atuais negam transições a partir de CANCELLED. Recomendo permitir aprovação somente a partir de WAITING_APPROVAL. Existe alguma exceção operacional que precisa ser preservada?

Ela é melhor que “quais estados existem?” porque demonstra investigação e concentra a conversa numa decisão. Depois da resposta, atualize a spec e passe à próxima lacuna. Não mantenha uma lista paralela de decisões apenas no chat.

Pergunte prioritariamente sobre:

• ator e autoridade;
• estado inicial e estado final;
• dados obrigatórios;
• concorrência;
• efeitos externos;
• falha parcial;
• auditoria e privacidade;
• itens explicitamente fora do escopo.

Etapa 3 — escreva o contrato observável

Uma estrutura enxuta pode ser assim:

Problema e resultado esperado
Atores e responsabilidades
Glossário
Pré-condições, pós-condições e invariantes
Fluxo nominal
Fluxos de erro e abuso
Interfaces e dados
Concorrência e idempotência
Observabilidade e auditoria
Critérios de aceite
Fora do escopo
Decisões abertas e fontes

Para a OS, a parte central poderia dizer:

Dado um supervisor autenticado da unidade Norte
e uma OS da mesma unidade em WAITING_APPROVAL,
quando a alçada do supervisor for maior ou igual ao custo estimado
e a versão enviada ainda for a versão atual,
então o sistema registra APPROVED, autor, instante e justificativa,
e publica o evento WorkOrderApproved pela outbox.

Se a versão divergir, responde 409 sem sobrescrever a decisão concorrente.
Se o ERP estiver indisponível após a confirmação da transação local, a aprovação permanece
registrada como sincronização pendente e a nova tentativa usa a mesma chave idempotente.

Isso fixa comportamento sem decidir nomes de funções internas. Já “usar event sourcing — persistir a sequência de eventos como fonte de verdade —” seria uma escolha estrutural difícil de reverter e mereceria um ADR próprio. O nome local approvedAt não merece um ADR.

Do texto ao teste: prova de verificabilidade

Uma spec é verificável quando outra pessoa consegue derivar testes sem nova reunião. Considere este fragmento conceitual de teste TypeScript; workOrder, user e approveOrder representam funções que o projeto real precisaria fornecer:

it("nega aprovação de outra unidade", async () => {
  const order = workOrder({ unitId: "north", status: "WAITING_APPROVAL" });
  const supervisor = user({ unitId: "south", role: "SUPERVISOR" });

  const result = await approveOrder({ order, supervisor, expectedVersion: 3 });

  expect(result).toEqual({ ok: false, reason: "CROSS_UNIT_FORBIDDEN" });
  expect(order.status).toBe("WAITING_APPROVAL");
});

O contexto é uma tentativa de aprovação entre unidades. As duas primeiras linhas montam entrada e ator. A chamada executa a regra declarada. As últimas linhas verificam tanto a resposta quanto a ausência de alteração indevida. Se a spec não disser que o estado deve permanecer intacto, o teste revela uma lacuna útil.

Em um projeto real, execute o teste com o comando documentado pelo repositório, por exemplo pnpm test -- approve-order. O resultado esperado é um teste aprovado. Para provar que ele protege a regra, altere temporariamente a unidade do supervisor para north e confirme que o cenário precisa usar outro resultado; depois desfaça a mutação. Nunca deixe a falha provocada no código de produção.

Concorrência, integração e falha segura

O caminho nominal raramente é suficiente. Duas pessoas podem abrir a mesma OS. A primeira aprova a versão 3; a segunda envia também a versão 3 depois que o registro já virou versão 4. Sem controle, a última gravação pode apagar informação. A spec deve exigir comparação de versão e um 409 Conflict, ou outro contrato explícito.

O ERP cria outra fronteira. Se o banco local confirmar e o ERP falhar, tentar “desconfirmar” silenciosamente pode perder auditoria. O padrão de outbox registra a mudança e o evento na mesma transação local; um processo posterior sincroniza com chave idempotente. Essa arquitetura só deve aparecer na spec se a consistência e a falha exigirem tal decisão — não como enfeite técnico.

Segurança é requisito de negócio:

• autorização é calculada no servidor, nunca aceita do modelo ou frontend;
• orderId vindo do cliente não prova acesso à ordem;
• comentário é validado e renderizado com segurança;
• retry não pode duplicar aprovação;
• log registra identificadores e decisão sem copiar tokens ou dados desnecessários;
• ações de alto impacto recebem trilha de auditoria imutável conforme a política aplicável.

Como era e como funciona melhor hoje

Um extremo antigo era produzir documentos enormes antes de qualquer feedback. O outro era saltar de uma conversa diretamente para código e descobrir as regras durante o incidente. O caminho atual recomendado combina specs vivas, exemplos verificáveis e pequenas fatias verticais. Agentes aceleram busca e redação, mas não recebem autoridade para inventar uma política ausente.

O método continua compatível com documentação formal em sistemas regulados. Nesses casos, rastreabilidade, aprovação e controle de mudança serão mais rigorosos; a necessidade de verificabilidade aumenta, não diminui.

Sinais de que você deve parar ou continuar investigando

Pare a descoberta quando atores, estados, regras, interfaces, falhas e aceite permitirem fatiar o trabalho e derivar testes. Continue investigando se um “a definir” muda autorização, fonte de verdade, consistência, contrato externo ou recuperação.

Também pare se a próxima pergunta não reduz risco e apenas coleta preferência. A meta não é eliminar toda incerteza do universo; é tornar a próxima fatia segura e verificável.

Exercício guiado

1. Escolha “permitir que o eletricista conclua uma OS”.
2. Inspecione cinco artefatos e registre caminho, evidência e interpretação.
3. Construa um glossário de cinco termos.
4. Liste três lacunas que mudam segurança ou comportamento.
5. Faça uma pergunta decisória por lacuna, com recomendação fundamentada.
6. Escreva fluxo nominal, três erros, um abuso e um caso de concorrência.
7. Peça a outra pessoa para derivar cinco testes sem explicação oral.

A evidência de conclusão é docs/specs/complete-work-order.md, o glossário e a lista de testes derivados. Se a pessoa precisar perguntar qual resultado esperar, revise a seção correspondente.

Desafio independente

Transforme uma ideia real de uma frase em spec. Limite a descoberta a dez perguntas de alto impacto. Inclua problema, resultado, atores, invariantes, dados, interfaces, concorrência, indisponibilidade, segurança, observabilidade, critérios de aceite e fora de escopo. Registre em ADR apenas uma decisão realmente difícil de reverter.

O desafio passa quando um revisor consegue apontar, para cada critério de aceite, qual evidência automatizada ou humana demonstrará o resultado. “O agente disse que terminou” não é evidência.

Conclusão

Você começou com uma intenção e aprendeu a não confundi-la com requisito. Investigou antes de perguntar, separou evidência de hipótese, conduziu decisões progressivas e produziu um contrato que gera testes. No próximo passo, essa spec poderá ser dividida em fatias verticais: cada ticket entregará uma pequena capacidade ponta a ponta, em vez de uma camada isolada impossível de validar.

Fontes

• ISO/IEC/IEEE 29148 — Requirements engineering
• Matt Pocock — visão geral das skills
• Matt Pocock — grill-with-docs
• Matt Pocock — to-spec
• OpenAI Codex — AGENTS.md
• AWS — padrão Transactional Outbox
• OWASP — Authorization Cheat Sheet
• RFC 9110 — 409 Conflict