Vale a pena escrever spec quando você programa sozinho?

Escrever documento pra si mesmo é estranho, vamos combinar

Você abre um markdown vazio, descreve um sistema que por enquanto só existe na sua cabeça, pra um leitor que é você mesmo daqui a pouco

O argumento clássico do spec-driven development é alinhamento: todo mundo do time lê o mesmo documento antes de alguém encostar no código. Só que, quando você programa sozinho, esse argumento simplesmente não existe

E mesmo assim o SDD virou padrão nessa era de agente, a ponto de já ter verbete próprio na Wikipedia

Então bora ao veredito honesto, incluindo os casos em que escrever spec só atrasa a sua vida 🙂

O que é spec-driven development (e por que ele apareceu agora)

A ideia é simples de explicar e chata de executar: antes do agente sair codando, você documenta o requisito, o design técnico e a lista de tarefas

Se você já mandou um briefing pra um freela, é mais ou menos isso. A diferença é que o freela aqui é a IA, e ela não pergunta "mas e se o usuário estiver deslogado?" antes de escrever 400 linhas

E por que isso apareceu AGORA? Porque o gargalo mudou de lugar. Escrever código deixou de ser a parte cara, e dizer com precisão o que se quer virou a parte cara

O ecossistema acompanhou. A própria GitHub mantém o github/spec-kit, descrito como um toolkit pra você começar com Spec-Driven Development

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

A AWS foi mais longe e fez uma IDE inteira em cima do conceito: o Kiro, baseado no Visual Studio Code, que transforma prompt em requisitos, design estruturado e tarefas de implementação

E tem a turma que acha tudo isso pesado demais, representada pelo Fission-AI/OpenSpec, que se apresenta como spec-driven development pra assistentes de código, numa pegada mais leve

Se liga no detalhe: nenhuma dessas ferramentas nasceu pra resolver reunião. Elas nasceram pra alimentar agente

O custo real da spec pra quem programa sozinho

Agora a parte que quase ninguém coloca no post de hype. O processo tem preço, e ele é cobrado em três frentes

Primeira: o fluxo é document-heavy por definição. Não é só gerar os documentos, é REVISAR. Você precisa ler as user stories e as tarefas antes do agente começar a executar, senão você só automatizou o erro

Segunda: passam a existir dois artefatos vivos. A spec e a implementação coexistem, e as duas precisam ficar em sincronia. Toda vez que o requisito muda, atualizar a spec antes do código adiciona fricção

Terceira, e essa é a crítica central: o caro não é escrever a spec, é MANTER a spec. Escrever dá um trabalho pontual, manter dá trabalho pra sempre

E aí vem o ponto que morde justamente quem trabalha sozinho: adotar o fluxo sem mudar a colaboração gera só documentação a mais

Ou seja, no time o documento paga a conta virando canal de alinhamento. Sozinho não existe colaboração pra mudar, então o documento tem que se pagar de outro jeito

Spoiler: ele se paga, mas não como documentação oficial

Spec completa, spec leve ou plan mode: comparativo pro dev solo

Dá pra pensar em três níveis de formalidade, do mais cerimonioso pro mais cru

No nível completo mora o Kiro, onde as specs vivem em .kiro/specs/ e são três arquivos: requirements.md com user stories e critérios de aceite, design.md com arquitetura técnica e diagramas de sequência, e tasks.md com o plano de implementação em tarefas rastreáveis

O requirements.md do Kiro usa notação EARS (Easy Approach to Requirements Syntax), um método padronizado pra escrever requisito sem ambiguidade. E os três arquivos entram automaticamente no contexto da conversa, pra resposta ficar alinhada com o que está documentado

O Spec Kit também joga no nível completo, mas por outro caminho: CLI specify e um fluxo de comandos com prefixo speckit. (/speckit.constitution, /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.checklist, /speckit.tasks, /speckit.analyze, /speckit.implement e /speckit.converge)

Depois do specify init, esses comandos ficam gravados na pasta do agente dentro do próprio projeto (.claude/, .github/prompts/, .pi/prompts/, .omp/commands/, conforme o agente escolhido). É a mesma lógica de instrução que mora no repositório e o agente carrega, que é o que rola quando você usa uma skill no Claude

No nível leve tem o OpenSpec e tem também um padrão intermediário bem honesto: a spec semeia a geração inicial e o código fica livre pra divergir depois. Isso é indicado pra feature assistida por IA e pra protótipo, com baixo overhead e nenhuma garantia de longo prazo

E no nível zero de formalidade tem o plan mode do Claude Code, que é reconhecido no sistema de permissões da ferramenta: a allowlist fixa inclui ferramentas que não modificam estado, entre elas as transições de plan mode

Repara que a coluna que mais dói não é a de esforço, é a de manutenção. Esforço você paga uma vez, manutenção você paga todo mês

Quando a spec paga a conta trabalhando sozinho

Tem cenário em que o retorno aparece mesmo sem ninguém pra alinhar, e o fio condutor é sempre o mesmo

O ganho apontado por quem usa SDD está no processo de pensamento, não no documento em si: te obriga a pensar a fundo os requisitos do caso de uso, documentar as considerações de arquitetura e delinear a abordagem de implementação

Onde isso vira dinheiro pro dev solo:

• Tarefa grande com requisito ambíguo. Se você não sabe direito o que é "pronto", o agente vai adivinhar por você. Spoiler: ele adivinha bonito e errado
• Feature que a IA vai implementar de ponta a ponta. Quanto menos você vai digitar, mais o texto do briefing importa. É o mesmo raciocínio de escrever a descrição no Claude Design pra o rascunho já sair perto do que você queria
• Protótipo que só precisa de direção inicial. Aqui a spec semeia a geração e depois você deixa o código divergir à vontade, sem culpa
• Projeto que você vai abandonar e retomar em alguns meses. O "você do futuro" é praticamente outra pessoa, e essa pessoa não tem contexto nenhum

