Spec-Driven Development em time: o workflow de spec compartilhada

Sozinho, a spec é disciplina contra o seu próprio desvio. Em time, ela vira o contrato que todo mundo lê em vez de tentar ler a mente do outro. Mesmo documento, trabalho maior.

Quem procura Spec-Driven Development para time normalmente já usou sozinho. Leu o estudo de caso, testou numa feature, viu um agente construir a coisa certa a partir de uma boa spec, e agora quer levar isso para as pessoas com quem trabalha. A pergunta por baixo é se o método sobrevive ao contato com um segundo dev, um revisor e uma codebase compartilhada.

Sobrevive. Mas uma coisa muda, e não perceber isso é como você acaba em teatro de processo: uma pasta de specs que ninguém lê e um ritual em que ninguém acredita. Sozinho, a spec é a sua disciplina contra o seu desvio e o do agente. Em time, a spec ganha um segundo trabalho. Ela vira um contrato, entre pessoas e entre squads. O documento é o mesmo. O trabalho é maior.

Este é o complemento prático do estudo de caso solo e de como escrever uma spec. Ele cobre o que realmente muda quando uma spec tem mais de um leitor: versionar a spec como contrato compartilhado, revisar por pull request, manter as convenções na ferramenta em vez de na cabeça das pessoas, colocar o gate num board, e o motivo pelo qual o workflow inteiro se paga, que é o gargalo sair de escrever código e ir para integrá-lo.

O que muda quando a spec tem mais de um leitor

Sozinho, a spec faz um trabalho. Ela é a única memória que o agente recebe e é a disciplina que te impede de se afastar do que você realmente quis dizer. Em time, ela mantém esse trabalho e ganha mais dois.

Os três trabalhos de uma spec de time

O documento não muda. O número de leitores muda, e essa é toda a diferença.

A spec fica entre	O que ela carrega	Solo ou time
Humano e agente	A única memória que o agente recebe. Limita o desvio dele.	Os dois
Humano e humano	O que um colega lê em vez de tentar ler a sua mente.	Só time
Squad e squad	O contrato na fronteira onde dois times se integram.	Só time

O modo de falha é tratar uma spec de time como uma spec solo com mais autores. Você continua escrevendo notas particulares, adiciona uma pasta compartilhada e chama isso de prática. As notas ainda pressupõem tudo o que mora na sua cabeça. Um colega abre o arquivo, bate na primeira regra implícita e chuta, que é exatamente o problema que specs existem para eliminar.

Versione a spec, ou você não tem uma prática de time

O git é o que transforma uma spec de memória particular em contrato compartilhado. A spec mora no repo, ao lado do código que ela governa, versionada junto com ele. Uma fonte da verdade, um histórico, um lugar para olhar.

Isso você talvez já faça sozinho. O passo que faz disso uma prática de time é aquele sobre o qual ninguém escreve: a spec entra em review antes de o código existir.

Um code review depois da implementação pega erro de digitação numa decisão que já estava errada. Um review de spec pega a decisão errada antes de uma única linha codificá-la. Então os requisitos chegam como pull request, um revisor lê, e só quando ele aprova o .status vira requirements:approved e o design começa. O mesmo para o design. O mesmo para as tarefas.

Deixe o cânone na ferramenta, não na cabeça

Sozinho, as suas convenções moram em você. A régua do Smart Kid, a gramática EARS, o hábito de escrever um escopo negativo explícito: você aplica sem pensar porque são suas. Em time, se isso vive só na cabeça das pessoas, o SDD de cada dev vai para um lado e você acaba com cinco dialetos de spec que não se parecem em nada.

A solução é colocar o cânone onde a ferramenta lê, não onde uma pessoa lembra. Arquivos de steering compartilhados guardam o contexto de produto e as regras. Skills levam o formato e a régua para o agente de cada dev. O sistema de contexto em três camadas que um dev solo mantém para si vira aquilo que o time inteiro compartilha.

O cânone compartilhado, versionado para todos

• .ai/
  • steering/
    • product.md// o que estamos construindo e para quem
    • tech-stack.md// a stack e as regras que prendem o agente
    • conventions.mda régua// formato de spec, gates, regras de código, compartilhados por todos
  • sdd/specs/012-login-otp/
    • .statusgate// stage:state, o gate legível por máquina
    • requirements.md// o QUÊ, revisado por PR antes do design
    • design.md// o COMO
    • tasks.md// o QUANTO

É assim também que o onboarding muda. Um dev novo lê o corpus de specs e os arquivos de steering, não uma página de wiki e um tapinha no ombro de alguém. As specs são o material de orientação, porque são o registro de cada decisão e do porquê dela. A régua viaja na ferramenta, então quem entrou ontem escreve uma spec que parece de alguém que está lá há dois anos.

