Como transformar o que os livros de requisitos ensinam em um template de spec para IA

Fala aí, beleza? Existe um abismo entre o livro de requisitos que você comprou e o arquivo que você realmente cola no assistente

O livro fala em stakeholder, rastreabilidade, atributo de requisito, nível de abstração

E o que sai da sua mão pro agente é um parágrafo tipo "faz aí um CRUD de chamados, capricha"

Aí o resultado vem torto e a culpa cai no modelo

Só que na maior parte das vezes o agente não errou por falta de inteligência, ele errou porque a spec permitia duas leituras e ele escolheu a que você não queria

A proposta aqui é fechar essa distância: traduzir o que os clássicos de requisitos ensinam num template de spec para IA com seções fixas, o que entra em cada uma e, principalmente, o que cortar 🙂

O que você precisa antes de escrever a spec

Antes de abrir o editor, três coisas em mãos:

• Um problema já delimitado: se você ainda está decidindo o que construir, não é spec que falta, é decisão
• Quem são os interessados: quem usa, quem aprova, quem sofre se quebrar
• As referências que sustentam o template

E as referências são estas quatro, se liga:

ISO/IEC/IEEE 29148. A IEEE 830-1998, aquela que todo mundo cita de cabeça, está marcada como Superseded Standard: a ISO/IEC/IEEE 29148:2011 a substituiu e a edição vigente é a ISO/IEC/IEEE 29148:2018, "Systems and software engineering, Life cycle processes, Requirements engineering"

Ela define o construto de um bom requisito, traz atributos e características de requisitos, e trata a aplicação dos processos de requisitos como algo iterativo e recursivo ao longo do ciclo de vida

Outra coisa que ela faz e que interessa demais pra gente: separa a especificação em documentos por nível de abstração em vez de um documento único gigante (StRS, SyRS, SRS, BRS e OpsCon)

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O template Volere, criado por James e Suzanne Robertson, do Atlantic Systems Guild, e distribuído em volere.org

O Volere usa a requirements shell, também chamada de snow card: uma ficha por requisito atômico, com campos fixos

Guarda esse conceito, porque é ele que vira o formato de linha da nossa lista de requisitos

O SRS de Karl Wiegers, coautor de "Software Requirements" e "Software Requirements Essentials", que mantém um template de Software Requirements Specification distribuído publicamente

A sintaxe EARS (Easy Approach to Requirements Syntax), criada por Alistair Mavin e colegas na Rolls-Royce plc

Ela nasceu de um trabalho bem específico: analisar regulamentos de aeronavegabilidade para um sistema de controle de motor a jato

Foi publicada na IEEE International Requirements Engineering Conference (RE’09), em 2009

O EARS é uma sintaxe controlada de requisito em linguagem natural: ordem de cláusulas consistente e um vocabulário limitado de palavras estruturais

Ele organiza tudo em cinco padrões: ubíquo (sem palavra-chave), dirigido a evento (When), dirigido a estado (While), comportamento indesejado (If/Then) e recurso opcional (Where)

Se você conhece um linter, é a mesma pegada: não é uma linguagem nova, é a sua língua com regra de forma

E se você for encarar essa pilha de leitura, vale jogar o material num caderno de IA e transformar pesquisa em conteúdo antes de sentar pra escrever o template

Passo a passo: montando o template seção por seção

Cada passo abaixo é UMA seção do arquivo, com o conceito de livro que ela herda, um bloco pronto pra copiar e o erro comum de quem escreve essa seção pela primeira vez

1. Contexto e objetivo:

O problema antes da solução

Essa seção herda a lógica do StRS e do OpsCon da 29148: descrever a necessidade e a operação, não a implementação

O agente precisa saber onde ele está pisando pra escolher bem quando a spec ficar omissa (e ela vai ficar em algum ponto)

## Contexto
Produto: painel interno de suporte
Problema: o atendente abre 3 abas pra responder um chamado
Quem é afetado: atendimento (uso diário), liderança (relatório semanal)
Objetivo: fechar o chamado sem sair de uma tela
Sinal de sucesso: o chamado é concluído em uma única tela

O erro comum deste passo: escrever a solução disfarçada de contexto ("objetivo: criar o componente TicketPanel")

Isso já entrega a arquitetura mastigada e mata a única parte em que o agente é bom sozinho

2. Escopo e não-escopo:

O que cortar é informação, não é enfeite

A seção de não-escopo é a que mais economiza retrabalho, porque agente de código é otimista por natureza: se cabe, ele faz

## Escopo
- Busca do chamado por número e por e-mail do cliente
- Resposta usando template salvo

