Feature grande demais para uma spec só? Como dividir em specs menores

Fala aí, beleza? Você sentou pra descrever uma feature na spec e ela foi crescendo sozinha

Requisito puxa requisito, caso de borda puxa caso de borda, e no fim o documento parece um mini PRD da empresa inteira

Aí você manda o agente implementar

Ele entrega uma parte bonita, improvisa outra, esquece uma regra que estava lá no meio do texto e você descobre isso só no teste

Se liga nisso: o problema quase nunca é a feature ser grande

O problema é a spec tentar ser ÚNICA

Neste post eu te mostro o critério de corte (por onde a linha passa de verdade), o contexto mínimo que cada fatia precisa carregar pra não depender das vizinhas e a ordem em que essas specs entram na implementação

Bora ver na prática? 🙂

O que você precisa antes de fatiar a spec

Antes de sair criando arquivo, junta três coisas

1) A feature descrita ponta a ponta, mesmo bagunçada

Pode ser um texto corrido, um monte de bullet solto, print de conversa com o cliente

O objetivo aqui não é organizar, é enxergar o tamanho real do bicho

2) Um agente de código que trabalhe com spec

Pode ser o Claude Code no modo de planejamento: Shift+Tab cicla entre os modos de permissão (default, acceptEdits e plan) e dá pra prefixar o prompt com /plan

No plan mode o Claude pesquisa e propõe as mudanças sem aplicar nada, o que é exatamente o que tu quer numa fase de recorte

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Podem ser também as ferramentas dedicadas a spec, tipo o GitHub Spec Kit ou o Kiro

3) O repositório onde as specs vão morar

O Kiro recomenda guardar as specs no próprio repo do projeto, junto do código que elas descrevem, mantendo a ligação entre requisito e implementação

Faz sentido: spec versionada fora do repo vira documento morto em três semanas

E agora o aviso mais importante da seção: o fatiamento é decisão humana antes de virar arquivo

Nem o Spec Kit nem o Kiro documentam um comando de "quebra essa spec em quatro pra mim"

A divisão acontece você criando specs novas, com a cabeça, e a ferramenta só materializa o que tu decidiu

Passo a passo: dividir uma feature grande em specs independentes

1. Escreva a feature inteira em uma folha só, de propósito. Sem organizar, sem numerar bonito, só despejar tudo que ela precisa fazer. É o raio-x: se você não consegue ler o escopo inteiro sem rolar a tela três vezes, já sabe que vem corte por aí… Erro comum deste passo: começar a estruturar antes de terminar de despejar, porque aí você fatia com base no que lembrou primeiro, não no todo
2. Liste os caminhos de uso e as regras, não as telas e tabelas. Aqui entra o SPIDR como catálogo de cortes: spike, path, interface, data, rules. Pergunta "quais caminhos o usuário percorre?" e "quais regras mudam o resultado?" em vez de "quais telas eu vou precisar?". Erro comum deste passo: listar entidades do banco e achar que aquilo é o escopo, quando é só o desenho técnico de uma parte dele
3. Corte na vertical. Fatia vertical é a que toca um pouco de cada camada e funciona ponta a ponta, mesmo cobrindo um caso só. Fatia horizontal separa UI, back-end e banco em itens distintos, e é justamente o que quebra tudo. Erro comum deste passo: criar "spec do banco", "spec da API" e "spec da tela". Divisão por camada fere as propriedades de independência e valor do INVEST: nenhum daqueles pedaços vale nada sozinho, e todos precisam esperar os outros pra existir
4. Aplique o teste do corte, fatia por fatia. A pergunta é uma só: o usuário se beneficiaria se APENAS esta fatia fosse entregue? Se a resposta for não, o pedaço não é uma fatia, é meia fatia, e você funde com a vizinha. Erro comum deste passo: aceitar um "sim, mas depois que a próxima estiver pronta". Esse "mas" é um não 😛
5. Defina o contexto mínimo que cada spec carrega. Três coisas escritas explicitamente: o contrato que ela assume pronto, o dado que ela cria pras outras e o que fica de fora. É isso que impede a spec 002 de precisar reler a 001 inteira pra fazer sentido. Erro comum deste passo: colar o projeto inteiro dentro de cada spec "pra garantir"
6. Ordene a implementação por dependência de dado e por risco. A fatia que CRIA o dado vem antes da que consome, sempre. E quando a viabilidade técnica é dúvida, o spike do SPIDR vai na frente de tudo, porque o resultado dele pode mudar o desenho das outras fatias. Erro comum deste passo: ordenar por camada de novo, de trás pra frente, começando pelo "vamos deixar o banco pronto primeiro"

Sobre o passo 5, vale uma parada pra explicar o PORQUÊ

A Anthropic trata contexto como recurso finito, com retorno marginal decrescente: o modelo tem um "orçamento de atenção" que vai sendo consumido conforme processa grandes volumes, e a curadoria do que entra é um trabalho iterativo

Ou seja: enfiar tudo na spec não é generosidade com o agente, é gastar o orçamento dele com coisa que não é do problema atual

A capacidade de achar agulha no palheiro melhorou muito, se liga: na variante 8-needle de 1M do MRCR v2, o Claude Opus 4.6 marca 76% contra 18,5% do Sonnet 4.5

Mas "consegue recuperar" é diferente de "vale a pena fazer ele procurar"

Spec curta continua ganhando, e essa mesma lógica vale quando você precisa dividir uma tarefa grande no Claude Code sem perder o fio no meio

