Modelo de PRD em Markdown para programar com IA

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. Uma especificação de funcionalidade é o arquivo do SpecScore para uma capacidade do produto: o que ela faz, por que existe e como se comporta. Markdown é o formato de texto puro desse arquivo. O desenvolvimento baseado em especificações (SDD, spec-driven development) é a prática de escrever a especificação antes do código e tratar a especificação como a fonte da verdade. No SpecScore, um requisito (REQ) é uma regra nomeada dentro de uma funcionalidade. Um critério de aceitação (AC, acceptance criterion) é uma condição abstrata opcional que aponta para uma ou mais dessas regras. Um cenário é um exemplo concreto escrito em passos Given, When e Then. Um plano é o documento que parte a funcionalidade em tarefas. Uma tarefa é uma unidade de trabalho que uma pessoa ou um agente pode terminar. A integração contínua (CI, continuous integration) é uma verificação automática em cada mudança proposta. A verificação é um comando da interface de linha de comando (CLI, command-line interface), specscore spec lint, da CLI em specscore/specscore-cli. Easy Approach to Requirements Syntax (EARS) é um padrão de frase que um requisito pode usar. Claude Code é o agente de programação com IA para o qual o plugin CLI Skills deste site foi escrito. Este modelo de especificação de funcionalidade é esse arquivo de funcionalidade, mais o plano e a tarefa que apontam de volta para ele.

Atualizado em 5 de novembro de 2026

O que é este modelo de especificação de funcionalidade

Um PRD costuma ser um arquivo de prosa que uma pessoa lê. O SpecScore guarda o mesmo encargo em arquivos que um linter pode verificar. A especificação de funcionalidade chama uma funcionalidade de unidade atômica da especificação de produto: um diretório sob spec/features/ cujo README.md é a única fonte da verdade do que a funcionalidade faz. A especificação de plano chama de plano o documento que decompõe essa funcionalidade em tarefas. Um cenário, na especificação de cenário, é um arquivo concreto Given/When/Then no diretório _tests/ da funcionalidade. A especificação de critérios de aceitação mantém o critério abstrato: diz o que deve ser verdadeiro, e o cenário diz como prová-lo.

O arquivo de checkout abaixo é o modelo preenchido. Junto com o índice de funcionalidades, um README da especificação e specscore.yaml, specscore spec lint aceitou-o com 0 violações. Essa verificação foi executada em 2 de novembro de 2026 com specscore 0.55.1 e com 0.39.1, a tag que dogfood.yml instala. A linha da barra do SpecScore Studio no arquivo da funcionalidade é a linha que os README de funcionalidade em specscore/specscore carregam. A tabela de seções obrigatórias da especificação de funcionalidade não a inclui.

O README da funcionalidade

A tabela de seções obrigatórias da especificação de funcionalidade diz que todo README de funcionalidade tem um título # Feature: {Title}, uma linha **Status:** logo depois do título, um Summary, um Problem, uma seção Behavior, uma seção Acceptance Criteria, uma seção Open Questions e um rodapé de adesão. O valor do status é um de Draft, In Review, Approved, Implementing, Stable, Amending, Rejected ou Deprecated. Uma seção Contents só é obrigatória quando a funcionalidade tem diretórios filhos. **Source Ideas:** é opcional. O arquivo verificado define isso como —.

Open Questions nunca é omitido. Quando não há nenhuma, a seção diz None at this time. Acceptance Criteria também nunca é omitido. Quando nenhum critério está definido, essa seção diz Not defined yet. e Open Questions deve então incluir Acceptance criteria not yet defined for this feature. O rodapé é a última linha, e a URL dele é https://specscore.md/feature-specification.

A convenção de frontmatter de artefatos diz que todo artefato carrega uma chave format: no frontmatter YAML, e um artefato com status também carrega status:, espelho do token **Status:** do corpo. A mesma funcionalidade diz que as regras de lint que impõem isso saem após um período de carência. O arquivo verificado inclui as duas chaves. Esta página não afirma que o pin v0.39.1 rejeita um arquivo que as omite.

README de funcionalidade que specscore spec lint aceitou (2 de novembro de 2026)

---
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*

Índice de funcionalidades da mesma execução de lint

---
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*

README da especificação da mesma execução de lint

# Checkout specification

## Open Questions

None at this time.

