# Sintaxe de requisitos EARS explicada, com exemplos Canonical: https://specscore.md/pt-br/articles/ears-requirements/ Atualizado em 2 de novembro de 2026 [EARS](https://alistairmavin.com/ears/) (Easy Approach to Requirements Syntax) é uma notação de requisitos: um conjunto pequeno de padrões de frase em inglês, também chamado de sintaxe EARS, que mantém uma condição, um gatilho e uma resposta do sistema numa ordem fixa. Um requisito é uma obrigação testável que um sistema deve cumprir. O [desenvolvimento guiado por especificação](https://specscore.md/pt-br/spec-driven-development/) (SDD, spec-driven development) é a prática de escrever essa obrigação numa especificação antes do código e tratar a especificação como fonte da verdade. Um documento de requisitos de produto (PRD, product requirements document) é a prosa que enuncia o problema e o escopo antes de partir o trabalho em tarefas. No [SpecScore](https://specscore.md/), um requisito (REQ) é uma regra nomeada dentro de uma funcionalidade, e um critério de aceitação (AC, acceptance criterion) é uma condição abstrata opcional que aponta para uma ou mais dessas regras. A [integração contínua](https://specscore.md/pt-br/validators/) (CI, continuous integration) é uma verificação automática em cada mudança proposta. A verificação é um comando da [interface de linha de comando](https://specscore.md/pt-br/cli/) (CLI, command-line interface): `specscore spec lint`. O [Kiro](https://kiro.dev/), um ambiente de desenvolvimento integrado (IDE, integrated development environment) com agentes da Amazon Web Services (AWS), escreve um desses padrões. A notação foi publicada pela primeira vez por Alistair Mavin e colegas da Rolls-Royce numa conferência de engenharia de requisitos do Institute of Electrical and Electronics Engineers (IEEE) em 2009. ## De onde veio o EARS Alistair Mavin, Philip Wilkinson, Adrian Harwood e Mark Novak, então na Rolls-Royce PLC, publicaram “Easy Approach to Requirements Syntax (EARS)” na 17th IEEE International Requirements Engineering Conference em 2009. O identificador do documento é [10.1109/RE.2009.9](https://doi.org/10.1109/RE.2009.9). Eles construíram as regras ao extrair requisitos de controle de motor da Certification Specification for Engines (CS-E), seção CS-E 50, um regulamento de aeronavegabilidade. Esse texto misturava requisitos, orientação de projeto e notas. O artigo nomeia oito problemas da linguagem natural sem restrição: ambiguidade, vagueza, complexidade, omissão, duplicação, prolixidade, implementação inadequada e intestabilidade. Um conjunto pequeno de regras devia permitir que cada requisito usasse um de cinco modelos. Os autores dizem que a notação serve a requisitos de alto nível das partes interessadas e não afirmam que cubra todo nível de decomposição de um sistema. O [guia do próprio Mavin](https://alistairmavin.com/ears/) descreve o EARS como um modo de restringir com suavidade requisitos textuais. As cláusulas ficam numa ordem, que ele chama de lógica temporal: qualquer pré-condição, depois o gatilho, depois o nome do sistema e a resposta. O conjunto de regras é zero ou muitas pré-condições, zero ou um gatilho, um nome de sistema e uma ou muitas respostas. O artigo de 2009 especializa essa forma em cinco modelos. O mesmo guia também nomeia requisitos complexos, que combinam as palavras-chave. No estudo de caso do artigo, o extrato bruto tinha 36 requisitos e o conjunto reescrito tinha 47. O comprimento médio caiu de 36,9 para 25,6 palavras. Os autores relatam que, nesse estudo, complexidade, omissão, duplicação, implementação inadequada e intestabilidade estavam ausentes do conjunto reescrito, enquanto ambiguidade, vagueza e prolixidade diminuíram sem desaparecer. Eles também listam os limites: uma amostra pequena, só requisitos de segurança de alto nível e julgamento ao classificar a vagueza. Esses números são do artigo, para esse único documento. ## Os padrões de frase EARS As palavras-chave são as do artigo de 2009 e do guia de Mavin. O artigo também permite *During* no lugar de *While* para um estado, com o mesmo sentido, quando isso se lê com mais clareza. As frases de exemplo ilustram os modelos. Não são citações do artigo. O Kiro escreve o padrão orientado a evento em maiúsculas; a notação original usa inicial maiúscula. Os exemplos ficam em inglês porque a sintaxe EARS é inglesa. ### Ubíquo `The shall ` Sempre ativo. Não há palavra-chave EARS, porque não há pré-condição nem gatilho. A ilustração do próprio artigo de 2009 é um sistema de controle que deve impedir o excesso de rotação do motor. **Exemplo:** The checkout system shall keep the order total equal to the sum of its line items. ### Orientado a evento `When , the shall ` A resposta é exigida quando um gatilho é detectado na fronteira do sistema, e só então. A palavra-chave é *When*. **Exemplo:** When a shopper submits the checkout form with invalid data, the checkout system shall show a validation error next to the invalid field. ### Orientado a estado `While , the shall ` A resposta é exigida enquanto o sistema permanece no estado nomeado. A palavra-chave é *While*. **Exemplo:** While the cart is empty, the checkout system shall keep the pay button disabled. ### Comportamento indesejado `If , then the shall ` A resposta trata uma falha, um distúrbio, um desvio ou outro comportamento indesejado. As palavras-chave são *If* e *then*. O artigo deu a esse padrão palavras-chave próprias para que esses requisitos continuem visíveis. Os autores observam que desejado e indesejado às vezes é uma questão de ponto de vista. **Exemplo:** If the submitted email is not a valid address, then the checkout system shall reject the form. ### Recurso opcional `Where , the shall ` A resposta vale só quando o produto inclui o recurso nomeado. A palavra-chave é *Where*. **Exemplo:** Where the shop includes gift wrapping, the checkout system shall offer gift wrapping on the order review step. ### Complexo `While , when , the shall ` Mais de uma palavra-chave. O guia de Mavin mantém a mesma ordem de cláusulas: *While* para a pré-condição, depois *When* para o gatilho, depois a resposta do sistema. O artigo de 2009 também combina *While* com *If / then* para comportamento indesejado num estado. Uma ilustração dessa combinação: While the shopper is signed out, if the shopper submits the checkout form, then the checkout system shall refuse the order. **Exemplo:** While the shopper is signed in, when the shopper submits a valid checkout form, the checkout system shall place the order. ## Erros comuns ### Várias obrigações numa frase O artigo trata uma frase composta como o problema de complexidade e a divide. A [especificação de requisito do SpecScore](https://specscore.md/requirement-specification) diz o mesmo nos próprios termos: cada `REQ` deve expressar exatamente uma obrigação testável. ### Esconder o comportamento indesejado em When *When* é para um gatilho esperado. *If / then* é para o comportamento que se preferiria não encontrar. Uma só palavra-chave para os dois faz o caso indesejado parecer o caso normal, que é o problema de omissão que o artigo aponta. ### Escrever a implementação “The checkout system shall store the flag in Redis” nomeia um projeto. O artigo chama isso de implementação inadequada. A resposta deve dizer o que o sistema deve alcançar, não qual componente faz isso. ### Sem nome de sistema “When the form is submitted, shall show an error” não tem sujeito. O conjunto de regras de Mavin exige um nome de sistema. ### Gatilho depois da resposta “The checkout system shall show an error when the form is submitted” põe o gatilho no fim. A ordem publicada é pré-condição, depois gatilho, depois resposta. ### Tomar a linha do Kiro por todo o EARS A página de especificações de funcionalidade do Kiro publica um único padrão, `WHEN … THE SYSTEM SHALL …`. O ubíquo, *While*, *If / then*, *Where* e as combinações complexas fazem parte da notação no artigo e no guia de Mavin. Não estão nessa página do Kiro. ## Como o Kiro usa EARS A [página de especificações de funcionalidade do Kiro](https://kiro.dev/docs/specs/feature-specs/), marcada como atualizada em 4 de agosto de 2026 e lida em 2 de novembro de 2026, diz que o arquivo `requirements.md` usa EARS. O padrão impresso é `WHEN [condition/event]` seguido de `THE SYSTEM SHALL [expected behavior]`. O exemplo da página: WHEN a user submits a form with invalid data, THE SYSTEM SHALL display validation errors next to the relevant fields. A [página de requisitos primeiro](https://kiro.dev/docs/specs/feature-specs/requirements-first/) diz que um `requirements.md` gerado inclui histórias de usuário com critérios de aceitação e comportamentos do sistema nessa mesma forma WHEN … THE SYSTEM SHALL …. O exemplo de cadastro são três frases: dados válidos de cadastro criam uma conta, um e-mail que já existe mostra “Email already registered” e um formato de e-mail inválido mostra um erro de validação. Antes do projeto, Analyze Requirements procura inconsistências lógicas, ambiguidades, restrições em conflito e lacunas. A página diz que se escolhe isso nas opções do chat ou no menu Continue do editor depois de gerar os requisitos. `design.md` e `tasks.md` ficam ao lado dos requisitos. Quick Spec executa requisitos, projeto e tarefas sem uma parada de aprovação entre eles. Essa análise é um passo dentro do Kiro. A página não a descreve como um linter de formato que se adiciona à própria CI. Como as outras ferramentas verificam uma especificação está no [guia de ferramentas](https://specscore.md/pt-br/spec-driven-development/tools/). A comparação dos dois produtos é [SpecScore vs Kiro](https://specscore.md/pt-br/vs/kiro/). ## O mesmo requisito no SpecScore O SpecScore não verifica se uma frase corresponde a um modelo EARS. `specscore spec lint`, do repositório [specscore-cli](https://github.com/specscore/specscore-cli), verifica a estrutura. O texto de ajuda nomeia arquivos README, seções Open Questions, níveis de título, referências a funcionalidades, links internos e entradas de índice. Uma frase EARS pode ser a prosa sob um título `REQ`. O linter não avalia o inglês. A [especificação de requisito](https://specscore.md/requirement-specification) coloca cada requisito sob um título de tópico dentro de `## Behavior`, um nível abaixo, em geral `#### REQ: slug`. O slug usa letras minúsculas, números e hifens. O identificador é `{feature-path}#req:{slug}`. A especificação diz que um requisito deve usar palavras-chave do RFC 2119 (Request for Comments 2119): MUST, MUST NOT, SHOULD, SHOULD NOT e MAY. No mapeamento abaixo, o *shall* do EARS é escrito como MUST. Um [critério de aceitação](https://specscore.md/acceptance-criteria-specification) é opcional. Quando se usa um, é `### AC: slug` dentro de `## Acceptance Criteria`, e a linha seguinte é `**Requirements:**` com esses identificadores. A especificação de critérios de aceitação diz que o AC enuncia uma condição abstrata e não deve conter passos Given/When/Then, entradas concretas nem detalhe de implementação. Um fluxo concreto é um [cenário](https://specscore.md/scenario-specification) no diretório `_tests/` da funcionalidade. A [especificação de funcionalidade](https://specscore.md/feature-specification) também exige um status, um resumo, um problema, o comportamento, critérios de aceitação, perguntas abertas e um rodapé de aderência. Os arquivos abaixo são uma funcionalidade de checkout. `show-field-error` é o exemplo orientado a evento. `reject-invalid-email` é o exemplo de comportamento indesejado. Em 2 de novembro de 2026, `specscore spec lint` reportou 0 violações para essa árvore com specscore 0.55.1, a versão mais recente publicada em 30 de outubro de 2026, e com specscore 0.39.1, a versão fixada em [dogfood.yml](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml). O [repositório do formato](https://github.com/specscore/specscore) é onde esse fluxo vive. ### spec/features/checkout/README.md ```markdown --- format: https://specscore.md/feature-specification status: Draft --- # Feature: Checkout validation > [SpecScore.**Studio**](https://specscore.studio): | [Explore](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=explore) | [Edit](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=edit) | [Ask question](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=ask) | [Request change](https://specscore.studio/app/github.com/example/checkout/spec/features/checkout?op=request-change) | **Status:** Draft **Source Ideas:** — ## Summary The checkout form shows a validation error next to a field when the shopper submits invalid data, and it rejects an email that is not a valid address. ## Problem A vague sentence such as "the form should handle bad input" does not say which event causes which response. Checkout needs those obligations written so a reviewer and a linter can point at them. ## Behavior ### Field validation The checkout system checks the form when the shopper submits it. #### REQ: show-field-error When a shopper submits the checkout form with invalid data, the checkout system MUST show a validation error next to the invalid field. #### REQ: reject-invalid-email If the submitted email is not a valid address, then the checkout system MUST reject the form. ## Acceptance Criteria ### AC: invalid-submission **Requirements:** checkout#req:show-field-error, checkout#req:reject-invalid-email Submitting the checkout form with invalid data shows a validation error next to the invalid field, and an email that is not a valid address is rejected. ## Open Questions None at this time. --- *This document follows the https://specscore.md/feature-specification* ``` ### spec/features/README.md — a célula de descrição é a frase de resumo da funcionalidade. A regra feature-index-row-sync do linter rejeitou uma descrição mais curta. ```markdown --- format: https://specscore.md/features-index-specification --- # Features | Feature | Status | Description | |---|---|---| | [Checkout validation](checkout/README.md) | Draft | The checkout form shows a validation error next to a field when the shopper submits invalid data, and it rejects an email that is not a valid address. | ## Open Questions None at this time. --- *This document follows the https://specscore.md/features-index-specification* ``` ### spec/README.md — remover a seção Open Questions produziu oq-section: Open Questions section not found. ```markdown # Checkout specification ## Open Questions None at this time. ``` ### specscore.yaml — project.host, project.org e project.repo são os valores confrontados com a linha studio-toolbar. Sem eles o linter reportou studio-toolbar: studio toolbar requires project host/org/repo. ```yaml # SpecScore Repo Config Schema: https://specscore.md/repo-config project: title: Checkout sample host: github.com org: example repo: checkout ``` Mais dois erros apareceram ao fazer este exemplo passar, e os dois estão corrigidos nos arquivos acima. Uma funcionalidade sem `**Source Ideas:**` falhou em `feature-source-ideas-required`; `—` é o valor vazio. O índice de funcionalidades também precisava do campo de frontmatter `format: https://specscore.md/features-index-specification`. A passagem do linter significa que os arquivos cumprem essas regras de estrutura. Não significa que as frases sejam um bom EARS, nem que o produto de checkout exista. O Given/When/Then desse comportamento seria um arquivo de cenário em `spec/features/checkout/_tests/`, não outro parágrafo dentro do AC. ## Perguntas ### O que significa EARS? Easy Approach to Requirements Syntax. É um conjunto de padrões de frase para requisitos, publicado por Alistair Mavin, Philip Wilkinson, Adrian Harwood e Mark Novak, da Rolls-Royce, na 17th IEEE International Requirements Engineering Conference em 2009, e descrito no site de Mavin. ### A notação do Kiro é todo o EARS? A página de especificações de funcionalidade do Kiro fixa um padrão: WHEN … THE SYSTEM SHALL …. O artigo de 2009 e o guia de Mavin também definem requisitos ubíquos, While orientado a estado, If/then para comportamento indesejado, Where para recurso opcional e combinações complexas dessas palavras-chave. ### O SpecScore valida a sintaxe EARS? Não. `specscore spec lint` valida a estrutura de arquivos do SpecScore. Uma frase EARS pode ser a prosa de um `REQ`. O linter não avalia o inglês. ### Onde ficam os exemplos Given/When/Then? Num cenário no diretório `_tests/` da funcionalidade. Um critério de aceitação continua uma condição abstrata e, na especificação de critérios de aceitação, não deve conter passos Given/When/Then. ## Fontes Lido em 2 de novembro de 2026, exceto onde uma página imprime a própria data de atualização. A página de especificações de funcionalidade do Kiro diz que foi atualizada em 4 de agosto de 2026. - [Mavin, Wilkinson, Harwood e Novak — Easy Approach to Requirements Syntax (EARS), 17th IEEE International Requirements Engineering Conference, 2009, DOI 10.1109/RE.2009.9](https://doi.org/10.1109/RE.2009.9) - [Alistair Mavin — guia EARS](https://alistairmavin.com/ears/) - [Documentação do Kiro — especificações de funcionalidade e EARS (página atualizada em 4 de agosto de 2026)](https://kiro.dev/docs/specs/feature-specs/) - [Documentação do Kiro — fluxo de requisitos primeiro](https://kiro.dev/docs/specs/feature-specs/requirements-first/) - [specscore/specscore — especificação de requisito](https://github.com/specscore/specscore/blob/main/spec/features/requirement/README.md) - [specscore/specscore — especificação de critérios de aceitação](https://github.com/specscore/specscore/blob/main/spec/features/acceptance-criteria/README.md) - [specscore/specscore — especificação de cenário](https://github.com/specscore/specscore/blob/main/spec/features/scenario/README.md) - [specscore/specscore — especificação de funcionalidade](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md) - [specscore/specscore — fluxo de CI dogfood](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) - [specscore/specscore-cli](https://github.com/specscore/specscore-cli) - [specscore/specscore](https://github.com/specscore/specscore) ## Relacionados - [Modelo de PRD em Markdown para programar com IA](https://specscore.md/pt-br/articles/feature-spec-template/) - [Lintar especificações na CI com um linter de especificações](https://specscore.md/pt-br/articles/lint-specs-in-ci/) - [Como escrever critérios de aceitação que um agente de IA possa verificar](https://specscore.md/pt-br/articles/acceptance-criteria/) - [SpecScore vs Kiro](https://specscore.md/pt-br/vs/kiro/) - [Ferramentas de desenvolvimento guiado por especificação](https://specscore.md/pt-br/spec-driven-development/tools/) - [Desenvolvimento guiado por especificação](https://specscore.md/pt-br/spec-driven-development/) - [Especificação de requisito](https://specscore.md/requirement-specification) - [Especificação de critérios de aceitação](https://specscore.md/acceptance-criteria-specification) - [Especificação de funcionalidade](https://specscore.md/feature-specification) - [Validadores e CI](https://specscore.md/pt-br/validators/)