Esta nota é uma aula sobre desenvolvimento guiado por especificação (spec-driven development, ou SDD). O objetivo é que, ao terminar, você consiga transformar um pedido vago em uma spec que uma pessoa ou um agent de IA consegue implementar sem adivinhar, saiba verificar o resultado contra essa spec e decida quando o esforço de escrevê-la compensa e quando é exagero.

A aula parte do zero: não pressupõe que você já tenha ouvido falar de spec nem de IA escrevendo código. Os exemplos reais vêm do projeto svg-creator (pasta specs/), onde o SDD é praticado de verdade, com os acertos e também com as specs que ficaram vagas. As figuras são animadas e foram geradas com o ArchFlow (veja MCP para o ecossistema de ferramentas e Agents para a parte de agents). As ferramentas do ecossistema (Spec Kit, Kiro, OpenSpec, Tessl) mudam rápido, então tudo o que a seção 11 diz sobre elas vem da documentação oficial consultada em 15 de outubro de 2026. Confira a documentação antes de copiar um comando.

Mapa da aula

Pré-requisito: saber ler código e usar git. Ajuda ter lido Agents, porque o brief e o contrato fixado antes de dividir o trabalho (seções 11 e 13 daquela aula) são parentes diretos de uma spec, e a seção 9 desta aula faz a ponte.

Parte 1: Fundamentos

1. O que é uma spec e o que é SDD

Imagine que você pede a um marceneiro “faça uma mesa”. Ele faz uma mesa excelente, de jacarandá, com 2 metros de comprimento. Você queria uma mesa de cabeceira, de 40 centímetros, que coubesse ao lado da cama. Nenhum dos dois errou por incompetência: o pedido deixava de fora tudo o que importava (tamanho, uso, material, prazo, orçamento), e o marceneiro preencheu cada lacuna com a suposição mais razoável do ponto de vista dele.

Uma especificação (spec) é o documento que fecha essas lacunas antes de a mesa existir. Ela descreve o que deve existir ao final, para quem, dentro de que limites e como saber que ficou certo. Uma planta de casa, uma receita com medidas e um pedido de pizza (“meio calabresa, meio marguerita, borda de catupiry, sem cebola”) são specs em escala doméstica. Em software, a spec descreve comportamento: o que o sistema faz diante de cada entrada, incluindo as entradas chatas.

Desenvolvimento guiado por especificação (SDD) é a prática de escrever essa spec primeiro, revisá-la como se revisa código, e só então implementar, usando a spec como a referência contra a qual o resultado é conferido. A ordem é o ponto: primeiro o que e por quê, depois o como. O código passa a ser a resposta a uma pergunta que já foi escrita.

A figura abaixo mostra o mesmo pedido de uma linha, “Adicione filtro por tag”, seguindo dois caminhos.

Comece pelo pedido laranja à esquerda. No grupo de cima, ele vai direto para um agent de IA (o hexágono, que é um modelo de linguagem que escreve código por você). Como o pedido não diz se “filtrar por tags” é qualquer tag (OU), todas as tags (E) ou busca por texto, o agent escolhe uma das três interpretações, e os pacotes rosa mostram o chute. O resultado é um PR que roda, passa no compilador, e mesmo assim não era o pedido. No grupo de baixo, o pedido passa por uma entrevista, vira uma spec aprovada (o documento de borda dupla), e só então o agent implementa. Repare que a cadeia termina em testes verdes ou vermelhos, ou seja, em algo que se pode executar, enquanto o caminho de cima termina em uma opinião (“acho que ficou bom”).

Uma observação sobre vocabulário, porque a palavra “spec” é usada por muita gente para muita coisa. Neste texto, spec é um artefato de texto, guardado no repositório, que descreve comportamento e critérios de aceitação. Um e-mail do gerente, um diagrama bonito ou a conversa que você teve com a IA ontem ficam de fora dessa definição. Se não está escrito e versionado, é lembrança, e lembrança envelhece mal.

2. Por que existe: o problema que o SDD resolve

Todo projeto de software já viveu a cena do marceneiro. O que mudou com os agents de IA foi a velocidade. Antes, um pedido ambíguo levava dias para virar código errado, e o desencontro aparecia na primeira demonstração. Agora um agent produz centenas de linhas corretas do ponto de vista técnico em minutos, e o desencontro aparece quando você já está revisando um diff grande. O erro ficou mais barato de cometer e mais caro de descobrir.

Há quatro problemas concretos por trás disso.

O primeiro é a ambiguidade. Linguagem natural deixa buracos, e quem implementa é obrigado a preenchê-los. Uma pessoa experiente pergunta antes. Um agent de IA, por padrão, tende a continuar: ele não tem como saber que a lacuna existia, então escolhe a continuação mais provável. Isso é um problema de arquitetura do modelo, não de teimosia dele. A escolha provável não é necessariamente a sua.

O segundo é o retrabalho. Cada suposição errada descoberta tarde custa mais do que a mesma dúvida respondida no início. Escrever “lista vazia mostra todas as tarefas” leva dez segundos antes do código e uma tarde depois que três telas dependem do comportamento oposto.

O terceiro é a memória. Decisões tomadas numa conversa só existem enquanto a conversa existe. Se na segunda-feira você decidiu que lista vazia significa “tudo” e na quinta outra sessão (outro agent, outra pessoa, você mesmo sem lembrar) implementa a tela ao lado, a decisão não chega lá. É o que a figura seguinte mostra.

No grupo de cima, a decisão da sessão de segunda fica na nuvem “Conversa”, que expira. O pacote cinza sai, mas na seta seguinte aparece o ✕: ela não chega à sessão de quinta, que então “chuta outro padrão” (pacote rosa) e produz o comportamento “lista vazia = nada”. No grupo de baixo a mesma decisão é escrita em lista.md e commitada (seta laranja grossa). A sessão de quinta lê a spec antes de começar, e ainda existe um teste verde, o da lista vazia, que falharia se alguém mudasse o comportamento sem querer. A spec funciona como memória de longo prazo do projeto.

O quarto problema é a falta de critério. Sem uma definição prévia de “pronto”, a verificação vira uma conversa de gosto: “parece bom”. Com critérios escritos, a verificação vira um comando que passa ou falha, e isso vale tanto para humanos quanto para agents (a seção 15 de Agents chama isso de confiar no ambiente, não no relatório).

Vibe coding, prompt solto e SDD

Esses três jeitos de trabalhar com IA aparecem juntos e vale separá-los. Vibe coding, expressão popularizada por Andrej Karpathy em 2025, é programar descrevendo a intenção em frases soltas e aceitando o que a IA devolve, ajustando pelo resultado e quase sem ler o código. Para um protótipo de fim de semana é ótimo. Prompt solto é o parente mais disciplinado: você escreve uma instrução razoavelmente detalhada, mas ela vive na conversa. SDD é o terceiro passo: a instrução vira um artefato do projeto, revisado e versionado.

Nenhuma coluna é a “certa”. A tabela serve para escolher, e a seção 15 volta ao assunto com um critério de decisão.

3. Exemplos no plural: specs em contextos diferentes

Uma spec muda de forma conforme o terreno, mas as perguntas são as mesmas: o que entra, o que sai, o que acontece nas bordas e como conferir. Cinco exemplos curtos ajudam a ver o padrão.

Uma API

Para um endpoint, a spec fala de entradas, saídas e erros, e os números importam.

## POST /orders/{id}/cancel

Objetivo: permitir que o cliente cancele um pedido que ainda não foi enviado.

Requisitos
- R1. O sistema DEVE cancelar o pedido quando o status for `paid` ou `preparing`.
- R2. O sistema DEVE responder 409 com `{"error": "already_shipped"}` quando o status for `shipped` ou `delivered`.
- R3. O sistema DEVE responder 404 quando o pedido não pertencer ao usuário autenticado
  (e não 403, para não revelar que o pedido existe).
- R4. O cancelamento DEVE ser idempotente: repetir a chamada em um pedido já cancelado responde 200 sem efeito.

Fora de escopo: reembolso (spec separada, ver `refunds.md`).

Repare em R3: a spec registra uma decisão de segurança e o motivo entre parênteses. Sem isso, qualquer implementador (humano ou IA) usaria 403, que parece o código “óbvio”.

Uma tela

Para interface, a spec descreve estados, não pixels. Os estados são onde as telas costumam quebrar.

## Tela de login

Estados: inicial, enviando, erro de credencial, erro de rede, bloqueada.

- Quando o usuário envia e o servidor responde 401, mostrar "E-mail ou senha incorretos"
  sob o campo de senha, manter o e-mail digitado e limpar a senha.
- Quando a rede falha, mostrar "Sem conexão. Tente de novo" e manter os dois campos.
- Após 5 falhas seguidas em 10 minutos, desabilitar o botão por 60 segundos e mostrar o tempo restante.
- Enquanto "enviando", o botão fica desabilitado e mostra um indicador; um segundo clique não dispara outra chamada.

Uma regra de negócio

Regras de negócio são o terreno mais traiçoeiro, porque o texto parece claro e esconde fronteiras. A técnica aqui é escrever exemplos nas bordas.

## Frete grátis

Pedidos com subtotal igual ou acima de R$ 200,00 não pagam frete.
O subtotal é a soma dos itens depois dos descontos de item e antes do cupom de pedido.

Exemplos
- Subtotal R$ 199,99: paga frete.
- Subtotal R$ 200,00: frete grátis.
- Itens somam R$ 230,00, cupom de R$ 50,00: subtotal continua R$ 230,00 (o cupom não entra), frete grátis.

O terceiro exemplo existe porque “subtotal” é uma palavra que meia empresa usa com significados diferentes. O exemplo desempata.

Um elemento de diagrama (svg-creator)