## Fora de escopo (não faça)
- Login social
- Migração dos chamados antigos
- Qualquer alteração de schema no banco
- Renomear arquivo ou pasta existente

O erro comum deste passo: deixar o não-escopo vazio "porque ainda não sei"

Não-escopo vazio é convite: você pede um filtro de busca e volta com refatoração de três módulos que ninguém pediu haha

3. Requisitos em frase controlada:

Aqui entra o EARS, com os cinco padrões

A regra é uma frase por requisito, sempre na mesma ordem de cláusulas, sempre com o mesmo punhado de palavras estruturais

Os exemplos canônicos publicados pelo próprio autor deixam o formato claro:

• Evento: When "mute" is selected, the laptop shall suppress all audio output
• Estado: While there is no card in the ATM, the ATM shall display "insert card to begin"
• Ubíquo: The mobile phone shall have a mass of less than XX grams

Repare no ubíquo: ele não tem gatilho, vale sempre

Já o comportamento indesejado usa If/Then, e o recurso opcional usa Where

No template, cada linha vira uma ficha atômica, no espírito da requirements shell do Volere: identificador, frase e origem

## Requisitos

UB-01 | ubíquo
The system shall keep the ticket history read-only

EV-01 | evento (When)
When the agent selects a saved template, the system shall fill the reply field with it

ST-01 | estado (While)
While the ticket is closed, the system shall disable the reply field

UW-01 | indesejado (If/Then)
If the ticket API is unavailable, then the system shall show the last cached ticket

OP-01 | opcional (Where)
Where the workspace has SLA enabled, the system shall show the remaining time

Escreveu em português? Beleza também, o que não pode é misturar meia dúzia de formas de dizer a mesma coisa no mesmo arquivo

O erro comum deste passo: escrever requisito com dois verbos ("o sistema deve validar e notificar o gestor")

Requisito com "e" no meio é requisito duplo: quando um dos lados falha, você não consegue nem dizer se o item passou

4. Critérios de aceite:

A forma condicional de sempre

O requisito diz o que o sistema faz

O critério de aceite diz como você prova que ele fez

O Kiro usa exatamente essa ideia no requirements.md, com histórias de usuário e critérios de aceite em notação EARS, no formato WHEN <condição/evento> THE SYSTEM SHALL <comportamento esperado>

O exemplo da documentação deles:

WHEN a user submits a form with invalid data THE SYSTEM SHALL display
validation errors next to the relevant fields

É o mesmo esqueleto do EARS, só que apontado pro teste em vez de apontado pro comportamento

E isso muda muito a conversa com o agente, porque ele passa a ter um alvo verificável em vez de uma vontade

O erro comum deste passo: critério que não dá pra observar ("a busca deve ser rápida", "a tela deve ser intuitiva")

Se você não consegue dizer o que aparece na tela, o agente inventa um número e você descobre depois

5. Restrições técnicas e decisões:

O pedaço que vira design

Essa seção é o design.md da vida: arquitetura, abordagem técnica, o que já foi decidido e não está em discussão

No Kiro, o design.md guarda a arquitetura técnica e diagramas de sequência

No OpenSpec, o design.md responde o "como", a abordagem técnica, separado do proposal.md, que responde o porquê e o quê

## Restrições
- Stack fixa: TypeScript, sem dependência nova sem aprovação
- Sem migration nesta entrega
- O componente novo mora em src/features/tickets/
- Erro de rede sempre exibe estado visível, nunca falha em silêncio

## Decisões já tomadas
- Cache em memória, não em disco (motivo: dado sensível)

O erro comum deste passo: listar preferência de estilo como se fosse restrição de arquitetura

Separar as duas coisas ajuda quem lê depois (humano ou máquina) a saber o que é negociável

6. Tarefas rastreáveis:

Ordenadas por dependência, com caminho de arquivo

Essa é a seção que o agente mais usa na prática, e é a que mais gente escreve mal

O tasks.md gerado pelo GitHub Spec Kit é um bom modelo do que faz diferença: quebra organizada por user story, ordenação por dependência (models antes de services, services antes de endpoints), marcação de paralelismo pra tarefa que pode rodar junto com outra e caminho exato do arquivo

## Tarefas
- [ ] T1 criar o tipo Ticket em src/features/tickets/types.ts
- [ ] T2 criar o serviço em src/features/tickets/service.ts (depende de T1)
- [ ] T3 criar o componente de resposta em src/features/tickets/Reply.tsx (pode rodar em paralelo)
- [ ] T4 ligar o serviço na tela em src/app/tickets/page.tsx (depende de T2 e T3)

O erro comum deste passo: tarefa sem caminho de arquivo