Quem é dono da spec

Sozinho, você faz os quatro papéis ao mesmo tempo: escreve os requisitos, decide o design, quebra as tarefas e revisa o resultado. Em time esses papéis se separam e, no momento em que isso acontece, a questão de quem é dono fica real.

Mapeie para os papéis que o SDD já nomeia. Quem escreve os requisitos é dono do QUÊ. Um arquiteto, humano ou agente, é dono do design. Um revisor é dono do gate. Nada disso é pesado. São as mesmas pessoas que já revisam código, fazendo isso um passo antes, no documento em vez do diff.

A pergunta que importa de verdade é o que acontece quando dois devs querem coisas diferentes. Sem SDD, eles descobrem no merge, ou depois, em produção, quando os dois já construíram a sua versão. Com SDD, a discordância aparece no pull request dos requisitos, nos comentários, antes de qualquer um dos dois escrever código.

Onde uma discordância aparece, e quanto custa

O valor de uma spec em time não é documentação. É levar a discussão para a camada mais barata de ter.

Onde o conflito aparece	Quanto custa resolver
No PR dos requisitos (SDD)	Uma thread de comentários, antes de existir código.
No code review, depois da implementação	Reescrever uma feature que já funciona.
Na integração, entre dois squads	Duas implementações que não se encaixam.
Em produção	Um incidente, e depois tudo o que está acima.

Coloque o gate num board

O arquivo .status é o gate. Ele é legível por máquina e existe um por spec. Sozinho, você mesmo lê e isso basta. Em time, um gate que só existe num arquivo que ninguém abre é um gate que acaba pulado, porque a maioria das pessoas não enxerga.

Então você torna ele visível. Um board em que cada coluna é uma etapa do SDD. Um card é uma feature. O card anda quando o gate dele é aprovado, e aprovar é mover.

Como uma feature anda pelo board

Entrada

Uma feature nova entra no backlog

↓

1. PRDEscrever e aprovar o QUÊ

   O requirements.md abre como pull request. Um revisor aprova. O .status vira requirements:approved. Nada mais adiante começa antes disso.

   ↓
2. SPECDesenhar a partir do QUÊ aprovado

   O design.md mapeia cada requisito para uma decisão. É aprovado do mesmo jeito, por review, no git, antes de qualquer tarefa ser quebrada.

   ↓
3. TASKSQuebrar o trabalho em gates

   O tasks.md divide o design em unidades de 2 a 4 horas, cada uma testável de forma independente, cada uma aprovada antes de uma linha de código ser escrita.

   ↓
4. EXECConstruir, depois revisar o diff

   O agente implementa a partir da spec aprovada. O pull request é onde um humano confere o diff contra a spec que ele deveria atender.

↓

Saída

Toda mudança de coluna é um gate que um humano aprovou. Pular um é bloqueado por branch protection, não por confiança.

Existe um repo de referência completo, funcionando, exatamente para isso: acme-store-sdd. Ele roda esse fluxo num board do GitHub Projects, com cada card andando conforme o gate .status é aprovado, e branch protection na main que recusa merge sem review. Clone e leia o .github/workflows junto com a pasta .ai/sdd/specs. O board não é o ponto. O board é o gate tornado visível, e você pode ver ao vivo: sete colunas, uma por etapa do SDD, cada card parado onde o .status da spec dele manda.

O gargalo sai de escrever código e vai para integrá-lo

Este é o motivo pelo qual tudo isso se paga em time, e não tem nada a ver com velocidade de digitação.

Sozinho, o seu gargalo era o seu próprio ciclo: você, um agente, uma feature por vez. Em time, gerar código fica barato rápido, porque todo mundo tem um agente. O time consegue produzir várias vezes mais código do que antes. Mas o que efetivamente vai para produção não cresce no mesmo ritmo, porque a parede mudou de lugar. Agora ela é o review, o deploy e a coordenação entre pessoas e squads.

Um time pode gerar dez vezes mais código e integrar mais ou menos o mesmo de sempre, porque digitar nunca foi a restrição. Integrar era. Revisar, conciliar, garantir que o que uma pessoa construiu encaixa no que outra pessoa construiu: esse é o trabalho que não fica mais barato só porque o código aparece mais rápido.

O board desenha isso na parede. Coloque um limite de WIP na coluna de review e veja os cards se acumularem ali. Essa pilha é a sua restrição real, tornada visível. Nenhum agente mais rápido resolve. Ela só anda quando a spec fez o seu trabalho como camada de coordenação, para que o trabalho de muitos devs e muitos agentes se encaixe em vez de colidir.

