SPDD: A Camada Que Faltava Entre SDD e Harness Engineering

Nos últimos dois posts, falei sobre SDD e Harness Engineering como camadas complementares do stack de desenvolvimento agêntico. SDD define o que construir. Harness define como o agente executa de forma confiável. Mas havia um gap óbvio entre os dois — e a Thoughtworks acabou de nomear e documentar esse gap.

O nome é SPDD: Structured Prompt-Driven Development. O artigo foi publicado no site do Martin Fowler esta semana, e é a continuação natural do Harness Engineering, escrita pela equipe interna de desenvolvimento da própria Thoughtworks.

A premissa central é incômoda, mas difícil de rebater: a maioria dos times que usa agentes IA hoje tem um problema de conhecimento efêmero. Cada dev constrói o contexto do agente do zero, na conversa, na hora. O que funciona para um não funciona para outro. O que o agente "aprendeu" sobre o projeto numa sessão desaparece na próxima. O conhecimento de domínio que você levou meses para construir não está em nenhum lugar que o agente consiga acessar de forma estruturada.

SPDD resolve exatamente isso — e faz parte de uma trilogia que, honestamente, precisava ser completada.

O Problema Que SPDD Nomeia

Para entender por que SPDD importa, pense em como o seu time usa agentes de IA hoje.

Provavelmente cada dev tem uma forma diferente de "chamar" o agente para uma tarefa. Uns são prolixos, dão muito contexto. Outros vão direto ao ponto. Uns lembram de mencionar as convenções do projeto, outros não. E quando a mesma tarefa aparece de novo — implementar autenticação, adicionar um novo endpoint, refatorar um módulo — o contexto precisa ser reconstruído do zero, na próxima sessão, da cabeça de quem está na cadeira.

É um modelo que escala mal. Não porque o agente seja ruim. Mas porque o input do agente depende da pessoa e do momento, não de um artefato de time.

A solução de SPDD é simples de enunciar e trabalhosa de implementar bem: tratar prompts como código. Versionar, revisar, reutilizar, melhorar ao longo do tempo. Transformar o contexto que hoje vive na cabeça de cada dev em um artefato compartilhado que o time inteiro pode usar, auditar e evoluir.

O REASONS Canvas: A Estrutura Do Prompt

O coração do SPDD é uma estrutura de prompt chamada REASONS Canvas. Cada letra corresponde a uma dimensão que o prompt precisa cobrir:

R — Requirements (Requisitos) O "por quê" do negócio. Não a tarefa técnica, mas o objetivo que a justifica. O que esta feature resolve para o usuário? Qual é o critério de sucesso do ponto de vista de produto?

E — Entities (Entidades) O modelo de domínio relevante para a tarefa. Quais são as entidades envolvidas? Como elas se relacionam? Qual é o vocabulário do domínio que o agente precisa conhecer para não inventar nomes e conceitos que não existem no sistema?

A — Approach (Abordagem) A estratégia de solução e os trade-offs conscientes. Por que essa abordagem e não outra? Quais alternativas foram consideradas e descartadas? Isso evita que o agente "re-descubra" uma abordagem que o time já avaliou e rejeitou.

S — Structure (Estrutura) A arquitetura do sistema onde a implementação vai viver. Dependências, padrões de organização de código, interfaces existentes. O agente precisa saber onde encaixar o código novo sem quebrar a coerência do que já existe.

O — Operations (Operações) As tarefas de implementação em sequência. Um breakdown concreto e ordenado do que precisa ser feito — não o código, mas o roteiro que o agente vai seguir.

N — Norms (Normas) Os padrões de código do time. Convenções de nomenclatura, padrões de erro, estilo de testes, regras de lint. Tudo que está implícito na cultura do time mas que o agente não consegue inferir sem ser informado.

S — Safeguards (Salvaguardas) Restrições explícitas. O que o agente não deve fazer. Onde não deve tocar. Quais decisões precisam de aprovação humana antes de serem implementadas.

Um REASONS Canvas bem preenchido para uma feature média tem entre 400 e 800 palavras. Parece muito — até você comparar com quanto tempo o time perde quando o agente implementa a coisa errada porque o contexto estava incompleto.