Seguindo:

7. Materialize uma spec por fatia, em diretório próprio. No Spec Kit a numeração varre as specs existentes e gera a próxima (001, 002, 003…), criando a estrutura specs/<branch-name>/ com os documentos daquela feature. No Kiro, uma spec são três arquivos gravados em .kiro/specs/: requirements.md (histórias de usuário e critérios de aceite), design.md (arquitetura técnica) e tasks.md (plano de implementação em tarefas rastreáveis). Erro comum deste passo: pendurar a fatia nova como apêndice da spec antiga
8. Confira cada spec ANTES de quebrar em tarefas. No Spec Kit, /speckit.checklist gera uma checklist de qualidade pra ver se a spec está completa, clara e consistente, descrita na doc como "testes unitários dos seus requisitos". Já /speckit.analyze compara spec.md, plan.md e tasks.md e aponta conflito, lacuna e ambiguidade. Erro comum deste passo: rodar o analyze e esperar conserto. Ele é read-only: aponta o problema, quem corrige é você

Se você for de Spec Kit, o bootstrap do projeto sai pela CLI Python chamada Specify:

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

E o fluxo de comandos que o agente roda passo a passo é esta sequência: constitution, specify, clarify, plan, checklist, tasks, analyze, implement e converge

Repara que checklist e analyze estão ali no meio de propósito, antes e depois das tasks

O Spec Kit tem uma página de integrações suportadas com os agentes de código compatíveis, e o Claude Code está entre eles

Três recortes que quase sempre funcionam

Feature cheia de regra de negócio

É o clássico: cálculo de comissão, desconto progressivo, elegibilidade, aquelas coisas com dez exceções

Aqui o corte é pelo rules do SPIDR

Primeira spec: o caso feliz funcionando ponta a ponta, do clique até o dado gravado, com UMA regra só

As exceções viram specs seguintes, uma por bloco de regra

Cada uma passa no teste do corte sozinha, porque o usuário já consegue usar o caminho principal enquanto as bordas não chegaram

Feature com dúvida técnica no meio

Aquela em que você não sabe se a integração aguenta, se o formato bate, se dá pra fazer no tempo do request

Corte pelo spike: primeiro a fatia que responde a dúvida, depois o resto

No Kiro dá pra encaixar isso no fluxo: as Feature Specs suportam dois pontos de partida, Requirements-First e Design-First, e o Design-First pode ser usado justamente pra validar viabilidade técnica antes de abrir uma spec Requirements-First completa

O Kiro também tem tipos de spec além da feature nova: spec de correção de bug e spec design-first pra construir sobre aplicação existente

E se você não quer os portões de aprovação entre as fases, tem o Quick Spec, que entrega os mesmos artefatos (requirements, design e tasks) sem os approval gates e faz perguntas sobre escopo, restrições e casos de borda antes de escrever

Feature que atravessa projetos de um monorepo

Essa dói porque parece uma feature só, mas mora em dois ou três lugares

O Spec Kit permite vários projetos independentes sob a mesma raiz, cada um com seu próprio conjunto de specs

Então o corte natural é por projeto: uma spec por projeto tocado, cada uma declarando o contrato que assume pronto do vizinho

O que NÃO vale é fazer uma spec gigante na raiz descrevendo o mundo, e depois torcer pro agente adivinhar onde cada parte cai

Sinais de que a spec ficou grande demais

Os sintomas são bem reconhecíveis, olha só

A correção recorrente é sempre a mesma: cortar mais uma fatia vertical e mover o excedente pra uma NOVA spec, em um novo diretório

No Spec Kit isso é explícito: mudança de acompanhamento substancial ou feature nova vira spec nova, cada uma ocupando seu próprio diretório numerado sob specs/

Não é apêndice na spec antiga, beleza?

E pra prevenir, três hábitos que custam pouco:

• rodar a checklist ANTES de gerar as tasks, não depois
• tratar toda mudança substancial como spec nova
• manter a spec curta porque o orçamento de atenção do modelo é finito, ponto

Uma dica de bastidor: quando o agente propõe um plano no Claude Code, você não precisa aceitar como veio

Ctrl+G abre o plano proposto no editor de texto padrão pra você editar antes de aprovar

É o momento perfeito pra riscar o que é de outra fatia 😀

Depois de aprovar, a sessão sai do plan mode e vai pro modo de permissão da opção escolhida, e o Claude começa a editar

Quer voltar a planejar? Shift+Tab de novo e tu está no plan mode

Pra começar do zero com feature grande e organização de trabalho no Claude Code, este vídeo do canal mostra o GStack transformando o Claude Code numa equipe de especialistas:

Comece pela fatia que entrega valor sozinha

Se você guardar uma coisa só deste post, guarda o critério: vertical, com valor demonstrável, aprovado no teste do corte

O resto (numeração, diretório, comando, ferramenta) é consequência

O próximo passo é bem concreto

Pega a feature que está travada hoje

Lista os caminhos de uso e as regras dela, sem olhar pra telas nem pra tabelas

Corta a primeira fatia que sobrevive à pergunta "o usuário se beneficiaria se só isso fosse entregue?"

Abre SÓ ela como spec, roda a checklist, quebra em tarefas e implementa

O resto fica anotado num rascunho, esperando virar spec própria depois

É menos documento, mais entrega, e um agente que não se perde no meio do caminho

Bora fatiar? até o próximo post! 🙂