"Criar o serviço" faz o agente escolher a pasta, e a pasta que ele escolhe raramente é a que o seu projeto usa

7. Onde o arquivo mora e como o agente acha:

Spec boa em lugar que ninguém lê não serve pra nada

Durante um bom tempo cada ferramenta lia o seu próprio arquivo de instrução: CLAUDE.md no Claude, GEMINI.md no Gemini, .github/copilot-instructions.md no GitHub Copilot

O AGENTS.md nasceu justamente pra resolver essa fragmentação: é um formato aberto pra dar contexto de projeto a agentes de código

Ele foi formalizado como especificação aberta em agosto de 2025, com liderança da OpenAI e participação de Google, Cursor e Factory

Em dezembro de 2025 foi doado à Agentic AI Foundation, da Linux Foundation

No mesmo dado de dezembro de 2025: mais de 60.000 projetos open source adotaram o formato e mais de 20 ferramentas de código com IA o suportam

O caminho prático é simples: o contexto permanente do projeto fica no arquivo que a SUA ferramenta lê, e a spec da entrega fica num arquivo próprio, versionado junto do código, apontado explicitamente quando você abre a tarefa

O erro comum deste passo: enfiar a spec inteira dentro do arquivo de contexto do projeto

Contexto é permanente, spec é da entrega: misturar os dois faz o agente carregar pra sempre uma regra que valia só pra uma feature

Spec Kit, Kiro e OpenSpec: como cada um já organiza esses arquivos

Antes de sair montando o seu do zero, vale saber que já existe ferramenta que cospe esses arquivos prontos

O GitHub Spec Kit é um toolkit open source do GitHub descrito como "Toolkit to help you get started with Spec-Driven Development"

O OpenSpec vai por outro caminho: organiza por MUDANÇA, não por documento único

E o Kiro é o que mais se aproxima do template que a gente montou aqui, com os três arquivos e o EARS nos critérios

Uma nota sobre o Spec Kit que costuma passar batido: ele suporta vários agentes, não só um

Entre os suportados estão Claude Code, GitHub Copilot, CodeBuddy CLI, Gemini CLI, Pi Coding Agent e Oh My Pi

Se você já usa alguma dessas, adotar a ferramenta pronta economiza a briga de manter template próprio

Se o seu fluxo é peculiar, mantém o seu arquivo e rouba o formato dos artefatos, que é o que realmente carrega o valor

Quando usar o template inteiro e quando usar só um pedaço

Spec completa pra tudo é receita pra você parar de escrever spec na terceira semana

A 29148 já resolve isso do jeito dela, separando por nível de abstração em vez de empilhar tudo num documento único

Dá pra aplicar a mesma lógica em escala pequena, assim:

Feature nova em projeto existente: template inteiro

Aqui tem contexto pra explicar, tem coisa que não pode ser tocada e tem ordem de execução

As sete seções valem o tempo, porque cada uma corta uma classe inteira de retrabalho

Correção pontual: só requisito + critério de aceite

Bug não precisa de contexto de negócio nem de plano de arquitetura

Precisa de uma frase EARS dizendo o comportamento correto e um WHEN ... THE SYSTEM SHALL ... dizendo como se prova

Duas linhas resolvem melhor que duas páginas

Projeto do zero: contexto e restrições valem mais que a lista de requisitos

No começo você não conhece os requisitos direito, e fingir que conhece só gera lista bonita que morre na primeira semana

O que segura o agente nessa fase é contexto, escopo, não-escopo e restrição técnica

A lista de requisitos você preenche conforme as decisões aparecem

E aí a coisa fica interessante: se você vai destrinchar documentação, transcrição de reunião ou material de pesquisa antes de escrever esse contexto, gerar um vídeo resumo dos documentos ajuda a entender o material antes de virar seção do template

Conclusão

A teoria de requisitos não envelheceu, ela só mudou de leitor

O que a 29148, o Volere, o SRS do Wiegers e o EARS resolvem é ambiguidade, e ambiguidade é justamente onde o agente de código escorrega

A diferença é que agora o destinatário da sua frase controlada não é o time de QA daqui a três meses, é uma máquina que vai executar em cinco minutos

Próximo passo bem concreto pra hoje: cria o arquivo no repositório com as sete seções fixas, escreve os três primeiros requisitos em EARS e roda UMA tarefa real em cima dele

O que voltar errado te mostra exatamente onde a spec ainda deixa duas leituras possíveis, e é ali que o template melhora de verdade

Depois vai afinando, porque template de spec bom não nasce pronto, ele apanha um pouquinho antes 😀

Até o próximo post!