Esse último caso é sacana. Você acha que vai lembrar, e não vai

Quando não compensa: os casos em que a spec só atrasa

Agora o contraponto, porque post que só elogia processo não serve pra decidir nada

É recomendado PULAR o SDD em feature pequena, onde o overhead supera o retorno. Se a mudança cabe em um parágrafo de conversa, escrever três documentos pra ela é cerimônia, não engenharia

Requisito que ainda vai mudar três vezes essa semana também não merece spec. Lembra da fricção: atualizar a spec antes do código, a cada troca de ideia, transforma o seu dia em reunião consigo mesmo

Código exploratório idem. Quando você ainda está descobrindo se a abordagem funciona, a especificação está descrevendo uma coisa que talvez nem exista amanhã

E manutenção que morre em duas horas, então, nem discute

Tome cuidado com a armadilha mais silenciosa de todas: a spec abandonada. O documento que ninguém atualiza não fica neutro, ele fica MENTINDO sobre o sistema

E aí a conta fica dobrada: você pagou o custo de escrever e ainda ficou com uma fonte de verdade falsa, que o agente vai ler com a maior confiança do mundo

A sensação de velocidade engana (e o estudo que mostra isso)

Tem um estudo randomizado da METR que eu acho difícil de esquecer

Eles mediram 16 devs open source experientes, em 246 tarefas reais, dentro de repositórios maduros que eles já conheciam (cerca de 5 anos de experiência média no projeto). Resultado: 19% mais lentos usando ferramentas de IA

A parte boa vem agora. Os mesmos devs estimaram depois que a IA os tinha deixado, em média, 20% mais rápidos

Percepção e cronômetro apontando em direções opostas, se liga nisso

Contexto obrigatório, porque número velho vira mentira fácil: as ferramentas usadas eram as disponíveis entre fevereiro e junho de 2025, predominantemente Cursor Pro com Claude 3.5 ou Claude 3.7 Sonnet, em chat, agent mode e autocomplete

E a própria METR classifica hoje aquele resultado como histórico, dizendo que ele não reflete necessariamente as ferramentas nem os fluxos de trabalho atuais. Em fevereiro de 2026 eles publicaram mudança no desenho do experimento de produtividade

Ou seja: não use isso pra dizer "IA deixa dev lento", isso seria zoado. Use pelo que o dado ainda ensina, que é a distância entre o que a gente SENTE e o que acontece

E essa parte eu já tinha visto de perto num assunto bem diferente. No vídeo abaixo eu falo sobre quando alguém pode se considerar programador júnior, e o ponto central é justamente esse: não existe prova nem parâmetro fixo, o critério é um conjunto de sinais práticos

O sinal mais forte que eu cito lá é conseguir pegar uma tarefa e entregar do início ao fim, testada e resolvida, sem depender dos colegas o tempo todo. E eu comento também que planejar antes de sair escrevendo código faz parte do avanço: colocar no papel, mapear as possibilidades, pensar no que pode dar errado

Juntando as duas coisas: a autoavaliação é o dado menos confiável que o dev tem em mãos, seja sobre o próprio nível, seja sobre a própria velocidade

É aí que a spec ganha uma função que ninguém anuncia: ela é um freio contra a pressa que PARECE produtividade. Aquele minuto em que você escreve o que pode dar errado é o minuto em que você não está gerando 300 linhas pra jogar fora depois

Veredito: escreva spec, mas escolha o tamanho dela

O veredito em uma linha: pro dev solo, a spec vale como ferramenta de pensamento e como briefing pro agente, não como documentação oficial pra manter em sincronia pra sempre

Muda tudo, inclusive o critério de sucesso. Spec boa não é a mais completa, é a que te fez pensar antes e deu contexto suficiente pro agente

Por perfil:

• Freelancer com escopo fechado: compensa, e talvez seja o caso mais óbvio. Requisito e critério de aceite escritos protegem você do escopo que cresce sozinho, e o documento serve pra duas coisas de uma vez
• Dev de produto próprio: compensa nas features grandes e nas que você vai delegar inteiras pro agente. No resto do dia a dia, cerimônia nenhuma
• Quem só está experimentando: não compensa formalizar. Fica no plano dentro da conversa e pronto

E tem cenário em que a resposta é NÃO, sem meio termo: mudança pequena, código exploratório e requisito instável. Nesses três, escrever spec é overhead puro

Conclusão

O critério de decisão cabe em uma frase: quanto maior a tarefa e quanto mais o agente vai executar sozinho, mais formal vale a pena ser, e quanto mais instável for o requisito, menos

O próximo passo é o mais barato possível: comece usando o plan mode do Claude Code, sem instalar nada, e veja se a dor de "faltou contexto" ainda aparece

Se aparecer, aí sim sobe de nível. Com o Spec Kit, a instalação persistente é assim:

uv tool install specify-cli

E pra usar de forma pontual, num ambiente temporário que é descartado ao fim do comando:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Os dois caminhos exigem o uv instalado, então esse é o erro comum aqui: rodar o comando sem ter o uv na máquina e achar que o problema é o Spec Kit

Se você preferir uma IDE inteira pensada pro fluxo, o caminho é o Kiro. Se preferir algo mais leve, é o OpenSpec

Escolhe um, testa numa feature de verdade e julga com o resultado na mão, não pela sensação… que a gente já viu que a sensação mente 😀

Até o próximo post!

Matheus Battisti