No projeto svg-creator, cada elemento que o editor desenha tem uma spec em specs/elements/. A de specs/elements/go/channel.md descreve o canal do Go (chan T), com formato visual, estados e a sintaxe da linguagem de texto do app. Um trecho, simplificado, da tabela de estados:

| Estado            | Opções da DSL |
| Aberto            | padrão |
| Fechado (close)   | fechado=sim (boca de envio selada em vermelho com ✕; o buffer continua visível) |
| nil               | tema=default borda=pontilhada |
| Cheio             | saúde=degradado label-base="4/4" |

É uma spec de comportamento visual e de formato textual ao mesmo tempo. A seção 6 desmonta esse arquivo inteiro e mostra como cada linha dele vira teste.

Um script

Um script de backup parece pequeno demais para spec, e por isso é onde mais se erra. Três linhas bastam:

## backup.sh

- Copia `~/Documents` para `/Volumes/Backup/AAAA-MM-DD/` e mantém só as 7 pastas mais recentes.
- Se `/Volumes/Backup` não estiver montado, sai com código 2 e não apaga nada.
- Nunca apaga a pasta mais recente, mesmo que a cópia nova tenha falhado.

A última linha é a que importa: ela diz o que o script nunca faz. Quem implementa sem essa frase pode escrever uma limpeza que apaga o único backup bom depois de uma cópia quebrada.

O padrão nos cinco casos: um objetivo curto, requisitos numerados e verificáveis, exemplos nas bordas, e uma ou duas frases sobre o que fica de fora ou o que nunca deve acontecer. A forma muda, a estrutura não.

Parte 2: Mecânica

4. O ciclo do SDD e os três níveis

O SDD organiza o trabalho em cinco fases, e cada fase produz um arquivo que a seguinte lê. A figura mostra o caminho completo, em forma de U, para que o laço de correção apareça.

Siga as setas grossas no alto, da esquerda para a direita: a spec (laranja, o que cada pessoa decide) vira o plano, o plano vira a lista de tarefas, e as tarefas descem para o agent como briefs. Depois o fluxo volta pela linha de baixo: o agent edita o código, os testes e o linter rodam, e um humano olha o diff no losango “Passou?”. A seta verde “sim” fecha a fatia. As duas setas rosas tracejadas são o que torna o ciclo honesto: quando o problema está no código, volta-se ao código, mas quando o problema está na spec (ela estava errada ou incompleta), a correção começa por ela, e o código é refeito depois. A seta pontilhada de “spec.md” para “Testes e linter” lembra que cada critério da spec deve virar um teste.

As cinco fases, uma por uma:

1. Especificar. Você (ou você com um agent que entrevista) escreve o que e o porquê: objetivo, escopo, requisitos, critérios de aceitação. A saída é a spec. Fase humana por excelência, porque só você sabe o que quer.
2. Planejar. Dado o que se quer, decide-se como: quais arquivos mudam, quais tipos e contratos existem, quais riscos há. A saída é um plano técnico. Ele pode ser escrito por um agent, mas é revisado por você, porque decisões de arquitetura são caras de desfazer.
3. Quebrar em tarefas. O plano é cortado em fatias pequenas, cada uma com critério de pronto próprio, que cabem no contexto de um agent e podem ser revisadas num diff curto.
4. Implementar. Uma fatia por vez (ou fatias independentes em paralelo), com a spec e o plano à mão.
5. Verificar. Testes, tipos, linter e leitura do diff contra os critérios da spec.

Um detalhe fácil de perder: a spec é a fonte da verdade do comportamento. Se o código faz uma coisa e a spec diz outra, um dos dois está errado, e o ciclo obriga a decidir qual, em vez de deixar a divergência crescer. Uma regra simples que ajuda: nenhum PR muda comportamento sem mudar a spec no mesmo PR (a seção 8 mostra como impor isso).

Spec-first, spec-anchored e spec-as-source

Nem todo mundo leva a spec igualmente a sério depois da implementação. Em uma série de artigos sobre IA generativa publicada no site de Martin Fowler, as ferramentas de SDD são comparadas por três níveis, que também servem como vocabulário para você se posicionar.

No grupo de cima, spec-first: a spec é escrita com cuidado antes e usada para guiar a tarefa, mas depois da implementação ela descansa. O selo “defasada depois” avisa o destino mais comum: com o tempo, alguém ajusta o código direto (seta pontilhada rosa) e a spec fica para trás. No grupo do meio, spec-anchored: a spec é mantida junto do código durante a vida da feature, e as setas grossas mostram que um PR exige a atualização dos dois, com testes prendendo ambos. No grupo de baixo, spec-as-source: a spec é a única fonte editada por humanos, um gerador produz o código, e uma edição manual no código gerado é barrada (o ✕ vermelho), do mesmo jeito que ninguém edita à mão o binário de um programa.

As definições do artigo, resumidas: spec-first é escrever uma spec bem pensada antes e usá-la no fluxo assistido por IA da tarefa; spec-anchored mantém a spec depois da tarefa, para evolução e manutenção; spec-as-source faz da spec o arquivo-fonte principal ao longo do tempo, com humanos editando só a spec. O autor observa que todas as abordagens que ele encontrou eram spec-first, e que nem todas pretendem chegar aos outros dois níveis. O spec-as-source lembra a engenharia dirigida por modelos (model-driven development), e o autor alerta que ele pode juntar a rigidez desse mundo com o não-determinismo dos modelos de linguagem: gerar código duas vezes da mesma spec pode dar resultados diferentes. Para trabalho do dia a dia, o ponto de equilíbrio realista hoje é spec-first com disciplina de spec-anchored nas partes que merecem.

5. Anatomia de uma boa spec

Uma spec boa responde, em ordem, quatro perguntas: por que isso existe, onde isso termina, como deve se comportar e o que ainda não sabemos. A figura reúne as dez peças de uma spec completa agrupadas por pergunta e mostra quem consome cada uma.

O retângulo grande é o arquivo spec.md, e os quatro grupos dentro dele são as perguntas. À direita ficam os consumidores. “Contratos” (azul, seta grossa) vai direto para o agent, porque tipos e nomes exatos não podem ser adivinhados. “Critérios de aceitação” (verde) viram os testes. “Fora de escopo” aponta para o “Refactor de brinde” com um ✕: é o muro que impede o agent entusiasmado de reorganizar o que ninguém pediu. “Perguntas em aberto” vai e volta entre a spec e você, com pacotes nos dois sentidos, porque são perguntas que precisam de resposta antes de codar. Vamos às peças.

Objetivo e porquê

O objetivo diz o que deve existir ao final e para quem, em uma ou duas frases. O porquê explica o problema que isso resolve. Parece enfeite, mas é a peça que mais ajuda nos casos que a spec não previu: um implementador que sabe que o filtro existe “para achar rápido as tarefas do cliente X” decide melhor a ordem dos resultados do que um que só leu “filtro por tag”. Em specs para agents, o porquê vale ouro, pelo mesmo motivo que a seção 11 de Agents recomenda incluir o motivo das decisões no brief.

Contexto

É o que o código não conta: restrições de negócio, integrações, decisões anteriores, o que já foi tentado e falhou. Se a resposta a “por que não usamos a biblioteca X?” é uma conversa de seis meses atrás, o contexto é o lugar de guardá-la em duas linhas.

Escopo e fora de escopo

O escopo lista o que entra. O fora de escopo lista o que alguém poderia razoavelmente esperar e que não entra. A segunda lista é a mais subestimada. No svg-creator, o arquivo specs/features/diagram_text.md tem uma subseção “Fora do escopo desta entrega” que afasta quatro tentações de uma vez: compatibilidade com Mermaid, edição ao vivo sincronizada, geração por linha de comando sem navegador, e estilos finos por nó. Cada item evita uma tarde de trabalho que ninguém queria.

Requisitos

São as frases que dizem o que o sistema faz. A seção “Como escrever requisitos sem ambiguidade”, logo abaixo, trata do cuidado com cada palavra.

Contratos

Tipos, formatos, nomes de campo, códigos de erro, assinaturas de função: tudo o que outra parte do sistema (ou outro agent) vai usar e que, por isso, não pode variar. O arquivo specs/features/edge_connections.md do svg-creator termina com um contrato em TypeScript (type EdgeData = { ... }) que lista cada campo da aresta, com os valores possíveis. Quem implementa a aresta e quem implementa o inspetor lateral partem do mesmo tipo. É exatamente a ideia de “fixar o contrato antes de dividir o trabalho” que a seção 13 de Agents chama de regra central da orquestração.

Critérios de aceitação

Frases que podem ser respondidas com “passou” ou “falhou”. A forma mais conhecida é Given/When/Then (dado, quando, então):

Dado que a lista tem 3 tarefas e nenhuma tag selecionada
Quando o usuário seleciona as tags "bug" e "urgente" no modo "todas"
Então só aparecem as tarefas que têm as duas tags

A outra forma é uma lista de verificação executável: pnpm test src/store passa, incluindo testes para o modo "qualquer", o modo "todas" e a lista de tags vazia. O teste de qualidade é este: dá para escrever o teste sem fazer nenhuma pergunta? Se não dá, o critério ainda está vago.

Casos de borda

Vazio, um, muitos, repetido, enorme, nulo, concorrente, fora de ordem, sem permissão, sem rede. Cada um que você nomeia na spec é um bug que o implementador não precisa descobrir em produção. Para cada requisito, passe os olhos por essa lista e pergunte “e se?”.

Perguntas em aberto e decisões

Perguntas em aberto são honestidade: o que ainda não se sabe, com um dono e um prazo. Uma spec que finge saber tudo é pior do que uma que lista três dúvidas. Decisões registram o que foi escolhido e o porquê (um ADR em miniatura, que a seção 13 compara com ADRs de verdade). As duas peças tornam a spec um documento vivo, em que cada dúvida resolvida vira decisão e some da lista de perguntas.

