Spec-Driven Development
Você produzirá uma spec pequena e implementará sua matriz de aceitação antes de escrever código de produto. O objetivo é tornar uma funcionalidade revisável e detectar o que falta entre serviço e interface. A tentativa inicial deve ser sua, antes de consultar a resolução.
Use a importação fictícia para controlar casos. O exemplo local organiza critérios; Playwright aparece como verificação E2E planejada ou executada no projeto disponível. Não marque esse cenário como aprovado apenas porque o plano cita a ferramenta.
JavaScriptAPIsProgramaçãoAo terminar esta aula
- Specs conectam necessidade e verificação.
- Dependências definem paralelismo seguro.
- Discrepâncias são comparadas, não escondidas.
Antes de continuar: Leitura: Spec-Driven Development
Escrever problema e comportamento
FundamentosRedija um PRD de uma página com operador, problema de retrabalho, objetivo e escopo. Defina importação parcial ou atômica e justifique o compromisso. A primeira preserva trabalho válido, mas exige relatório de rejeições; a segunda simplifica consistência, mas obriga corrigir todo o lote antes de avançar. Escreva histórias e critérios com entradas concretas. Inclua arquivo vazio, linha negativa e tentativa de importar em outro escopo. Essa etapa retoma contratos e autorização: decisão de produto e garantia de acesso não devem ficar escondidas em um prompt.
↗ Product requirements document↗ Spec Kit specification template
Definir contrato e exemplos
FundamentosDescreva a operação, campos, unidades e códigos de erro. Escreva uma resposta com linhas aceitas e rejeitadas, incluindo número e motivo. Confira se a interface consegue apresentar o resultado sem interpretar texto livre. Identifique o contexto confiável de tenant e a chave do lote. Compare exemplos com o schema e procure contradições, como um campo opcional que a interface sempre exige. Corrija essas discrepâncias antes de gerar mocks ou clientes. O contrato deve informar também falha total e repetição da intenção, não apenas um caminho feliz.
Decompor e implementar checkpoints
FundamentosCrie tarefas com resultado e verificação: validar contrato, implementar regras, persistir relatório, apresentar rejeições e testar jornada. Desenhe dependências e indique onde um mock permite trabalho paralelo. Em cada checkpoint, compare artefato com critério. Execute a matriz local e perceba que pendência de interface impede conclusão. Quando uma descoberta técnica muda o comportamento, atualize a spec e os exemplos. Não trate o plano como documento imutável nem use sua lista de tarefas para ocultar requisitos novos ou incompatíveis.
↗ Spec Kit tasks template↗ Effective harnesses for long-running agents
Avaliar jornada e discrepâncias
FundamentosPrepare um cenário E2E que envie arquivo controlado e confira motivo visível. Use isolamento de dados e seletores sem depender de detalhes frágeis do DOM. Compare o resultado com a história do operador: ele consegue saber o que corrigir? Revise também autorização com teste de integração. A matriz final liga cada critério à evidência real e mostra lacunas. Feche com uma análise de discrepâncias que distingue implementado, verificado e pendente. Outra pessoa deve conseguir revisar a entrega sem conhecer as conversas que produziram o plano.
Amarrar implementação à jornada
FundamentosImplemente uma fatia vertical pequena: entrada de arquivo, validação de uma linha e apresentação de rejeição. O serviço pode começar local e controlado; a interface precisa mostrar número e motivo, não apenas falha genérica. Depois amplie para lote e persistência conforme o contrato. A sequência permite testar o caminho inteiro cedo e detectar divergência entre mock e implementação. Use o teste unitário para valor negativo, o teste de contrato para resposta e o E2E para o operador visualizar a rejeição. Execute apenas verificações disponíveis e registre lacunas. A feature só é aceita quando os critérios pertinentes têm evidência. Um documento de spec bem escrito sem comportamento implementado ainda é preparação, e deve ser rotulado assim na entrega do estudante.
Caso adicional para diagnóstico e decisão
FundamentosAcrescente uma alteração de requisito: o operador agora precisa baixar apenas as linhas rejeitadas. Antes de implementar, identifique quais artefatos mudam: PRD, critério, contrato de relatório, tarefa de interface e E2E. Não acrescente uma função isolada sem atualizar a aceitação. Escreva um exemplo de arquivo baixado e confirme que conserva cabeçalho e motivos sem incluir dados de outra conta. Compare exportação imediata com geração assíncrona: a primeira simplifica o fluxo em lotes pequenos; a segunda pode atender volume maior, mas precisa de estado, recuperação e autorização no download. A rubrica avalia o comportamento escolhido, não o nome da arquitetura. Esse caso mostra por que um plano é um artefato vivo ligado à spec. A análise de discrepâncias deve apontar tanto funcionalidade faltante quanto comportamento extra que aumenta escopo sem necessidade.
Execução, inspeção e diagnóstico
FundamentosExecute a matriz e tente justificá-la como entrega concluída. O AC2 pendente impede essa conclusão. Acrescente campos de evidência e data de execução; depois preencha-os apenas com resultados observados. A estrutura torna visível quando uma intenção de teste foi confundida com teste executado.
const criterios = [
{id:"AC1",descricao:"Linha negativa rejeitada",verificacao:"teste-validacao",feito:true},
{id:"AC2",descricao:"Motivo visível ao operador",verificacao:"e2e-interface",feito:false},
{id:"AC3",descricao:"Escopo autorizado",verificacao:"teste-integracao",feito:true}
];
console.log({concluido:criterios.every(x=>x.feito),
pendencias:criterios.filter(x=>!x.feito).map(x=>x.id)});Se backend passa e jornada falha, investigue contrato, adaptação ou apresentação. Se o mock difere do serviço, revise a fronteira antes de ampliar testes. Se critérios são vagos, a discrepância pode estar na spec, não no código. O diagnóstico precisa indicar qual documento ou componente muda.
Exercício aplicado
Entregue PRD, specs, contrato, plano com dependências e matriz de verificação da importação.
- Tente definir comportamento e tradeoff de importação.
- Escreva exemplos e schemas coerentes.
- Decomponha tarefas com checkpoints.
- Avalie jornada e registre discrepâncias com evidência.
Abrir resolução comentada
A solução começa pelo PRD e inclui uma história de correção de erros. Define importação parcial, contrato de motivos e autorização. O plano permite frontend trabalhar com mock versionado, mas exige integração final e E2E para o fluxo do operador.
A conclusão depende de todos os critérios pertinentes verificados. Se o cenário de interface falha, revise a implementação ou o requisito explicitamente; não reclassifique o critério como opcional depois de ver o resultado. O relatório registra o que falta e o impacto no uso.
A resolução mantém necessidade, contrato e teste ligados. Um plano bom termina com comportamento demonstrado para o operador; não basta cumprir uma lista de alterações internas.
A solução contém PRD, contrato, tarefas com dependências e uma fatia funcional local de validação e apresentação de rejeições. Os asserts verificam regra, escopo, versão do contrato e número/motivo. A matriz liga os critérios à evidência realmente executada e mantém E2E de interface como pendência explícita. Essa resolução não chama uma apresentação textual de teste de navegador: a feature integrada só é concluída quando upload, interface e Playwright forem executados no projeto-alvo.
import assert from "node:assert/strict";
const prd={problema:"Operador não sabe corrigir linhas rejeitadas",usuario:"operador autorizado",
objetivo:"Apresentar número e motivo",escopo:"importação parcial",foraEscopo:["editor completo de planilha"]};
const contrato={versao:1,entrada:{id:"string",valor:"inteiro em centavos"},
saida:{aceitas:"lista",rejeitadas:"linha, codigo, motivo"},escopo:"contexto autenticado"};
function importar(linhas,ctx){const aceitas=[],rejeitadas=[];
linhas.forEach((l,i)=>{if(l.tenant!==ctx.tenant)rejeitadas.push({linha:i+1,codigo:"ESCOPO_INVALIDO",motivo:"Escopo não autorizado"});
else if(!Number.isSafeInteger(l.valor)||l.valor<0)rejeitadas.push({linha:i+1,codigo:"VALOR_INVALIDO",motivo:"Valor deve ser inteiro não negativo"});
else aceitas.push({id:l.id,valor:l.valor});});return {versao:1,aceitas,rejeitadas};}
function renderizar(resultado){return "Rejeições: "+resultado.rejeitadas.map(x=>"Linha "+x.linha+": "+x.motivo).join("; ");}
const resultado=importar([{tenant:"A",id:"p1",valor:100},{tenant:"A",id:"p2",valor:-1},
{tenant:"B",id:"p3",valor:100}],{tenant:"A"});
assert.equal(resultado.aceitas.length,1);assert.equal(resultado.rejeitadas[0].linha,2);
assert.ok(renderizar(resultado).includes("Linha 2: Valor deve ser inteiro não negativo"));
assert.ok(!resultado.aceitas.some(x=>x.id==="p3"));assert.equal(resultado.versao,contrato.versao);
const criterios=[{id:"AC1",entrada:"linha negativa",resultado:"rejeição com motivo",evidencia:"assert local do serviço"},
{id:"AC2",entrada:"resultado com rejeição",resultado:"número e motivo visíveis",evidencia:"assert de apresentação textual",
pendencia:"E2E da interface real não executado"},
{id:"AC3",entrada:"outro tenant",resultado:"escopo rejeitado",evidencia:"assert local de contexto"}];
const tarefas=[{id:"contrato",depende:[],saida:"schema e exemplos"},{id:"servico",depende:["contrato"],saida:"validação"},
{id:"interface",depende:["contrato"],saida:"apresentação"},{id:"e2e",depende:["servico","interface"],saida:"jornada verificada"}];
assert.ok(tarefas.every(t=>t.depende.every(id=>tarefas.some(x=>x.id===id))));
assert.ok(criterios.every(c=>c.evidencia||c.pendencia));
console.log({status:"verificações locais aprovadas",prd,contrato,resultado,criterios,tarefas,
discrepancia:"apresentação local existe; upload e E2E no produto continuam pendentes"});Como conferir seu resultado
- Critérios têm entradas e resultados observáveis.
- Mocks respeitam contrato versionado.
- Cada conclusão aponta evidência ou pendência.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Escrever comportamento observável.
- Relacionar contrato e dependências.
Três linhas: duas válidas, terceira negativa. Defina resposta e matriz; E2E não executado.
Conferir raciocínio e critérios de domínio
A política é importação parcial: as duas linhas válidas entram e a terceira não altera estado.
Uma resposta coerente é accepted=2 e rejected=[{index:3, reason: 'NEGATIVE_VALUE'}]. Uma confirmação de três importadas ou um erro sem linha/motivo viola o contrato.
A matriz associa validação ao unitário, escopo à integração e feedback ao E2E. Como o E2E não foi executado, a conclusão é funcionalidade ainda não comprovada de ponta a ponta.
Evidências para autoavaliação ou revisão por pares
- Política de importação: A política é importação parcial: as duas linhas válidas entram e a terceira não altera estado.
- Contrato da resposta: Uma resposta coerente é accepted=2 e rejected=[{index:3, reason: 'NEGATIVE_VALUE'}]. Uma confirmação de três importadas ou um erro sem linha/motivo viola o contrato.
- Evidência por camada: A matriz associa validação ao unitário, escopo à integração e feedback ao E2E. Como o E2E não foi executado, a conclusão é funcionalidade ainda não comprovada de ponta a ponta.
Um erro frequente
Lista de arquivos é plano de aceitação.
Plano liga necessidade, contrato, dependência e verificação observável.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. User story substitui contrato técnico?
Não.
Ela comunica necessidade, enquanto contratos especificam fronteiras e dados.
2. Task concluída prova requisito aceito?
Não.
É necessário ligar implementação à verificação do critério.
3. E2E aprovado prova todos os arquivos possíveis?
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Product requirements document
Atlassian • consulta: 2026-10-06
FundamentosObjetivos, escopo, requisitos e comunicação de decisões em PRD.
Limites: Formato sugerido pelo fornecedor; adaptar ao produto e evitar burocracia desnecessária.
- Spec Kit specification template
GitHub • consulta: 2026-10-06
FundamentosUser stories, acceptance scenarios, requisitos e critérios verificáveis.
Limites: Template no ramo main; adaptar ao projeto, sem confundir template com especificação concluída.
- Playwright Best Practices
Microsoft / Playwright • consulta: 2026-10-06
FundamentosTestes E2E de comportamento visível, isolamento, locators e assertions confiáveis.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- GitHub Spec Kit
GitHub • consulta: 2026-10-06
FundamentosFluxo requirements → specification → technical plan → tasks → implement/converge; consistência e checklists.
Limites: Ferramenta concreta para ensinar SDD, não padrão universal; comandos atuais podem diferir de tutoriais antigos.
- OpenAPI Specification 3.1.1
OpenAPI Initiative • consulta: 2026-10-06
FundamentosContrato HTTP, schemas, operações, parâmetros e respostas.
Limites: Versão fixada 3.1.1; suporte das ferramentas a JSON Schema/OpenAPI deve ser verificado.
- Structured model outputs
OpenAI • consulta: 2026-10-06
OpenAIJSON Schema, saída estruturada, strict mode e distinção entre resposta estruturada e function calling.
Limites: Suporte a subconjunto JSON Schema e modelos específicos; JSON válido não garante verdade factual ou regra de negócio.
- Spec Kit tasks template
GitHub • consulta: 2026-10-06
FundamentosQuebra de tarefas, dependências, ordenação e execução paralela quando aplicável.
Limites: Dependency graph explícito do curso é representação editorial derivada das dependências do plano.
- Effective harnesses for long-running agents
Anthropic • consulta: 2026-10-06
AgentesHarness, artefatos persistentes, progresso incremental, recuperação e testes de aplicação.
Limites: Relato de engenharia; harness mínimo e gates do curso são síntese pedagógica, não implementação fornecida completa.