Depois de alguns meses trabalhando com o Hélio, ficou claro um padrão: as tarefas mais complexas — aquelas que envolviam várias etapas, várias referências, mudanças em mais de um processo — saíam bem quando tinham um documento de problema e objetivo antes de começar. E saíam mal quando não tinham.
Na engenharia de software, isso tem nome: Spec-Driven Design. Eu adapto para o contexto do trabalho cotidiano com IA e chamo de Estrutura Conduzida por Especificação.
O que é uma spec
Uma especificação é um arquivo Markdown curto que responde a duas perguntas antes do trabalho começar:
Qual é o problema? — o que está errado, falta, ou precisa mudar. Qual é o objetivo? — como o trabalho termina, o que ele entrega.
Não é documentação técnica. Não é um plano detalhado. É uma âncora que orienta o Claude — e você — antes de qualquer conversa de execução.
Quando uma spec vale a pena
O critério não é o tipo de trabalho. É a maturidade do ambiente.
Uma spec sem processos documentados vira escrita solta sem ancoragem. Você escreve o problema e o objetivo, pede ao Claude para executar, e ele não tem referência concreta sobre os processos que a spec afeta. O resultado é genérico.
Se você ainda não tem pelo menos um processo documentado no ambiente, volte ao artigo anterior sobre documentar o primeiro processo. A spec assume que esse contexto já existe.
Com o ambiente organizado, vale spec para qualquer trabalho que envolva:
- mudança em um processo existente
- criação de algo novo que vai conviver com o que já existe
- decisão que precisa ser rastreável depois
Onde a spec mora
Cada spec vive dentro da pasta da tarefa que ela afeta, em uma subpasta specs/:
O nome do arquivo segue o padrão AAAA-MM-DD-nome-slug.md. A data no início facilita ordenar pelo histórico.
O frontmatter mínimo
Três campos no topo do arquivo — isso é tudo que você precisa para começar:
---
title: Fechamento mensal automatizado
status: rascunho
created: 2026-08-04
---title descreve o que a spec resolve. status começa como rascunho e vai avançando conforme o trabalho progride. created registra quando foi aberta. Outros campos entram se o uso pedir — não antes.
O ciclo iterativo
Você não escreve a spec do zero e envia para execução. Ela é construída em par com o Claude, em cinco etapas:
1. Você escreve uma frase sobre o que quer resolver.
2. O Claude responde com 10 a 20 perguntas sobre o problema e o objetivo.
3. Você responde diretamente no arquivo da spec.
4. O Claude integra as respostas no corpo do documento.
5. Você revisa com <nota> nos pontos que precisam de ajuste. Repete até fechar.
O Hélio e eu usamos exatamente essa lógica quando montamos a spec para o controle de runway — Alfredo descreveu o problema em uma frase, o Claude devolveu perguntas, o Hélio respondeu, e fomos ajustando até o documento refletir o que ele realmente precisava.
Referenciando outros processos
Quando a spec afeta um processo que existe em outra pasta, a referência vai no texto, com o caminho em backticks:
Essa spec altera o processo em `./Financeiro/CLAUDE.md`.
O ajuste é na etapa de geração do painel — ela precisa
considerar IOF na fatura internacional.Sem XML tag especial, sem link Markdown. Caminho em backtick é suficiente para o Claude entender que precisa ler aquele arquivo como referência.
O que a spec não é
Spec não é documentação do que foi feito — é planejamento do que vai ser feito. Depois da execução, as decisões tomadas voltam para o CLAUDE.md do processo afetado, não para a spec.
A spec é descartável depois de executada. O que fica é o processo atualizado.
Estou ministrando mentorias para profissionais de diversas áreas que estão começando nessa ideia. Se não quer percorrer esse caminho sozinho, é só me chamar.