Como escrever requisitos sem ambiguidade

Um requisito ambíguo é uma promessa de retrabalho. Quatro hábitos tiram a maior parte da névoa.

O primeiro é usar verbos de obrigação consistentes. “Deve”, “não deve” e “pode” têm pesos diferentes, e a RFC 2119 (o padrão que a internet usa para isso) define DEVE, NÃO DEVE, DEVERIA e PODE com significados fixos. Você não precisa citar a RFC, mas precisa escolher: “deve” para o que é obrigatório, “pode” para o que é opcional, e nada de “tenta”, “procura”, “idealmente”.

O segundo é trocar adjetivos por números. “Rápido” não verifica; “responde em até 300 ms no percentil 95, com 100 usuários simultâneos” verifica. “Muitos itens” vira “até 10.000”. “Recente” vira “dos últimos 7 dias”.

O terceiro é dar um exemplo concreto. Um exemplo é um mini-teste que o leitor consegue rodar de cabeça. O exemplo do frete grátis da seção 3 (R$ 199,99 contra R$ 200,00) desambigua o “igual ou acima” de uma vez.

O quarto é dar um contraexemplo, isto é, dizer o que não é. “O filtro combina tags com E. Não é busca por texto: digitar no campo de busca não afeta este filtro.” O contraexemplo fecha a porta que o exemplo deixou entreaberta.

Existe também uma notação padronizada para requisitos, a EARS (Easy Approach to Requirements Syntax), criada por Alistair Mavin e colegas, que ajuda a escrever frases com a mesma forma. Seus padrões, segundo a página do autor:

Um requisito EARS de verdade: “Quando o usuário seleciona uma tag removida, o sistema deve retirá-la do filtro e mostrar todas as tarefas que casam com as tags restantes”. Perceba como a forma obriga a nomear gatilho e resposta, que é onde a ambiguidade costuma morar.

Para fixar, veja alguns requisitos vagos e a reescrita:

6. Anatomia de uma spec de verdade (svg-creator)

Teoria é mais fácil de lembrar com um caso real, e o svg-creator oferece um com a vantagem de ter specs de qualidades diferentes. Todos os caminhos abaixo são relativos à raiz do projeto.

Uma spec boa, e como ela evoluiu

O arquivo specs/elements/go/channel.md descreve o elemento “canal” do Go. Ele tem uma visão geral (a semântica e a palavra-chave na DSL), características geométricas e visuais, comportamentos com uma tabela de estados, e um exemplo da linguagem. Mais importante do que a estrutura é a história do arquivo no git. Na última versão commitada, a linha do estado “fechado” era assim:

| Fechado (`close`) | `badge="closed:danger" borda=tracejada` |

e na versão em edição ficou assim:

| Fechado (`close`) | `fechado=sim` (boca de envio selada em vermelho com ✕; o buffer continua visível, pois um canal fechado ainda entrega o que já guardava); é o campo `channelClosed` |

Duas coisas aconteceram. Primeiro, a spec ganhou precisão: não basta dizer “fechado”, a nova linha diz o que se vê (a boca selada), o que continua valendo (o buffer, porque em Go um canal fechado ainda entrega o que já guardava) e o nome do campo de dados (channelClosed). Segundo, a mesma revisão trouxe uma regra para o “envio barrado” (anim=bloqueado na aresta que chega ao canal, e cor-pacote âmbar para canal cheio, que é espera e não erro). A decisão sobre cores carrega o porquê dentro da frase, exatamente como a seção 5 recomenda.

Da spec ao teste

A figura mostra o que uma única linha dessa spec produziu no código.

No grupo de cima estão duas peças da spec, “Estado fechado” e “Envio barrado”. A primeira se desdobra em dois testes (setas laranja grossas): um de camada da DSL, em src/utils/diagramText/go.test.ts, que confere que o texto fechado=sim (e os sinônimos fechado e closed) vira channelClosed: true e que a escrita de volta devolve fechado=sim; e outro visual, em src/elements/shapes/ChannelShape.test.ts, que confere que a tampa só é desenhada com channelClosed e que as células do buffer continuam lá (o teste compara a quantidade de células preenchidas do canal fechado com a do canal aberto). Cada teste fala com um pedaço do código (grupo de baixo), e as setas de dupla direção mostram o ritmo vermelho-depois-verde: o pacote rosa desce (o teste nasce falhando), o verde sobe (passa depois da implementação). O “Envio barrado” tem um ✕ no caminho porque a spec dele descreve justamente algo que é barrado.

O que há de didático aqui é a rastreabilidade: dá para apontar uma frase da spec e achar os testes que a protegem, e dá para apontar um teste e achar a frase que o justifica. Quando a spec muda, o teste sinaliza o que precisa mudar; quando o teste quebra, a spec diz se o comportamento era intencional.

Specs mais vagas, para comparar

Nem todo arquivo da pasta tem esse nível, e comparar ajuda a enxergar o que falta. O arquivo specs/elements/rectangle.md tem catorze linhas e diz coisas como “Bordas: ligeiramente arredondadas (border radius) para visual moderno” e “pode ser esticado desproporcionalmente sem perdas visuais”. Nenhuma dessas frases pode ser verificada: quanto é “ligeiramente”? O que é “perda visual”? Se um agent mudar o raio da borda de 8 para 12, a spec não protesta.

Já specs/features/grouping_containers.md tem bons pontos (containers colapsáveis, arestas agregadas) e frases que pedem exemplo, como “a seleção e foco dão preferência aos filhos, não ao contêiner pai”. Preferência em que situação? Clique num ponto onde o filho e o pai se sobrepõem? Isso é o tipo de dúvida que uma linha de critério resolve:

Dado um container com um filho que ocupa o canto superior esquerdo
Quando o usuário clica dentro da área do filho
Então o filho é selecionado, e não o container

Uma comparação lado a lado:

A moral não é criticar quem escreveu a spec do retângulo, que descreve uma forma simples e estável. É mostrar que o nível de detalhe deve acompanhar o risco: onde há estados, interações e bordas (o canal), a precisão compensa; onde o elemento é trivial, uma frase basta. A seção 8 volta a isso sob o nome de granularidade.

Parte 3: Criar specs

7. Do pedido vago à spec, passo a passo

A habilidade central do SDD é transformar “quero um filtro por tag” em algo que ninguém precise adivinhar. O método tem seis passos e cabe em uma tarde.

Leia a figura da esquerda para a direita. O pedido (laranja) entra em um entrevistador, que é um agent com um prompt feito para perguntar. Ele dispara cinco perguntas em sequência (o atraso entre os pacotes mostra isso), e cada pergunta volta com uma resposta (pacotes amarelos). As respostas viram frases em um rascunho de spec (azul), e esse rascunho passa por um losango de leitura crítica: “dá para escrever o teste de cada critério?”. Se sim, a spec é aprovada (verde). Se não, o critério está vago, e a seta rosa leva de volta a mais perguntas. Esse laço é a parte importante, porque é onde a qualidade é decidida.

Passo 1: comece pelo pedido cru

Escreva o pedido como ele chegou, sem enfeitar: “Adicione filtro por tag na lista de tarefas”. Ele é o ponto de partida e também o contraexemplo: é uma frase que parece completa e não é.

Passo 2: entreviste o pedido

Entrevistar o pedido é o hábito que mais muda a qualidade das specs. Em vez de começar a escrever, faça perguntas até a lista de dúvidas acabar. Um bom roteiro de entrevista cobre sempre as mesmas áreas:

• Quem usa e para quê? (O porquê.)
• Qual é o comportamento principal em um exemplo concreto? (Requisito.)
• O que acontece no vazio, no excesso, no repetido e no erro? (Bordas.)
• O que não faz parte? (Fora de escopo.)
• Isso persiste, a quem pertence, quem pode ver? (Dados e permissões.)
• Como vou saber que ficou certo? (Critérios.)

Para o filtro por tag, as cinco perguntas da figura seriam: E ou OU? Lista vazia? Persiste ao recarregar? O que acontece se a tag em uso for removida? O que fica de fora? Cada uma vem com uma resposta decidida por você: E (todas as tags), lista vazia mostra tudo, não persiste (só em memória), a tag removida sai do filtro, e busca por texto fica fora.

Você pode fazer essa entrevista sozinho, com um colega, ou pedindo a um agent que a conduza. Um prompt útil para o agent:

Vou descrever uma feature em uma linha. Não escreva código nem spec ainda.
Faça uma pergunta por vez, a mais importante primeiro, sobre: usuário e objetivo,
comportamento em exemplos concretos, casos de borda, o que fica de fora, dados e
critérios de aceitação. Quando eu disser "chega", escreva o rascunho da spec.

O “uma pergunta por vez” evita o despejo de quinze perguntas que ninguém lê, e o “a mais importante primeiro” faz o agent priorizar. Existe um efeito colateral bom: a própria resposta “não sei, decide você” revela uma decisão que alguém precisava tomar e que, sem a entrevista, teria sido tomada em silêncio pelo código.

Passo 3: escreva o rascunho

Com as respostas na mão, o rascunho sai quase sozinho. Cada resposta vira uma ou duas frases. Veja o resultado para o filtro por tag, já no formato completo:

# Filtro por tag na lista de tarefas

## Objetivo e porquê
Permitir que o usuário veja só as tarefas com certas tags, para achar rápido o trabalho de um cliente
ou de um tipo (bug, urgente) em listas com dezenas de tarefas.

## Contexto
O estado das tarefas vive em `src/store/tasks.ts` (Zustand). O filtro fica no store; a interface só lê o resultado.
Não usar `useEffect` para filtrar.

## Escopo
- Selecionar de 1 a 10 tags.
- Modo `all` (padrão): a tarefa precisa ter todas as tags selecionadas. Modo `any`: basta uma.
- O filtro vale só para a lista atual e vive em memória.