Conforme os times começam a adotar agentes em escala, o padrão é consistente, e não é o que os fornecedores de ferramentas vendem. O agente quase nunca é o gargalo. A integração é. Uma spec compartilhada é como um time impede que a integração vire a parede, porque ela é a interface que permite que trabalho em paralelo se encaixe na primeira tentativa, não na terceira.

Você está rodando SDD ou só arquivando specs?

Gate de prontidão do time

• ✓Obrigatório:
  As specs moram no git, versionadas ao lado do código que governam.Se elas moram numa wiki ou num notebook, não são um contrato compartilhado. São notas particulares com passos extras.
• ✓Obrigatório:
  Toda spec é revisada e aprovada num pull request antes de a implementação começar.Uma spec mergeada que ninguém revisou é um rascunho com um check verde.
• ✓Obrigatório:
  As convenções moram em arquivos de steering e skills compartilhados, não na cabeça de um dev sênior.Se ensinar alguém a escrever spec exige um tapinha no ombro, a régua ainda não está na ferramenta.
• ✓Obrigatório:
  O gate é visível: qualquer um consegue ver quais features estão aprovadas e quais ainda são rascunho.Um board, uma coluna por etapa. Se o gate só existe num arquivo .status que ninguém abre, ele não é visível.
• ✓Obrigatório:
  Branch protection bloqueia merge sem review.O gate tem que ser físico, não uma norma que as pessoas lembram nos dias bons.
• ✓Obrigatório:
  A discordância sobre um requisito acontece na spec, não na integração.Se dois devs descobrem que construíram coisas diferentes na hora do merge, a discussão apareceu na camada mais cara.

FAQ

Quem aprova o gate em time?+

O papel de revisor: a mesma pessoa que revisaria o código, só que um passo antes, no documento. Na prática, um tech lead ou um sênior do squad aprova requisitos e design, e qualquer pessoa competente pode aprovar as tarefas. A aprovação é um ato humano, com nome, registrado no pull request e no arquivo .status, não um 'parece ok' implícito.

Você não precisa de um comitê. Um revisor competente por gate basta. O que não dá é não ter ninguém, porque um gate sem aprovador não é um gate.

O que acontece quando dois devs discordam sobre um requisito?+

A discordância vai para o pull request dos requisitos, como comentários, e é resolvida antes de qualquer um dos dois escrever código. Esse é todo o argumento econômico para trabalhar assim.

A mesma discordância descoberta na integração custa duas implementações prontas que não se encaixam. Descoberta em produção, custa um incidente. Leve a discussão para a camada mais barata de ter.

Precisamos mesmo de um board, ou o arquivo .status basta?+

Sozinho, o arquivo basta, porque você mesmo lê. Em time o arquivo é invisível, e um gate invisível acaba pulado. O board é o .status visível para todo mundo ao mesmo tempo. É uma visão por cima dos arquivos, não uma segunda fonte da verdade.

O board também expõe o gargalo de integração, coisa que um arquivo não faz. Uma coluna passando do limite de WIP é uma restrição para a qual você consegue apontar.

Usamos Jira, não GitHub Projects. Isso ainda funciona?+

Sim. O princípio é: colunas são as etapas do SDD, e um card aponta para a spec no git. A marca do board não importa.

O que importa é que o board reflita o gate e nunca vire o lugar onde a spec de fato mora. O git guarda o artefato, o board reflete o estado.

Toda feature precisa da spec completa de três documentos em time?+

Não, a regra é a mesma de quando você trabalha sozinho. Um fix de uma hora não merece um requirements.md. O que muda em time é que o limite passa a ser uma decisão compartilhada, não pessoal.

Combinem quando uma mudança precisa de spec, depois escrevam essa regra nas convenções e coloquem no arquivo de steering, para que os humanos e o agente apliquem o mesmo limite em vez de seis diferentes.

Como isso escala para além de um squad?+

A spec na fronteira do squad vira o contrato entre squads. Quando um time depende de outro, a interface é uma spec que os dois lados aprovam, não uma thread de chat que os dois lados esquecem.

É o mesmo mecanismo um nível acima: levar a coordenação para um artefato versionado que os dois lados revisam, para que a integração entre times seja projetada de propósito em vez de descoberta no merge.

Para onde ir agora

O SDD não muda quando você adiciona pessoas. A spec faz o mesmo que sempre fez. O que muda é que a disciplina tem que sair da sua cabeça e virar algo que um time consegue ver, revisar e fazer valer. Versione, revise num pull request, coloque o gate num board e deixe a branch protection segurar a linha. O método sempre foi sobre levar as decisões para o lugar mais barato de tomá-las, e é em time que isso rende mais.