specscore.yaml da mesma execução de lint

# SpecScore Repo Config Schema: https://specscore.md/repo-config

project:
  title: Checkout sample
  host: github.com
  org: example
  repo: checkout

O identificador da funcionalidade é o caminho do diretório relativo a spec/features/. O link do índice checkout/README.md significa que o arquivo vive em spec/features/checkout/README.md, então o id da funcionalidade usado por requisitos e critérios é checkout. O índice lista cada funcionalidade de primeiro nível. Um diretório filho que não está listado é uma violação de index-entries, que lintar especificações na CI descreve. O README da especificação nessa árvore tem uma seção, Open Questions, e diz None at this time. O arquivo de configuração é o que a CLI procura para cima. Sem specscore.yaml o comando sai com 3 e nomeia specscore init.

Identificadores REQ, critérios de aceitação e cenários

A especificação de requisito coloca cada regra sob um cabeçalho de tema dentro de ## Behavior. O cabeçalho é #### REQ: {slug}, com um espaço depois dos dois pontos. O slug usa letras minúsculas, números e hifens. O id canônico é {feature-path}#req:{slug}. No arquivo de checkout isso é checkout#req:show-field-error e checkout#req:reject-invalid-email. Um requisito enuncia uma só obrigação. A especificação diz que os requisitos SHOULD usar as palavras-chave RFC 2119 MUST, MUST NOT, SHOULD, SHOULD NOT e MAY. Um cabeçalho REQ: não é válido fora de ## Behavior. Uma frase EARS pode ser essa prosa. O linter não avalia o inglês. Os padrões estão em sintaxe de requisitos EARS.

Critério de aceitação

A especificação de critérios de aceitação diz que cada critério é um cabeçalho ### AC: {slug} dentro de ## Acceptance Criteria, depois uma linha **Requirements:** que lista valores {feature-id}#req:{slug}, e então um enunciado abstrato do que deve ser verdadeiro. Os critérios são opcionais. A especificação diz para acrescentar um quando o agrupamento de dois ou mais requisitos relacionados acrescenta clareza. O arquivo de checkout agrupa as duas regras em checkout#ac:invalid-submission. O enunciado não contém Given, When nem Then. Como escrever critérios de aceitação é o guia de redação. A regra ac-heading-format (ac_heading.go na tag v0.55.1 da CLI) verifica que o cabeçalho é ### AC: <id> com um id em kebab-case. O artigo sobre lint registra que esta regra não exige a linha **Requirements:** e não avalia as palavras. A especificação de critérios de aceitação ainda exige essa linha.

Cenário

A especificação de cenário coloca um cenário em _tests/, que não é uma subfuncionalidade e fica fora do índice de funcionalidades. O arquivo começa com # Scenario: {Title}, uma linha **Validates:** que aponta para um requisito ou um critério, e uma seção ## Steps cujas palavras-chave são maiúsculas: GIVEN, WHEN, THEN e AND. Todo diretório _tests/ deve conter um README com um índice de cenários. A amostra abaixo é essa forma de arquivo. Ela não fez parte da execução de lint de 2 de novembro. specscore spec lint não verifica as palavras-chave dos passos do cenário. specscore rehearse executa os arquivos de cenário. Rehearse é esse executor. O fluxo dogfood executa o linter e não chama o rehearse.

Forma de arquivo de cenário, segundo a especificação de cenário

# Scenario: Reject an invalid email