## Fora de escopo
- Busca por texto.
- Persistir o filtro entre sessões.
- Criar ou renomear tags.

## Requisitos
- R1. O sistema DEVE mostrar apenas as tarefas que casam com o filtro, no modo escolhido.
- R2. Com lista de tags vazia, o sistema DEVE mostrar todas as tarefas.
- R3. Quando uma tag selecionada for removida do sistema, o sistema DEVE retirá-la do filtro.
- R4. A 11ª tag selecionada DEVE ser ignorada, com o aviso "Máximo de 10 tags".

## Contrato
type TagFilter = { tags: string[]; mode: 'any' | 'all' }
setTagFilter(filter: TagFilter): void
selectVisibleTasks(state): Task[]

## Critérios de aceitação
- Dado 3 tarefas (A: [bug], B: [bug, urgente], C: []), quando o filtro é {tags:[bug,urgente], mode:'all'},
  então só B aparece.
- O mesmo filtro com mode 'any' mostra A e B.
- Com tags: [], mostra A, B e C.
- `pnpm test src/store` passa, com um teste para cada critério acima.

## Casos de borda
- Tag inexistente no filtro: o filtro a ignora (não zera a lista).
- Tarefa sem tags nunca casa com um filtro não vazio.

## Perguntas em aberto
- A ordem das tarefas filtradas segue a ordem da lista original? (Dono: você. Decidir antes da fatia B.)

## Decisões
- Modo padrão `all` porque o uso típico é afunilar ("bug E urgente"), não ampliar.

Passo 4: leia como um implementador cético

Releia a spec fingindo que você nunca viu o projeto. Para cada critério, pergunte: dá para escrever o teste sem fazer uma pergunta? Para cada requisito, procure adjetivos sem número e verbos fracos. Onde achar, volte ao passo 2, o laço rosa da figura. É melhor descobrir essa lacuna agora do que no review de um PR com oitocentas linhas.

Passo 5: fixe o contrato e as fatias

Se o trabalho vai ser dividido (entre pessoas ou agents), escreva os tipos e assinaturas na spec e liste as fatias com arquivos disjuntos. No exemplo, a fatia A é o store, a fatia B é a interface, e o contrato de TagFilter permite que a B comece sem esperar a A.

Passo 6: aprove antes de codar

Alguém (você, um colega) lê e aprova. A aprovação é o momento em que a spec deixa de ser rascunho. O selo “v1” verde na figura marca isso. Um jeito prático de fazer isso em time é abrir a spec como PR e revisar o texto antes do código existir: discutir “lista vazia mostra tudo?” em um comentário de PR custa um minuto, e discutir o mesmo depois da implementação custa um dia.

Antes e depois

Para encerrar a seção, veja os dois extremos lado a lado. O antes:

Adicione filtro por tag na lista de tarefas.

O depois é a spec acima. A diferença em tamanho é de uma linha para cerca de quarenta. Em tempo, é de dez segundos para vinte minutos. Em decisões tomadas por escrito, é de zero para oito. E o custo de cada uma dessas oito decisões, se tomadas pelo código sem ninguém notar, seria descoberto em outra hora e de outra forma.

8. Spec curta ou longa, granularidade e spec viva

Curta ou longa

Existe uma tensão real. Specs curtas são lidas e mantidas; specs longas cobrem mais e acabam sem leitor. O critério prático é proporcionalidade: o tamanho da spec deve acompanhar o custo de errar. Uma mudança de texto em um botão pede uma linha. Um endpoint novo pede uma página. Um fluxo de pagamento pede spec, plano e tarefas, com contratos e revisão.

O artigo do site de Martin Fowler sobre ferramentas de SDD traz um exemplo do excesso: o autor relata que, para um bug pequeno, o Kiro gerou quatro histórias de usuário com dezesseis critérios de aceitação, o que ele achou muito mais do que o problema pedia, e que o Spec Kit pareceu exagerado para uma história de 3 a 5 pontos. Isso vale como aviso: a ferramenta não decide o tamanho da spec por você. Quem decide é você, olhando o risco.

Granularidade

Granularidade é o tamanho da unidade que uma spec cobre. Uma spec por feature (por exemplo, “filtro por tag”) costuma ser boa, porque a feature tem objetivo próprio e cabe em uma leitura. Uma spec por função é fina demais, vira comentário de código. Uma spec por produto inteiro é grossa demais, vira o romance da seção 14. No svg-creator, a divisão em specs/features/ (comportamentos transversais, como arestas e agrupamento) e specs/elements/ (um arquivo por elemento, com os do Go numa subpasta) é um exemplo de granularidade natural: um arquivo para cada coisa que tem estados e bordas próprios.

Duas regras ajudam a calibrar. A primeira é que uma spec deve caber na cabeça de quem implementa: se você precisa de um índice para navegar nela, quebre. A segunda é que cada spec tem um dono claro de leitura: quem vai implementar e quem vai verificar.

Manter a spec viva e versionada

Uma spec envelhece quando o código muda e ela não. A figura mostra os dois destinos.

No grupo de cima, o caminho sem disciplina: a spec de março diz “lista vazia = tudo”, três PRs mexem só no código ao longo de meses (a seta lenta “meses passam”), e a spec de setembro (em rosa, com estado degradado) continua dizendo a mesma coisa, que agora pode estar errada. Quando um agent recebe essa spec como brief, ele confia nela (pacotes rosa) e implementa o que está escrito, o que produz uma regressão. Ou seja, uma spec desatualizada é pior do que nenhuma, porque ela confere autoridade a uma informação velha. No grupo de baixo, o caminho com disciplina: o PR que muda comportamento passa por uma pergunta no losango (“tocou na spec?”). Se sim, a seta verde grossa leva ao merge, e se não, o ✕ bloqueia e o PR volta ao autor.

Cinco práticas fazem esse segundo caminho acontecer:

1. A spec mora no mesmo repositório do código, perto dele (uma pasta specs/ ou ao lado do módulo), e entra no mesmo PR. Spec em wiki separado é spec que ninguém atualiza.
2. Um item no template de PR: “Mudou comportamento? Atualizei a spec.” A pergunta custa dois segundos e cria o hábito.
3. Critérios que viram testes. Quando o comportamento muda e o teste quebra, o teste obriga a revisitar a spec. É a defesa automática mais forte contra deriva.
4. Mudanças de comportamento começam pela spec (o laço rosa do ciclo na seção 4). Quando a ordem é spec, depois código, a spec nunca fica para trás por esquecimento.
5. Cada spec tem um estado visível (rascunho, aprovada, implementada, obsoleta) e specs obsoletas são marcadas ou removidas. Uma pasta cheia de specs que ninguém sabe se valem é um cemitério.

Há uma abordagem alternativa usada pelo OpenSpec, que a seção 11 descreve: em vez de reescrever a spec inteira a cada mudança, cada mudança traz um delta (o que foi adicionado, modificado ou removido), e ao arquivar a mudança o delta é fundido nas specs principais. Isso mantém o histórico de por que cada requisito entrou.

Parte 4: SDD com agents de IA

9. A spec como brief e como contrato

Se você leu Agents, já conhece o brief: a mensagem de delegação que é a única ponte entre a conversa principal e um subagent, porque o subagent não herda o histórico (seção 5 daquela aula). O brief tem sete partes (seção 11): objetivo, contexto, escopo, fora de escopo, contratos, critério de pronto e formato do relatório. Compare com a anatomia da seção 5 desta aula. É praticamente a mesma lista. Isso não é coincidência: um brief é uma spec de uma tarefa, e uma spec de feature é um brief para a feature inteira.

A diferença está no tempo de vida e na escala. O brief morre quando a tarefa acaba, e a spec fica. O brief cobre uma fatia, e a spec cobre a feature de onde as fatias saem. Na prática, o fluxo sensato é: a spec da feature é a fonte, e o brief de cada fatia é um recorte dela mais o contrato e o critério de pronto daquela fatia. O orquestrador não reinventa o contexto a cada delegação, ele copia da spec.

A figura percorre isso de cima para baixo. O grupo “Brief” reúne a spec aprovada e os contratos. O orquestrador lê a spec inteira (seta laranja grossa) e dispara os briefs das fatias para os workers com atraso entre os pacotes, que é o jeito de mostrar a distribuição. Os dois workers trabalham em arquivos disjuntos (só src/store e só src/components) e cada um num worktree, a cópia isolada do repositório que Agents explica na seção 6. As linhas pontilhadas azuis dos contratos para os dois workers mostram a regra central: a interface está fixada antes da divisão, então o worker B não precisa esperar o A existir. Os diffs sobem para a suíte inteira (verde), depois para o reviewer de contexto limpo, e daí para você.

O caminho rosa é o mais ensinativo. Quando o worker B esbarra em algo que a spec não diz (um “Lacuna na spec”), o comportamento desejado é que ele pergunte, não que chute. A pergunta sobe até você, que decide e atualiza a spec, em vez de deixar a decisão se esconder no código. Esse é um efeito colateral valioso do SDD com agents: as lacunas da spec ficam visíveis como perguntas em vez de invisíveis como suposições. Para que isso aconteça, o brief precisa dizer explicitamente “se a spec não cobrir um caso, pare e devolva a pergunta”, exatamente como a seção 11 de Agents pede para o agent dizer o que não conseguiu fazer.

Contrato primeiro, depois paralelismo

A seção 13 de Agents mostra o pipeline de uma feature (explorar, planejar com contratos, implementar em paralelo, testar, revisar, você decide). Em termos de SDD, a etapa 2 daquele pipeline, “planejar com contratos”, é exatamente a fase de especificar e planejar. As fatias só são seguras em paralelo porque os tipos foram escritos antes. Uma spec boa já traz esse material pronto. Uma spec sem contratos obriga o arquiteto a reconstruí-los, e é aí que o trabalho paralelo começa a divergir.

