Padrões de Design
Fluxo de TrabalhoIntermediário

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:

  1. 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.
  2. 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:

  1. Especificar — O Context Architect escreve ou atualiza a Live Spec com critérios de aceitação claros e anexa o Context Packet relevante.
  2. Executar — O agente recebe a especificação e o contexto, produzindo então código, testes ou documentação.
  3. 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

1

2

3

4

5

6

Exemplos de Código

Ad-Hoc Prompt (Before)
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.

Live Spec (After)
# 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 integration

Considerações

Benefícios
  • • **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.
Desafios
  • • **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.