O Workflow Na Prática

O fluxo de trabalho do SPDD tem quatro momentos principais:

1. Análise (user story → contexto estruturado) O PO escreve a user story. O dev roda /spdd-analysis, que extrai os conceitos de domínio envolvidos, identifica riscos e ambiguidades, e produz uma lista de perguntas para clarificação antes de começar a implementar. Essa etapa sozinha já elimina uma quantidade significativa de retrabalho — você descobre o que está ambíguo antes de o agente implementar.

2. Geração do Canvas (contexto → REASONS Canvas) Com as ambiguidades resolvidas, /spdd-prompt gera o REASONS Canvas completo: modelo de domínio, abordagem de solução, breakdown de tarefas, constraints. Esse artefato fica no repositório, junto com o código.

3. Execução (REASONS Canvas → código) O agente recebe o REASONS Canvas como contexto estruturado e implementa. O output é mais previsível porque o input é mais completo e padronizado — não depende do estilo pessoal de quem está na cadeira.

4. Sincronização (código → canvas atualizado) Aqui está o insight mais importante do SPDD: quando o código é refatorado ou modificado, /spdd-sync atualiza o canvas para refletir as mudanças. O prompt não fica desatualizado. Esse loop fechado é o que transforma o canvas em um documento de design vivo, não em documentação que envelhece.

Onde SPDD Se Encaixa No Stack

Nos últimos dois posts, a conversa girou em torno de duas camadas: SDD na camada de intenção e Harness na camada de execução. SPDD é precisamente a camada de comunicação entre as duas.

┌─────────────────────────────────────────┐
│  SDD — Camada de Intenção               │
│  (o que construir: spec, critérios,     │
│   constraints de negócio)               │
└─────────────────────┬───────────────────┘
                      │
┌─────────────────────▼───────────────────┐
│  SPDD — Camada de Comunicação           │
│  (como passar intenção ao agente:       │
│   REASONS Canvas versionado,            │
│   revisável, reutilizável)              │
└─────────────────────┬───────────────────┘
                      │
┌─────────────────────▼───────────────────┐
│  Harness — Camada de Execução           │
│  (como o agente executa com segurança:  │
│   guides, sensors, feedback loops)      │
└─────────────────────────────────────────┘

SDD sem SPDD é como ter um contrato bem escrito mas sem nenhum briefing para quem vai executar — a intenção existe, mas chega fragmentada e dependente de interpretação.

SPDD sem SDD é como ter um briefing muito bem estruturado para uma tarefa que não foi bem especificada — formato impecável, direção errada.

Harness sem SPDD é como ter uma infraestrutura de execução excelente alimentada por input ad hoc — o ambiente está preparado, mas o contexto que entra no agente varia com quem está na cadeira.

Os três juntos formam um sistema coerente: a spec define o que, o canvas traduz isso em contexto estruturado para o agente, e o harness garante que a execução é confiável e autocorretiva.

O Insight Sobre Conhecimento de Time

O ponto que mais me chamou atenção no artigo do Fowler não é técnico — é organizacional.

SPDD muda fundamentalmente onde o conhecimento de domínio do time fica armazenado. Hoje, esse conhecimento está distribuído em: cabeças das pessoas (evapora quando alguém sai), commits (difícil de navegar), PRs (contexto fragmentado), Confluence/Notion (desatualizado por padrão), e sessões de chat com o agente (completamente efêmeras).

Com SPDD, o canvas de cada feature se torna um terceiro tipo de artefato de código — junto com o código de produção e os testes. Quando alguém entra no time, não precisa reverse-engineer a intenção a partir de commits e código. Lê o canvas e entende: por que essa feature existe, quais trade-offs foram feitos, quais eram as constraints, qual era a abordagem escolhida.

É documentação que o processo de desenvolvimento força a manter atualizada — não documentação que depende de disciplina para ser escrita e atualizada.