10. Camadas de contexto: steering, constitution e a spec da feature

Agents precisam de contexto, mas contexto demais é tão ruim quanto contexto de menos. A janela de contexto de um modelo é limitada, e despejar tudo nela dilui o que importa. A solução do ecossistema é separar o contexto em camadas, carregadas em momentos diferentes.

Na figura, três grupos alimentam o agent no centro, e a espessura da seta indica a frequência. A camada 1 é o projeto (arquivos como CLAUDE.md ou AGENTS.md, e o que o Spec Kit chama de constitution ou o Kiro chama de steering): comandos de build, convenções, regras que valem sempre. A seta é fina e cinza, “todo turno”, porque esse conteúdo vai para toda conversa, e por isso precisa ser enxuto. A camada 2 é a feature: a spec e o plano daquela funcionalidade, carregados quando você trabalha nela (seta média). A camada 3 é a tarefa: o brief da fatia, a seta grossa laranja, o que importa agora. O elemento rosa à direita é o anti-padrão: colar “todas as specs do projeto” no prompt, o que satura a janela e gera ruído, e o ✕ mostra que isso afoga o sinal.

Cada ferramenta nomeia essas camadas à sua maneira. Pela documentação do Kiro (consultada em 15 de outubro de 2026), arquivos de steering são Markdown que dá ao agent conhecimento persistente do projeto; ficam em .kiro/steering/ no workspace (ou ~/.kiro/steering/ para valer em todos), e o Kiro pode gerar três arquivos de base: product.md (propósito, usuários, metas de negócio), tech.md (frameworks, bibliotecas, restrições técnicas) e structure.md (organização de arquivos, convenções de nome, arquitetura). Há modos de inclusão: always (padrão), fileMatch (carrega quando se trabalha em arquivos que casam com um padrão), manual (só quando você referencia) e auto (quando o Kiro julga que o pedido casa com a descrição). A mesma página diz que arquivos AGENTS.md são sempre incluídos. No Spec Kit, o passo constitution define os princípios do projeto uma vez por projeto, e o artigo no site de Martin Fowler descreve a constitution como princípios de alto nível, pensados para serem imutáveis e aplicados a toda mudança. No Claude Code, o equivalente é o CLAUDE.md, que Agents cita como parte do que um subagent recebe.

A regra de bolso é decidir onde cada informação mora pelo ritmo de mudança. Mora na camada 1 o que muda raramente e vale para tudo (“usamos pnpm”, “testes em Vitest”, “sem travessão nos textos”). Mora na camada 2 o que vale para uma feature. Mora na camada 3 o que vale para uma tarefa. Colocar uma regra de uma feature na camada 1 a faz custar tokens em todas as conversas, e colocar uma regra global só na spec de uma feature a faz sumir nas outras.

11. O ecossistema de ferramentas

Nos últimos anos surgiram ferramentas que estruturam o SDD com agents. Elas variam em forma, mas compartilham um esqueleto: uma spec, um plano, uma lista de tarefas e a implementação guiada por esses arquivos. Esta seção resume o que cada uma é segundo a documentação oficial consultada em 15 de outubro de 2026. Tudo isso evolui rápido, então trate os nomes de comandos como fotografia de uma data.

A figura coloca as quatro ferramentas em quatro grupos com o mesmo vocabulário de cores: laranja para o que expressa intenção (a spec), azul para plano e tarefas, e o agent em escuro. Observe como o esqueleto se repete: constitution ou steering primeiro, depois a spec, depois plano e tarefas, depois a implementação. A diferença está em onde cada ferramenta se apoia e em quanto a spec permanece depois da tarefa.

GitHub Spec Kit

O Spec Kit é um kit de código aberto, do GitHub, que dá aos agents de código processos estruturados, modelos reutilizáveis e resultados documentados. O fluxo central é o SDD, e há processos adicionais para correção de bugs e avaliação de ideias. Segundo o README consultado, os comandos principais, que você invoca como skills dentro do chat do seu agent (e não no terminal), são: /speckit-constitution (princípios do projeto, uma vez por projeto), /speckit-specify (escreve a spec da feature), /speckit-plan (plano técnico), /speckit-tasks (quebra em tarefas), /speckit-implement (implementa contra os artefatos) e /speckit-converge (repete com implement até reportar “Converged”). A página também menciona etapas opcionais de clarificação, checklist e análise de consistência, sem nomear os comandos, e avisa que outros agentes podem usar sintaxe de invocação diferente. A instalação documentada usa o CLI specify: uv tool install specify-cli, depois specify init my-project --integration copilot (o valor de --integration escolhe o agent). Requisitos: Python 3.11 ou superior, uv e um agent de código suportado. A página consultada não descreve a estrutura de pastas criada pelo specify init, então confira essa parte na documentação.

Kiro

O Kiro é um ambiente (IDE, CLI e web) da AWS em que cada spec produz três arquivos, segundo a documentação de specs. requirements.md traz histórias de usuário e critérios de aceitação (para bugs, vira bugfix.md, com análise do comportamento atual, esperado e inalterado). design.md traz a arquitetura técnica, diagramas de sequência, fluxo de dados, tratamento de erros e estratégia de testes. tasks.md traz o plano de implementação com acompanhamento de status. As fases são requisitos, design e tarefas. Há variantes: specs de feature com fluxo “requirements-first” ou “design-first”, specs de bugfix, e a Quick Spec, que gera os três arquivos de uma vez sem portões de aprovação. Ao executar todas as tarefas, o Kiro monta um grafo de dependências e agrupa as independentes em ondas que rodam em paralelo, e as ondas rodam em sequência. A página não fala de EARS, e os assuntos de steering e hooks ficam em outras páginas (a de steering está na seção 10).

OpenSpec

O OpenSpec é um framework de SDD para assistentes de código que adiciona uma camada leve de especificação, para que você e a IA concordem no que construir antes de qualquer código. A estrutura mostrada na documentação: openspec/specs/ guarda as specs atuais do projeto; openspec/changes/<nome>/ guarda uma mudança em andamento, com proposal.md (por quê e o quê), specs/ (requisitos e cenários), design.md (abordagem técnica) e tasks.md (checklist de implementação); openspec/changes/archive/<data>-<nome>/ guarda mudanças concluídas. Os comandos: /opsx:explore (pensar livremente, opcional), /opsx:propose <nome> (cria a pasta da mudança), /opsx:apply (o agent percorre as tarefas) e /opsx:archive (move a mudança para o arquivo com prefixo de data e atualiza as specs). Os arquivos de spec começam com um cabeçalho como ## ADDED Requirements, com requisitos em ### Requirement: e cenários em #### Scenario: com passos WHEN/THEN. A página não usa o termo “delta spec”, mas o formato implica esse conceito. Suporta mais de 30 assistentes, com grafia de comando que varia por ferramenta (/opsx:propose, /opsx-propose, @opsx-propose, $openspec-propose), e exige Node.js 20.19.0 ou superior (npm install -g @fission-ai/openspec@latest, depois openspec init).

Do ponto de vista dos níveis da seção 4, o OpenSpec é o que mais se aproxima de spec-anchored: a pasta specs/ é o retrato atual do sistema e cada mudança a atualiza no arquivamento.

Tessl

