Spec-Driven Development
Substitua o prompting ad-hoc por Live Specs e Context Packets estruturados para produzir saídas de agentes determinísticas e avaliáveis por meio do ciclo Especificar-Executar-Avaliar.
Visão Geral
Spec-Driven Development é um padrão de fluxo de trabalho no qual cada unidade de trabalho do agente começa com uma especificação estruturada — uma Live Spec — em vez de um prompt ad-hoc em linguagem natural. O Context Architect cria a especificação, um agente a executa e um Eval Harness valida o resultado. Este ciclo de três fases — Especificar, Executar, Avaliar — é a metodologia de Spec Driven Development descrita no Agentic Development Handbook e é a principal alternativa ao Vibe Coding.
Problema
Equipes que dependem de prompting ad-hoc encontram modos de falha previsíveis:
- Saídas não reprodutíveis. A mesma intenção redigida de forma diferente produz códigos diferentes. Não há um artefato estável para versionar, comparar (diff) ou revisar.
- Falta de contexto. Os prompts raramente carregam todo o contexto do sistema de que um agente precisa — restrições de arquitetura, contratos de interface, padrões de qualidade — então o agente adivinha, e as suposições divergem.
- Sem âncora de avaliação. Sem critérios de aceitação legíveis por máquina, não há como verificar automaticamente se a saída do agente satisfaz o requisito. A revisão torna-se um processo manual e subjetivo.
- Deriva entre sessões. O conhecimento evapora entre as sessões do agente. Cada nova conversa começa do zero, a menos que o desenvolvedor forneça o contexto manualmente de novo.
Esses problemas se agravam à medida que as equipes escalam o número de agentes e tarefas. O que funciona para um único desenvolvedor conversando com um copilot falha quando vários agentes executam em paralelo em uma base de código.
Solução
Substitua o prompt ad-hoc por uma camada de especificação formal composta por dois artefatos:
- Live Spec — Um documento versionado e legível por máquina que define o que o agente deve construir, incluindo contratos comportamentais, critérios de aceitação e referências ao contexto relevante.
- Context Packet — Um conjunto agrupado de arquivos, esquemas, exemplos e instruções que o agente recebe junto com a especificação. Os Context Packets fornecem o como — decisões de arquitetura, padrões de codificação, contratos de API e Golden Samples que demonstram a qualidade de saída esperada.
O Context Architect cria e mantém esses artefatos. A execução segue o Fluxo de Trabalho Triangular:
- Especificar — O Context Architect escreve ou atualiza a Live Spec com critérios de aceitação claros e anexa o Context Packet relevante.
- Executar — O agente recebe a especificação e o contexto, produzindo então código, testes ou documentação.
- Avaliar — O Eval Harness executa verificações automatizadas em relação aos critérios de aceitação definidos na especificação. Falhas retornam para a fase de Execução com contexto de diagnóstico; aprovações avançam a saída para etapas de revisão humana.
Este padrão aplica os princípios de Context Engineering: o gargalo no desempenho do agente não é a capacidade do modelo, mas a qualidade e a integridade do contexto fornecido ao modelo.
Implementação
Exemplos de Código
Can you create a React product card component? It should show the
product image, name, price, and have an add-to-cart button. Use
TypeScript and Tailwind. Make it responsive.This prompt lacks architecture context, has no acceptance criteria, and produces non-reproducible results.
# specs/product-card.spec.yaml
spec:
id: product-card-v2
title: Product Card Component
status: active
author: "@context-architect"
behavioral_contract:
description: >
A presentational React component that displays a single product
with image, name, formatted price, and an add-to-cart action.
inputs:
- name: product
type: "Product"
source: "src/types/product.ts"
outputs:
- rendered ProductCard component
- onAddToCart callback invocation with product ID
acceptance_criteria:
- id: ac-1
description: Renders product image with lazy loading
validation: unit-test
- id: ac-2
description: Displays formatted price using currency util
validation: unit-test
- id: ac-3
description: Calls onAddToCart with product.id on button click
validation: unit-test
- id: ac-4
description: Passes axe accessibility audit with zero violations
validation: a11y-check
- id: ac-5
description: Responsive layout at 320px, 768px, and 1024px breakpoints
validation: visual-regression
context_references:
- path: context/frontend-standards.md
- path: context/component-patterns.md
- path: src/types/product.ts
- path: src/components/ExampleCard.tsx # golden sample
scope:
includes:
- ProductCard component implementation
- Unit tests for all acceptance criteria
excludes:
- Cart state management
- API integrationConsiderações
- • **Reproducibility.** The same spec produces consistent agent output regardless of phrasing, session, or agent model.
- • **Evaluability.** Machine-readable acceptance criteria enable automated validation through the [[eval-harness]], reducing reliance on manual review.
- • **Knowledge accumulation.** Specs and Context Packets are versioned artifacts that capture institutional knowledge. They survive developer turnover and agent model changes.
- • **Parallelization.** Multiple agents can execute against different specs simultaneously because each spec is self-contained with its own context.
- • **Governance integration.** Specs provide a natural gate for [[gate-based-governance]] — review the spec before authorizing execution, then review agent output against the spec criteria.
- • **Measurable improvement.** Teams can track spec pass rates over time and identify which context gaps cause the most failures.
- • **Upfront investment.** Writing a Live Spec takes more time than typing a prompt. The payoff comes from reuse, reproducibility, and reduced rework — but teams must commit to the practice before seeing returns.
- • **Spec maintenance.** Specs must evolve with the codebase. Stale specs produce incorrect agent output. Teams need processes (or agents) to keep specs current.
- • **Context Packet curation.** Assembling and maintaining high-quality Context Packets requires ongoing effort from the [[context-architect]]. Under-specified context leads to the same problems as ad-hoc prompting.
- • **Tooling maturity.** The ecosystem for spec-driven agent workflows is still developing. Teams may need to build custom tooling for spec parsing, context assembly, and eval harness integration.
- • **Cultural shift.** Developers accustomed to direct coding or conversational prompting may resist the overhead of writing specs. Leadership must reinforce that specs are the primary engineering artifact in an agentic workflow.