A Thoughtworks descreve isso como transformar AI assistance from personal efficiency into organizational capability. Um agente que você usa bem individualmente é produtividade pessoal. Um time que compartilha artefatos bem escritos, revisados e versionados é uma capacidade organizacional que escala, persiste e melhora com o tempo.

Três Habilidades Que SPDD Exige

O artigo identifica três habilidades que devs precisam desenvolver para trabalhar bem com SPDD:

Alignment (Alinhamento): a capacidade de extrair intenção do PO de forma estruturada antes de começar a implementar. Não é uma habilidade técnica — é uma habilidade de facilitação. Fazer as perguntas certas, trazer à tona as ambiguidades antes que elas virem retrabalho.

Abstraction-first (Abstração Primeiro): pensar em domínio, entidades e relações antes de pensar em código. Isso vai contra o instinto de muitos devs que querem ir direto para a implementação — mas é a habilidade que torna o canvas útil em vez de superficial.

Iterative Review (Revisão Iterativa): tratar o canvas como um artefato vivo que precisa de code review, assim como o código. Revisar artefatos de colegas, identificar quando estão incompletos ou ambíguos, e manter o /spdd-sync disciplinado para que canvas e código não divirjam.

Nenhuma dessas habilidades é nova para devs sêniors — são variações de habilidades que tech leads já exercitam. O que SPDD faz é torná-las parte do processo de trabalhar com agentes, não uma atividade separada e opcional.

Por Que Agora

O timing do artigo não é coincidência. A Thoughtworks está documentando o que os times internos deles foram descobrindo ao longo de meses usando agentes em produção — o mesmo processo que gerou o Harness Engineering e, agora, o SPDD.

O contexto importa: agentes de IA estão ficando mais capazes mais rápido do que os processos de time estão se adaptando. A maioria dos times que usa Claude, Cursor, Copilot ou Kiro hoje ainda opera no modelo ad hoc — cada dev, cada sessão, cada conversa. Esse modelo funciona para tarefas individuais e autocontidas. Começa a falhar em trabalho de time, em projetos maiores, em features com histórico.

SPDD é a resposta para esse scaling problem. Não é mais uma metodologia para substituir as anteriores — é a peça que completa o stack que SDD e Harness Engineering começaram a montar.

O Que Fazer Com Isso

Se você quiser experimentar SPDD sem virar o workflow do time de cabeça para baixo:

Comece com uma feature nova. Antes de começar a implementação, escreva um REASONS Canvas — mesmo que informal, mesmo que apenas R, E e O. Observe se o agente se comporta diferente. Observe se você consegue reusar o canvas numa feature similar duas semanas depois.

Coloque o canvas no repositório. Mesmo num diretório .agent/prompts/ ou similar. A disciplina de versionar força a manter atualizado.

Revise artefatos, não só código. Na próxima PR, inclua o canvas junto. Peça para alguém revisar. Perguntas sobre o canvas vão trazer à tona ambiguidades de design que o code review sozinho não captura.

Feche o loop. Quando refatorar, atualize o canvas. Essa disciplina é o que transforma o canvas em ativo de longo prazo, não em documentação que envelhece.

Conclusão

A trilogia está completa — pelo menos por enquanto.

SDD define o contrato do que construir. SPDD traduz esse contrato em contexto estruturado, versionável e reutilizável para o agente. Harness Engineering garante que o agente execute dentro desse contexto de forma confiável e autocorretiva.

Três camadas, três problemas distintos, três soluções que se reforçam. O stack de desenvolvimento agêntico maduro está começando a tomar forma — e o que a Thoughtworks publicou no site do Fowler esta semana é mais uma peça que encaixa.

A pergunta que fica: o seu time está tratando prompts como ativos ou como conversas descartáveis?

Fontes

• Structured Prompt-Driven Development (SPDD) — Martin Fowler
• Harness Engineering for Coding Agent Users — Martin Fowler / Birgitta Böckeler
• Treating AI Prompts Like Code: What I Learned From Thoughtworks' SPDD Method
• open-spdd: A SPDD AI Coding Assistant Command Template Manager — GitHub
• Spec-Driven Development: Unpacking One of 2025's Key Practices — Thoughtworks
• Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl — Martin Fowler