O Tessl tem dois produtos. O Spec Registry permite adicionar pacotes de specs como dependências do projeto, instalados localmente como uma biblioteca, para que o agent receba informações corretas sobre APIs e versões em vez de alucinar; o lançamento falava em mais de 10 mil specs prontas, e é possível publicar as suas. O Tessl Framework é a camada de fluxo: usa specs para definir o que construir antes de codar, guarda essas instruções no código como memória de longo prazo e se integra a agents (Claude Code, Cursor, Codex, Gemini CLI e outros) via MCP (veja MCP). Sobre o estado: o artigo de Martin Fowler descreve o Framework em beta privado e como o único dos três que mirava explicitamente o nível spec-anchored e explorava spec-as-source (com código marcado como // GENERATED FROM SPEC - DO NOT EDIT, uma spec por arquivo de código e não-determinismo observado ao regenerar). Uma análise de 2026 encontrada na pesquisa indica que o Framework ainda não parecia ter chegado a disponibilidade geral, mas não consegui confirmar o status atual na fonte oficial, então verifique no site da Tessl antes de planejar em cima dele.

Como escolher

Você não precisa de nenhuma delas para fazer SDD. Uma pasta specs/ e disciplina de PR já dão spec-first e boa parte do spec-anchored, que é o que o svg-creator faz. As ferramentas valem quando você quer padronizar o fluxo em um time, ter comandos prontos para agents ou automatizar a quebra em tarefas. O artigo de Fowler faz a crítica útil: com um fluxo fixo para problemas de tamanhos diferentes, as ferramentas tendem ao exagero em tarefas pequenas, revisar muito Markdown pode ser mais cansativo do que revisar código, e os agents nem sempre seguem todas as instruções, o que cria uma falsa sensação de controle. Um teste sensato antes de adotar: aplique a ferramenta a uma feature real de tamanho médio e compare com fazer a spec à mão. Se a ferramenta produziu mais arquivos do que decisões, ela está pesada para o seu caso.

12. Verificar contra a spec

Uma spec que não é verificada vira sugestão. A verificação, no SDD com agents, tem três camadas, e a primeira já foi mostrada.

A primeira é executável: cada critério de aceitação vira um teste, e o critério de pronto de cada fatia é um comando (pnpm test src/store). É o ambiente respondendo, e não o agent opinando. A seção 15 de Agents resume: “Implementei e os testes passam” é uma afirmação que só vira fato depois que alguém roda o teste.

A segunda é a revisão com contexto limpo. Um agent revisor recebe a spec e o diff, não o histórico do implementador, e procura desvios: requisito sem código, código sem requisito (o refactor de brinde), caso de borda ignorado. A pergunta que ele responde é “o diff cumpre cada linha da spec?”. Peça que ele aponte, para cada requisito, o arquivo e a linha que o atende, e que diga explicitamente quais não encontrou.

A terceira é humana: você lê o diff contra a spec. Um truque que acelera: leia primeiro a lista de critérios, depois procure no diff o teste de cada um. Se faltar teste, falta verificação, mesmo que o código esteja certo.

Um cuidado: a spec só protege o que ela diz. Um agent pode cumprir todos os requisitos e ainda assim criar um problema que a spec não cobria (uma consulta lenta, um vazamento). Por isso o SDD complementa e não substitui testes gerais, linters e revisão de segurança.

Parte 5: Contexto e vícios

13. Onde a spec se encaixa: TDD, BDD, ADR, PRD e OpenAPI

A spec não nasceu sozinha. Há um conjunto de práticas e documentos que respondem a perguntas vizinhas, e confundi-los gera sobreposição e lacunas. O jeito de ordená-los é perguntar a cada um qual pergunta ele responde.

A figura distribui os artefatos em quatro grupos por pergunta. À esquerda, “Por quê construir”: o PRD. Logo abaixo, “Por que assim”: o ADR. No meio, “O quê”: a spec e o OpenAPI. À direita, “Como saber que está certo”: BDD, TDD e o código. As setas contam a ordem de trabalho: o PRD alimenta o recorte da spec (seta cinza), o ADR impõe restrições já aceitas (pontilhada), a spec gera um contrato público (azul) e os cenários de BDD (laranja grossa), os cenários viram testes de TDD, e o ciclo vermelho-depois-verde (pacote rosa na ida, verde na volta) chega ao código.

O PRD (product requirements document, documento de requisitos de produto) descreve o problema de negócio, os usuários e as métricas de sucesso. É um nível acima: diz por que vale a pena construir algo, e pode originar várias specs. Uma spec responde “o quê, exatamente, nesta feature”, em nível de comportamento.

O ADR (architecture decision record, registro de decisão de arquitetura) é um documento curto que registra uma escolha técnica, as alternativas consideradas e o motivo. Ele responde “por que fizemos assim”. A seção “Decisões” de uma spec é um ADR em miniatura, e decisões de peso (escolher um banco, um protocolo) merecem um ADR próprio, referenciado pela spec. A diferença é a durabilidade: uma spec descreve o comportamento atual e muda com ele, enquanto um ADR é um registro histórico e raramente é reescrito (se a decisão muda, escreve-se um novo ADR que substitui o antigo).

O TDD (test-driven development, desenvolvimento guiado por testes) é uma disciplina de implementação: escrever um teste que falha, escrever o mínimo para passar, refatorar. Ele opera no nível do código e dos testes unitários. O SDD fica um degrau acima: diz quais testes valem a pena escrever, porque os critérios de aceitação são a lista deles. Na prática, SDD e TDD se somam: a spec fornece os cenários, e o TDD os implementa em ciclos curtos.

O BDD (behavior-driven development, desenvolvimento guiado por comportamento) é a prática de descrever o comportamento em cenários legíveis por todos, normalmente em Given/When/Then, às vezes executáveis em ferramentas como Cucumber. Os critérios de aceitação de uma spec no formato Given/When/Then são BDD. Você pode fazer SDD usando BDD como linguagem dos critérios, ou usar listas de verificação mais simples, e as duas coisas valem.

O OpenAPI é uma especificação legível por máquina para APIs HTTP: rotas, parâmetros, corpos e códigos de resposta. É um contrato, e é derivável para documentação, clientes e validação. A spec de uma feature diz o que o endpoint faz e em quais casos (as regras, o porquê, as bordas) e o OpenAPI descreve a forma (os campos e tipos). Uma regra como “pedido já enviado responde 409” mora nos dois: a spec explica quando e por quê, e o OpenAPI declara que a resposta 409 existe e qual o seu corpo. Quando um dos dois é gerado a partir do outro, a deriva diminui.

14. Erros comuns e anti-padrões

Quase todo erro de SDD cai em dois extremos: spec de menos, que deixa a IA chutar, e spec de mais, que ninguém lê nem mantém. Os seis padrões abaixo cobrem o segundo extremo e os vícios do primeiro. Cada um vem com o porquê e a saída.

A spec que vira romance

Uma spec de quinze páginas para uma mudança de dois arquivos. Parece rigor, mas o resultado é que ninguém a lê inteira, as partes importantes se perdem no meio e a manutenção custa mais do que o benefício. O sintoma típico é a revisão que aprova sem ler, porque o texto é grande demais. A saída é proporcionalidade (seção 8) e cortar tudo o que o implementador não usaria para decidir algo. Pergunte a cada parágrafo: se eu apagar isto, alguém implementa diferente? Se a resposta é não, apague.

A spec desatualizada

Já vista na seção 8. O porquê é que ela é pior do que a ausência: dá autoridade a uma informação errada, e um agent a segue com a confiança de quem não sabe que está velha. A saída é spec e código no mesmo PR, critérios viram testes, e specs obsoletas marcadas ou removidas.

A spec sem critério verificável

“O sistema deve ser intuitivo e performático.” Ninguém consegue dizer se passou. O porquê do dano é que, sem critério, a verificação vira opinião e a discussão no review vira gosto pessoal. A saída é o teste de escrever o teste: se você não consegue descrever como seria um teste que falha, o requisito ainda é um desejo. Troque por números, exemplos e Given/When/Then.

A spec que descreve implementação em vez de comportamento

“Criar uma tabela filters com índice em tag_id e um hook useTagFilter.” Isso é um plano, não um requisito, e fixa uma solução antes de entender o problema. O dano aparece de dois jeitos: o implementador não pode propor algo melhor, e quando a solução muda a spec precisa mudar sem que o comportamento tenha mudado. A saída é separar o quê (spec) do como (plano), como no ciclo da seção 4. Há uma exceção legítima: contratos (tipos, formatos, assinaturas) pertencem à spec, porque outras partes dependem deles. A regra é descrever na spec as fronteiras que outros enxergam e deixar para o plano o interior.

Over-specification

Especificar cada detalhe, inclusive o que não importa: cor exata do hover, nome interno de cada variável, ordem de cada import. O porquê do dano é que a rigidez tira do implementador (pessoa ou IA) a liberdade de acertar o que você não pensou, e cria uma spec frágil, que quebra com qualquer ajuste. A saída é especificar o que importa para quem consome o resultado e deixar o resto livre. Um critério prático: especifique o que, se mudar, alguém reclamaria.

Big design up front

Escrever todas as specs do projeto antes de codar qualquer coisa. É a versão em papel do modelo cascata, e tem o mesmo problema: você descobre o que não sabia só ao implementar, e as specs escritas antes disso ficam erradas. O autor do artigo no site de Martin Fowler se declara cético de desenhos antecipados pesados e preferir passos pequenos e iterativos. A saída é spec por feature, escrita pouco antes da implementação dela, com a possibilidade de voltar e corrigir (o laço rosa do ciclo).

Há mais um vício, o oposto de todos os anteriores: aprovar a spec sem lê-la. Uma spec que o agent escreveu e que você aprovou por cansaço é uma ilusão de controle. O agent produz texto que parece completo, e o perigo é aceitá-lo sem a leitura cética do passo 4 da seção 7. Leia como se fosse código, porque é.

Resumo dos sintomas e correções:

15. Quando não usar SDD

SDD tem custo: escrever, revisar e manter. Quando o custo passa do benefício, é exagero, e o exagero também é um erro. A figura é uma árvore de decisão.

Comece no círculo à esquerda, o pedido que chegou. A primeira pergunta é a mais barata: cabe em uma frase e o teste é óbvio (um typo, renomear uma variável, ajustar uma cor)? Se sim, siga a seta verde: peça direto, com um prompt e um commit, sem spec. Se não, a segunda pergunta é se o trabalho envolve mais de um arquivo, mais de uma sessão ou mais de uma pessoa, porque aí o contexto vai se perder. Se for pequeno, o caminho “não” leva à última pergunta, a de exploração: se você ainda não sabe o que quer, a spec seria prematura, e há dois destinos. Se o código vai ser jogado fora, faça um protótipo descartável (borda tracejada), sem spec, mas com uma data para jogá-lo fora. Se vai ficar, faça uma entrevista primeiro, e a spec nasce do que você descobrir. Se a resposta à segunda pergunta for sim, a terceira pergunta separa o tamanho: contrato público ou difícil de desfazer (API, migração, formato de dados)? Se sim, spec, plano e tarefas, com contratos fixados e revisão antes de codar (borda dupla). Se não, uma spec curta de uma página (objetivo, critérios, fora de escopo) basta.

Os casos clássicos em que o SDD pesa mais do que ajuda:

1. Mudanças triviais, em que a spec seria maior do que o diff.
2. Exploração e protótipos, em que a spec envelheceria em uma hora.
3. Problemas ainda mal compreendidos, em que o produto e a pesquisa precisam acontecer antes. O artigo no site de Martin Fowler observa que features grandes com requisitos pouco claros provavelmente pedem habilidades de produto e pesquisa que nenhuma ferramenta de SDD substitui.
4. Correção de um bug com causa óbvia, em que o teste que reproduz o bug já funciona como spec.
5. Equipes sem hábito de revisar texto, em que a spec vai ficar sem leitor. Nesse caso comece com a menor spec possível e só cresça se ela for lida.

Um último critério, pessoal: se você percebe que está escrevendo a spec só para cumprir o processo, pare. Spec que ninguém usa para decidir ou verificar nada é papelada. O SDD é um meio de reduzir suposições silenciosas, e quando não há suposição a reduzir, ele não tem o que fazer.

Parte 6: Prática

16. Exercícios

1. Pegue um pedido real seu, de uma linha, e faça a entrevista da seção 7 com um colega ou com um agent. Anote quantas perguntas surgiram que você não tinha respondido sozinho. Esse número é o tamanho da sua zona de suposição.
2. Reescreva cinco requisitos vagos do seu projeto (procure por “rápido”, “amigável”, “suportar vários”) com números, verbos de obrigação e um exemplo. Confira cada um com o teste “dá para escrever o teste sem fazer perguntas?”.
3. Abra specs/elements/rectangle.md no svg-creator e reescreva as seções de bordas e de esticar com critérios verificáveis, no estilo de channel.md. Quantas decisões você teve que tomar que a spec original deixava em aberto?
4. Escolha uma frase de specs/features/grouping_containers.md (“a seleção e foco dão preferência aos filhos”) e escreva três critérios Given/When/Then que a tornem verificável, incluindo um caso de borda (filho e container sobrepostos).
5. Escreva a spec completa de uma feature pequena sua (use o molde da seção 7). Entregue-a, sem explicar nada, a outra pessoa ou a um agent, pedindo só “implemente”. Compare o resultado com o que você tinha em mente. Onde divergiu, qual frase da spec faltava?
6. Pegue uma spec antiga do seu projeto e verifique quantos requisitos ainda são verdade no código. Marque o resultado em três colunas: vale, mudou, não existe mais. A proporção de “mudou” mede o quanto a spec derivou.
7. Instale uma das ferramentas da seção 11 (Spec Kit ou OpenSpec são boas para começar) em um projeto de teste e rode o fluxo completo numa feature de tamanho médio. Compare o número de arquivos gerados com o número de decisões que de fato apareceram. Ela ajudou ou pesou?
8. Repita o experimento do exercício 5 de Agents com spec: dê o mesmo pedido a um agent uma vez como prompt solto e outra como spec aprovada, e compare o código e o número de correções necessárias.

17. Glossário

Parte 7: Aplicações com Claude

18. Levantar requisitos para uma aplicação com Claude

Até aqui, a spec descreveu software que se comporta sempre do mesmo jeito: dada a entrada, sai a mesma saída, e um teste confere. Uma aplicação que chama um modelo de linguagem quebra essa premissa. O mesmo pedido pode render respostas diferentes, e o modelo toma decisões (classificar um e-mail, resumir um contrato, recomendar uma ação) que ninguém programou linha a linha. Isso não torna a spec inútil, torna o levantamento de requisitos mais importante. Quando o comportamento não vem de um if, a única garantia de que ele ficou como você queria é ter dito, por escrito e em termos mensuráveis, o que significa “certo” e o que significa “inaceitável”.

Pense num estagiário muito capaz que começa hoje numa clínica. Antes de deixá-lo atender o telefone, você explica quem liga, o que ele pode resolver sozinho, o que deve passar para um médico e o que jamais pode dizer. Se você pular essa conversa, ele vai improvisar com boa vontade, e o improviso de quem não conhece o terreno costuma errar justamente nos pontos de risco. O levantamento de requisitos para uma aplicação com Claude é essa conversa, só que registrada de modo que um conjunto de testes possa cobrar o resultado.

Esta seção cobre o levantamento de requisitos (Understanding Requirements), a habilidade de descobrir o que um sistema precisa fazer antes de desenhá-lo. Ela segue quatro perguntas, na ordem em que costumam ser respondidas: quem usa, que decisão o modelo toma, o que é inaceitável errar e como transformar tudo isso em critérios que um conjunto de avaliação consegue verificar.

Primeira pergunta: quem usa a aplicação

Uma aplicação tem usuários de verdade, e é raro que seja um só tipo. Uma ferramenta de triagem de chamados de suporte é usada pelo atendente que lê a sugestão do modelo, pelo cliente que escreveu o chamado (e nunca vê a sugestão), pelo gerente que olha os números no fim do mês e, indiretamente, por quem mantém o sistema. Cada papel tem uma tolerância diferente a erro e uma expectativa diferente de tom, de velocidade e de explicação. O atendente quer uma sugestão curta e uma justificativa que ele consiga conferir em segundos. O gerente quer consistência, porque comparar semanas só faz sentido se o modelo classifica do mesmo jeito sempre.

Por isso, vale escrever os papéis e, para cada um, o que ele faz com a saída do modelo. Essa segunda parte é a que mais se esquece. Se a saída é lida por uma pessoa que decide em seguida, um erro ocasional é amortecido por ela. Se a saída alimenta direto outro sistema (um robô que fecha o chamado, uma API que dispara um reembolso), nenhum humano fica entre o erro e a consequência. As mesmas 95% de acerto significam coisas muito diferentes nas duas situações.

Dois exemplos de contextos diferentes mostram o padrão. Num assistente interno que resume reuniões para a equipe, os usuários são colegas, o resumo é conferido por quem esteve na reunião, e um detalhe errado é corrigido numa mensagem. Num fluxo que extrai o valor e o vencimento de boletos recebidos por e-mail e já agenda o pagamento, o usuário final nem vê a saída, e um número trocado vira dinheiro saindo da conta. A pergunta “quem usa” é o que revela essa diferença antes de qualquer linha de código.

Segunda pergunta: que decisão o modelo toma

A frase “usamos IA para atendimento” não é um requisito. Um requisito diz qual decisão específica fica a cargo do modelo, quais são as opções possíveis e o que vem antes e depois dela. Na triagem de chamados, a decisão pode ser “escolher uma entre sete categorias e uma prioridade de 1 a 4”. No extrator de boletos, é “devolver valor, vencimento e beneficiário, ou declarar que não conseguiu”. Escrever a decisão assim obriga a definir o formato da resposta, o conjunto fechado de valores permitidos e, o que é crucial, a saída para o caso de dúvida.

Essa última parte costuma ficar de fora e causa a maioria dos problemas em produção. Todo modelo precisa de uma resposta legítima para “não sei” ou “não se aplica”: uma categoria “outros”, um campo nulo, um valor incerto que encaminhe o caso para uma pessoa. Sem essa saída, o modelo é empurrado a escolher uma das opções mesmo quando nenhuma serve, e o erro sai com cara de acerto. A decisão, portanto, vem acompanhada de uma regra de escalonamento: em que situações o modelo não decide e passa a vez.

Também ajuda separar o que o modelo decide do que o código decide. Regras que têm resposta exata (calcular o total, validar um CPF, checar se o usuário tem permissão) pertencem ao código comum, que é determinístico e barato de testar. O modelo fica com o que exige interpretação de linguagem natural. Um requisito bem levantado traça essa fronteira por escrito, e o principal ganho é que a parte menos previsível do sistema fica pequena e cercada.

Terceira pergunta: o que é inaceitável errar

Nem todo erro pesa igual, e o levantamento de requisitos precisa dizer quais pesam mais. Um erro de tom numa resposta ao cliente é incômodo. Um dado de outro cliente aparecendo na resposta é um incidente de privacidade. Uma ação irreversível executada por engano (apagar registros, enviar um e-mail em massa, aprovar um pagamento) pode ser impossível de desfazer. Três famílias de erro aparecem tantas vezes que valem como roteiro de entrevista.

A primeira é o falso positivo, quando o modelo afirma que algo é verdade e não é. Num filtro de fraude, um falso positivo bloqueia um cliente honesto. Num detector de conteúdo impróprio, remove uma publicação legítima. A segunda é o falso negativo, o oposto: o modelo deixa passar o que devia pegar, como a fraude real que foi aprovada. Quase nunca dá para zerar os dois ao mesmo tempo, porque diminuir um tende a aumentar o outro. Por isso é preciso escolher, por escrito, qual dos dois é mais caro para este produto. Um triador médico prefere acusar doença demais a de menos. Um sistema de moderação de um fórum pequeno talvez prefira o contrário.

A terceira família é a do vazamento e da ação irreversível. Aqui a pergunta é “o que o modelo nunca pode revelar ou fazer, mesmo que o usuário peça com jeito?”. Informações de outros clientes, dados pessoais fora do necessário, instruções internas do sistema, e qualquer ação que não tenha como ser revertida sem custo. A documentação de Anthropic sobre critérios de sucesso lista, entre as dimensões comuns a avaliar, a preservação de privacidade, formulada como a pergunta sobre se o modelo consegue seguir instruções de não usar nem compartilhar certos detalhes. Isso mostra que privacidade é um critério de primeira classe, que se mede como qualquer outro, e não um cuidado de última hora.

Uma forma prática de levantar esses erros é fazer a pergunta do pior dia: imagine que a aplicação saiu no jornal pelo motivo errado, qual foi a manchete? A resposta quase sempre aponta para um erro específico e dá o critério mais importante da spec. Cada manchete imaginada vira um requisito do tipo “o sistema NÃO DEVE”, e cada um deles pede um caso de teste que tente provocar o erro de propósito.

Para as ações irreversíveis, o requisito costuma ser de arquitetura e não de qualidade do modelo: a decisão do modelo vira uma proposta, e uma confirmação (humana ou de um sistema com regras exatas) fica entre a proposta e a execução. Esse é um bom exemplo de requisito que nenhuma melhora de prompt substitui. Se o erro é inaceitável, o desenho não deve depender de o modelo acertar sempre.

Quarta pergunta: como transformar isso em critérios verificáveis

Esta é a ponte com tudo o que a aula ensinou antes. Um critério de aceitação, como visto na seção 5, é uma frase respondida com “passou” ou “falhou”. Para uma aplicação com modelo, o critério ganha uma característica nova: ele é medido sobre um conjunto de exemplos, não sobre um caso, e costuma ser uma taxa em vez de um sim ou não. A documentação de Anthropic sobre critérios de sucesso diz que bons critérios são específicos, mensuráveis, alcançáveis e relevantes, e dá um exemplo para análise de sentimento: em vez de “o modelo deve classificar bem os sentimentos”, algo como um conjunto de teste de 10.000 posts de Twitter diversos em que o modelo atinja F1 de pelo menos 0,85, 99,5% das saídas sem toxicidade, 90% dos erros causando apenas inconveniência (não um erro grave) e 95% das respostas em menos de 200 ms. A própria página observa que termos como “inconveniência” e “erro grave” também precisariam de definição precisa num projeto real, o que reforça um ponto: o critério só vale se alguém concordar sobre o que as palavras querem dizer.

Aplicando isso à triagem de chamados, o caminho tem cinco passos.

Primeiro, escolha as dimensões que importam. A documentação enumera dimensões comuns, entre elas fidelidade à tarefa, consistência, relevância e coerência, tom e estilo, preservação de privacidade, uso do contexto fornecido, latência e preço, e lembra que a maioria dos casos de uso precisa avaliar várias ao mesmo tempo. Nem todas valem para o seu produto. Marque as que valem e descarte o resto de propósito.

Segundo, traduza cada resposta das três primeiras perguntas em uma frase mensurável. Veja como o material do levantamento se converte:

Os números dessa tabela são ilustrativos, inventados para mostrar a forma. Os valores certos para o seu produto saem da conversa com quem sofre o custo do erro, e a documentação sugere basear metas em referências do setor, experimentos anteriores, pesquisa ou conhecimento de especialistas, sem esquecer de que o alvo precisa ser realista para o que os modelos atuais conseguem.

Terceiro, monte o conjunto de avaliação para espelhar o uso real. A documentação da Anthropic sobre desenho de avaliações recomenda três princípios: ser específico à tarefa (refletir a distribuição real do que a aplicação recebe, sem esquecer casos de borda), automatizar a correção sempre que possível e preferir volume a qualidade (mais perguntas com sinal um pouco mais fraco e correção automática valem mais do que poucas perguntas corrigidas à mão com todo o cuidado). Entre os casos de borda que ela cita estão dados de entrada irrelevantes ou inexistentes, entradas muito longas e casos ambíguos em que até pessoas teriam dificuldade de chegar a um consenso. Cada item da sua lista do “pior dia” entra aqui como um grupo de casos propositais.

Quarto, escolha como corrigir cada critério. Quando a resposta é um rótulo fechado, a comparação exata de texto é barata e inequívoca. Quando a qualidade é subjetiva, como o tom, a documentação mostra o uso de um segundo modelo como avaliador, com uma escala de 1 a 5, e recomenda que o avaliador seja um modelo diferente do que gerou a resposta. Quando o critério é uma pergunta de sim ou não sobre o conteúdo (a resposta contém dado pessoal de saúde?), um modelo avaliador também serve, e a página afirma que ele consegue pegar casos sutis que regras fixas deixam passar. Reserve a correção humana para calibrar os avaliadores automáticos e para os casos que ninguém sabe resolver por regra. Não confirmei na documentação a recomendação exata de quando usar correção humana, porque essa parte da página não pôde ser lida por inteiro.

Quinto, escreva o limite de aprovação e o que acontece quando ele não é atingido. Um critério sem consequência é decoração. “Se a taxa de vazamento for maior que zero em qualquer rodada, a mudança não vai para produção” é um requisito de processo que transforma a avaliação em um portão. É o mesmo princípio da seção 12: a verificação vira um comando que passa ou falha, em vez de uma opinião.

Um exemplo completo, na forma de spec

Juntando as quatro perguntas, a parte de requisitos de uma aplicação com Claude pode ficar assim. Repare como ela reaproveita o molde da seção 7 e acrescenta o que é próprio de um modelo.

# Triagem de chamados de suporte

## Objetivo e porquê
Sugerir categoria e prioridade para cada chamado novo, para que o atendente comece
pelos mais urgentes. O atendente sempre confirma antes de qualquer ação.

## Usuários
- Atendente: lê a sugestão e a justificativa de uma linha; decide.
- Gerente: lê o relatório semanal; precisa de classificação consistente entre semanas.
- Cliente: nunca vê a sugestão.

## Decisão do modelo
Escolher 1 entre 7 categorias e uma prioridade de 1 a 4. Se não houver base
suficiente, devolver categoria `incerto` e encaminhar a um humano.

## O que o código decide (não o modelo)
Verificar permissão, calcular SLA, enviar a resposta ao cliente.

## Inaceitável
- Chamado de segurança com prioridade 3 ou 4 (falso negativo).
- Qualquer identificador de outro cliente na saída (vazamento).
- Resposta enviada ao cliente sem confirmação humana (ação irreversível).

## Critérios de aceitação (conjunto de 500 chamados rotulados, mais 40 casos de borda)
- C1. Categoria igual à rotulada em pelo menos 90% dos casos.
- C2. Chamados de segurança com prioridade 1 ou 2 em pelo menos 99% dos casos.
- C3. Nos 40 casos ambíguos, `incerto` em pelo menos 80%.
- C4. Zero identificadores de outros clientes nos casos de vazamento.
- C5. 95% das respostas em menos de 2 segundos.

## Perguntas em aberto
- Qual é a meta aceitável de F1 por categoria rara? (Dono: gerente de suporte.)

Um detalhe sobre esse exemplo: ele registra o porquê de cada exigência próximo da exigência, e deixa uma pergunta em aberto com dono, exatamente como a seção 5 recomenda. Os números são ilustrativos e precisam ser substituídos pelos que o seu negócio aceita.

Armadilhas do levantamento

A primeira armadilha é medir só a média. Uma taxa de acerto de 95% esconde que os 5% errados podem estar todos na categoria que mais importa. Por isso a tabela acima tem critérios separados para os subconjuntos de risco, e não só um número global.

A segunda é escrever o critério depois de ver os resultados. Se você fixa a meta olhando o que o modelo já consegue, o conjunto de avaliação só confirma o que já existia. Escreva as metas antes de rodar a primeira vez, pelo mesmo motivo que a spec vem antes do código.

A terceira é deixar o conjunto de avaliação envelhecer. Os exemplos refletem os usuários de hoje, e os usuários mudam. Trate o conjunto como a spec: versionado, no repositório, e revisto quando aparecer um erro em produção que ele não previu. Um erro novo em produção é, de preferência, transformado em um caso novo de teste.

A quarta é esquecer que o modelo, o prompt e os dados mudam. Toda troca de versão do modelo ou de texto do prompt é uma mudança de comportamento, e a mesma regra de “nenhum PR muda comportamento sem mudar a spec” se aplica, agora com o conjunto de avaliação como o teste que acusa a regressão. Para o lado de recuperação de documentos em sistemas com RAG, veja Avaliação de RAG. Para entender o que o modelo recebe e devolve, veja LLMs, e para o texto que guia o modelo, veja Prompt e contexto.

Exercícios desta seção

1. Escolha uma aplicação com modelo que você usa ou gostaria de construir. Liste os papéis de usuário e, para cada um, o que ele faz com a saída do modelo. Marque onde não há humano entre o erro e a consequência.
2. Escreva a decisão do modelo como “escolher entre N opções” e defina a saída para dúvida. Depois separe o que o código decide.
3. Faça a pergunta da manchete de jornal e escreva três requisitos “NÃO DEVE”. Para cada um, escreva três casos de teste que tentem provocar o erro.
4. Reescreva o critério “o modelo deve responder bem” em quatro critérios mensuráveis, com número, tamanho do conjunto de teste e forma de correção.
5. Monte um conjunto de 20 exemplos para o seu caso, dos quais pelo menos 5 sejam de borda (entrada vazia, muito longa, ambígua). Rode o modelo e registre quais critérios falharam antes de mexer no prompt.

Fontes

Consultadas em 15 de outubro de 2026.

• GitHub Spec Kit: o que é, comandos /speckit-*, instalação com specify, requisitos.
• Kiro: specs: arquivos requirements.md, design.md e tasks.md, fases, tipos de spec, ondas de tarefas.
• Kiro: steering: arquivos de steering, locais, arquivos de base e modos de inclusão.
• OpenSpec: estrutura de pastas, comandos /opsx:*, formato das specs, ferramentas suportadas.
• Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl: definições de spec-first, spec-anchored e spec-as-source, e a análise crítica das três ferramentas.
• Tessl: Spec Registry e Framework: produtos e estado (o status atual do Framework não foi confirmado).
• EARS, Easy Approach to Requirements Syntax: os padrões de requisito.
• Anthropic: define success criteria: propriedades de bons critérios, dimensões comuns e o exemplo de sentimento (seção 18). Consultada em 18 de outubro de 2026; o fim da página não foi lido.
• Anthropic: create strong empirical evaluations: princípios de desenho de avaliações, casos de borda e métodos de correção (seção 18). Consultada em 18 de outubro de 2026; o fim da página não foi lido.
• Projeto svg-creator (somente leitura): specs/elements/go/channel.md, specs/elements/rectangle.md, specs/features/edge_connections.md, specs/features/grouping_containers.md, specs/features/diagram_text.md, src/utils/diagramText/go.test.ts e src/elements/shapes/ChannelShape.test.ts.

Sem fonte consultada (escrito do conhecimento geral do autor): a origem do termo vibe coding (Andrej Karpathy, 2025), a RFC 2119, as definições de TDD, BDD, ADR, PRD e OpenAPI, e a atribuição do Kiro à AWS. Na seção 18, o roteiro de quatro perguntas, a pergunta da manchete, o exemplo da triagem de chamados e todos os números dele são do autor, sem fonte, e ilustrativos.

Relacionados

• Agents
• MCP
• LLMs
• Prompt e contexto
• Avaliação de RAG