**Validates:** [checkout#ac:invalid-email-rejected](../README.md#ac-invalid-email-rejected)

## Steps

GIVEN the shopper is on the checkout form
WHEN the shopper submits the email "not-an-email"
THEN the page shows "Enter a valid email address" beside the email field
AND the order is not placed

Leia as três camadas em ordem. O requisito diz a regra. O critério de aceitação diz o que deve ser verdadeiro para as regras que nomeia. O cenário dá um fluxo concreto. Um agente que só vê a prosa do PRD precisa inventar esse recorte. O modelo já o tem.

Planos e tarefas

Um README de plano vive em spec/plans/{plan-slug}/README.md. A especificação de plano exige o título # Plan: {Title} e os campos de cabeçalho Status, exatamente uma linha de origem, Date, Owner e Supersedes. Um plano com origem numa funcionalidade usa **Source Feature:** mais o slug da funcionalidade, aqui checkout. As outras linhas de origem válidas são **Source:** idea:{slug} e **Source:** none. As seções obrigatórias são Summary, Approach, Tasks e Open Questions. Dentro do plano, cada tarefa é um cabeçalho ### Task N: com uma linha **Verifies:** da forma feature-slug#ac:ac-slug. A regra P-001 em plan_rules.go informa um cabeçalho de critério de aceitação que nenhuma tarefa cobre e que não está listado sob ## Deferred AC Coverage. A regra P-002 informa um valor **Verifies:** que não resolve para um desses cabeçalhos. Planos com origem numa ideia e planos com **Source:** none estão isentos de P-001.

O plano abaixo segue essa forma publicada para a funcionalidade checkout, incluindo o frontmatter format: e status:. Ele não estava na execução de lint de 2 de novembro. Uma funcionalidade que um plano toca deve incluir uma tabela ## Plans com colunas Plan, Status, Author e Approved. O arquivo de funcionalidade verificado não tem seção Plans porque essa árvore não tem plano.

A especificação de tarefa também define uma tarefa como seu próprio diretório e README.md sob o plano. O título é # Task: {Title}. Os campos obrigatórios são **Status:**, **Depends on:** (o literal none quando não há dependência) e **Model:** (small, medium, large ou inherit). Um diretório que contém diretórios de tarefas filhas é um plano, não uma tarefa. O arquivo de tarefa abaixo usa esses campos para a primeira tarefa de checkout. Ele não estava na execução de lint de 2 de novembro. A URL do rodapé de um documento de tarefa é https://specscore.md/task-specification.

Forma de plano da especificação de plano, preenchida para checkout

---
format: https://specscore.md/plan-specification
status: Draft
---

# Plan: Show checkout validation errors

**Status:** Draft
**Source Feature:** checkout
**Date:** 2026-11-05
**Owner:** @example
**Supersedes:** —

## Summary

This plan decomposes the checkout feature into the work that shows a field error and rejects an email that is not a valid address.

## Approach

Both tasks verify the same acceptance criterion, which bundles the two requirements. Nothing is deferred, so this plan has no Deferred AC Coverage section.

## Tasks

### Task 1: Show a validation error beside the invalid field

**Verifies:** checkout#ac:invalid-submission

When the shopper submits the checkout form with invalid data, show a validation error next to the invalid field.

### Task 2: Reject an email that is not a valid address

**Verifies:** checkout#ac:invalid-submission

If the submitted email is not a valid address, reject the form.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/plan-specification*

Forma de documento de tarefa da especificação de tarefa

---
format: https://specscore.md/task-specification
status: queued
---

# Task: Show a validation error beside the invalid field

**Status:** queued
**Depends on:** none
**Model:** medium

## Acceptance Criteria

- Submitting the checkout form with invalid data shows a validation error next to the invalid field.

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/task-specification*

O arquivo da funcionalidade responde o que o formulário de checkout deve fazer. O plano responde como esse trabalho é partido, e cada tarefa em linha nomeia o critério que verifica. O documento da tarefa é a folha que uma pessoa ou um agente pega. Mantenha estável o id do critério. checkout#ac:invalid-submission é a string que tanto a funcionalidade quanto o plano usam.

Lintar o modelo na CI

specscore spec lint valida a árvore de especificações contra violações de convenção estrutural. Uma execução limpa imprime 0 violations found e sai com 0. Uma execução que encontra violações imprime uma linha por achado e sai com 1. Esse código de saída faz um job de CI falhar. Argumentos inválidos saem com 2. Um specscore.yaml ausente sai com 3. dogfood.yml instala a CLI com SPECSCORE_VERSION definido como v0.39.1 e depois executa specscore spec lint em pull requests e em pushes para main. O trecho do fluxo, o relatório de falha e o catálogo de regras estão em lintar especificações na CI.

A licença do formato é CC BY 4.0 em specscore/specscore. A licença da CLI é Apache-2.0 em specscore/specscore-cli.

Outras ferramentas de desenvolvimento baseado em especificações publicam verificações diferentes. As frases abaixo usam só o que as próprias páginas desses projetos dizem. O guia de ferramentas registra as mesmas páginas como lidas em 30 de outubro de 2026, exceto a página inicial da documentação do Spec Kit, que imprime 28 de setembro de 2026.

OpenSpec documenta openspec validate na sua referência de CLI. Esse comando verifica a estrutura de mudanças e especificações do OpenSpec e sai com código diferente de zero quando a validação falha. Ele não verifica um cabeçalho ### AC: do SpecScore nem um índice do SpecScore.

O README do Task Master descreve decompor um PRD em tarefas com task-master parse-prd. Não descreve um linter para esse PRD. Um PRD ainda pode ser o texto que você reescreve no arquivo de funcionalidade desta página. specscore spec lint é o que então verifica o arquivo de funcionalidade.

GitHub Spec Kit descreve um fluxo de agente cujas fases escrevem artefatos Markdown. Essa página inicial da documentação não descreve um comando que linta um README de funcionalidade SpecScore na CI. A comparação dessas ferramentas é o guia de ferramentas.

Um modelo de especificação que o Claude Code pode ler

Os arquivos são Markdown, então um agente que pode ler um repositório pode ler o modelo. Claude Code é o agente a que a página CLI Skills se dirige. Essa página documenta ai-plugin-specscore, um plugin fino de Claude Code que envolve a CLI. O repositório do plugin é specscore/ai-plugin-specscore. A página diz que o plugin expõe specscore spec lint, specscore feature, specscore task e specscore feature change-status como comandos do plugin. As linhas de instalação dessa página são /plugin marketplace add specscore/ai-marketplace e /plugin install cli-skills@specscore.

A mesma página documenta specscore agent setup <agent-name> para claude, copilot, cursor, codex, antigravity.google, pi.dev ou opencode, executado dentro de um projeto gerido pelo SpecScore. SpecStudio Skills é o fluxo guiado (/ideate, /specify, /plan, /implement) e também é um plugin de Claude Code. O modelo desta página é o arquivo que esses comandos lintam. O plugin não substitui o README da funcionalidade.

Perguntas frequentes

O que é um modelo de PRD em Markdown?

É um documento de requisitos de produto escrito como arquivos Markdown com uma forma fixa. No SpecScore essa forma é um README de funcionalidade: título, status, resumo, problema, comportamento com regras #### REQ:, critérios de aceitação e perguntas abertas. O arquivo de checkout desta página é um que specscore spec lint aceitou.

Onde ficam os identificadores REQ num modelo de especificação de funcionalidade?

Sob um cabeçalho de tema dentro de ## Behavior, como #### REQ: {slug}. O id é {feature-path}#req:{slug}. Os critérios de aceitação listam esses ids em **Requirements:**. Uma tarefa do plano lista o id do critério em **Verifies:**.

Qual é a diferença entre um critério de aceitação e um cenário?

Um critério de aceitação é uma condição abstrata. Um cenário é um fluxo concreto Given/When/Then em _tests/. A especificação de critérios de aceitação diz que o critério não deve prescrever os passos. O arquivo de cenário faz isso.

O linter avalia a prosa do PRD?

Não. specscore spec lint verifica a estrutura: cabeçalhos, seções obrigatórias, linhas do índice e referências como P-001 e P-002. Não decide se o produto é uma boa ideia. Lintar especificações na CI é o relato mais longo desse comando.

O Claude Code pode usar este modelo de especificação?

Sim. O modelo é Markdown no repositório. O plugin CLI Skills expõe specscore spec lint e os comandos de funcionalidade e de tarefa dentro do Claude Code. specscore agent setup claude escreve um arquivo de instruções para esse agente. O plugin não inventa outro modelo.

Um plano substitui a especificação da funcionalidade?

Não. O README da funcionalidade é a fonte dos requisitos e dos critérios de aceitação. O plano decompõe essa funcionalidade em tarefas, e cada tarefa aponta de volta com **Verifies:**. A especificação de plano e a especificação de tarefa são os dois documentos desse recorte.

Fontes

A funcionalidade checkout, o índice de funcionalidades, o README da especificação e specscore.yaml foram aceitos por specscore spec lint em 2 de novembro de 2026 com specscore 0.55.1 e com 0.39.1. As amostras de plano e de tarefa seguem as especificações publicadas e não fizeram parte dessa execução. As páginas de concorrentes são as ligadas abaixo; o guia de ferramentas as registra como lidas em 30 de outubro de 2026, exceto a página inicial da documentação do Spec Kit, que imprime 28 de setembro de 2026.