Spec-Driven Development com Claude Code: o workflow na prática

O Claude Code é capaz e não guarda estado. Sem um sistema, essa combinação é perigosa. Spec-driven development resolve o segundo problema para você usar o primeiro com segurança.

Este é o complemento prático de o que é spec-driven development: o como, especificamente no Claude Code. Nunca ouviu falar de SDD? Comece por lá. Já entendeu por que specs importam? É aqui.

O método dá ao Claude Code três coisas que ele não consegue ter sozinho: uma memória que sobrevive à sessão, um gate de aprovação que impede a implementação antes da hora e um review estruturado que confere o resultado contra o que foi de fato aprovado. Cada seção abaixo adiciona uma peça desse sistema.

A Anthropic já mandou você planejar primeiro

Antes de qualquer framework, leia o manual de quem fez o modelo. As boas práticas do Claude Code publicadas pela Anthropic descrevem um loop de quatro passos: explorar, planejar, implementar, commitar. Existe um plan mode dedicado cuja única função é impedir o agente de escrever código enquanto pensa. O motivo declarado é direto: “deixar o Claude pular direto para o código pode produzir código que resolve o problema errado.”

Plan mode não é um empurrãozinho conceitual. É uma funcionalidade real do produto. No terminal, Shift+Tab entra em plan mode. Nele, o Claude lê arquivos e responde perguntas sem alterar nada. Quando você tem um plano que vale revisar, Ctrl+G abre o plano no seu editor para você editar direto antes de o Claude seguir. Depois é sair do plan mode e deixar ele implementar.

A Anthropic é igualmente específica sobre o que uma boa spec contém: “as specs mais úteis são autocontidas: nomeiam os arquivos e interfaces envolvidos, dizem o que está fora do escopo e terminam com um passo de verificação ponta a ponta que prova que a feature funciona.” Essa frase é o briefing de design de tudo que vem abaixo.

A técnica da entrevista para spec

A Anthropic publica o prompt que transforma uma ideia em spec antes de existir uma linha de código. Este é o template deles:

I want to build [brief description]. Interview me in detail using the
AskUserQuestion tool. Ask about technical implementation, UI/UX, edge
cases, concerns, and tradeoffs. Don't ask obvious questions, dig into
the hard parts I might not have considered. Keep interviewing until
we've covered everything, then write a complete spec to SPEC.md.

Rode isso numa sessão limpa. O Claude te pressiona em edge cases que você ainda não considerou. Quando ele terminar, abra outra sessão limpa para implementar. O contexto zerado mantém a implementação focada só na spec, e não na conversa que a produziu.

Essa é a fase de PRD de um workflow de SDD estruturado, formalizada. A técnica é da Anthropic. O sistema em volta dela é o método.

Quando pular o plano

A Anthropic traça a linha sem rodeio: “se você consegue descrever o diff em uma frase, pule o plano.” Uma variável renomeada, uma linha de log, um typo: nada disso precisa de spec. A cerimônia existe para trabalho que dura mais que uma sentada, atravessa várias sessões ou mexe em arquitetura e corretude de verdade. Todo o resto: prompt e vai.

CLAUDE.md é a camada um, não o sistema inteiro

O Claude Code lê o CLAUDE.md no início de toda conversa. A Anthropic o chama de “um arquivo especial que o Claude lê no início de toda conversa” e dá uma disciplina clara para mantê-lo útil: “seja conciso. Para cada linha, pergunte: remover isso faria o Claude errar? Se não, corte. Arquivos CLAUDE.md inchados fazem o Claude ignorar as suas instruções de verdade.”

Essa última frase é a falha em que a maioria dos devs cai. Eles enchem o CLAUDE.md de convenções de código, preferências de ferramenta, normas do time e contexto do projeto até chegar a 400 linhas. O Claude lê o primeiro terço e pula o resto. As convenções que mais importam são as que se perdem.

A solução não é organizar melhor o CLAUDE.md. É tirar a maior parte do conteúdo de lá e levar para um sistema de contexto com três camadas, cada uma com um trabalho só.

O sistema de contexto em três camadas

Um projeto que dura mais que uma sessão precisa de três camadas de contexto, cada uma com um tempo de vida e uma função diferentes.

Três camadas, três funções

1. 01

   CLAUDE.md

   Carregado em toda sessão. Contém só o que precisa carregar antes de o agente fazer qualquer coisa: ponteiros para as outras camadas, um lembrete de uma linha para checar o .status antes de implementar e as regras de comportamento que valem para toda conversa.

   Mantenha abaixo de 30 linhas.
   Se remover não causa erro, corte.

   +
2. 02

   steering/

   Contexto estável do produto, que quase nunca muda. O que o produto é e o que não é, a stack com os motivos, convenções de código além do lint e as regras de arquitetura inegociáveis. O CLAUDE.md aponta para cá; o agente lê o que precisa.

   Muda quando você toma uma decisão de arquitetura deliberada.
   Nunca muda por causa de uma feature.

   +
3. 03

   specs/NNN-feature/

   Specs por feature que evoluem ao longo do pipeline: requisitos, design, tasks e o arquivo .status que libera a implementação. O único lugar onde trabalho de implementação é autorizado.

   Cada arquivo avança uma fase.
   .status é o único gate. Arquivo existir não é aprovação.

O CLAUDE.md é um conjunto curto de ponteiros: “O contexto do produto fica em steering/. As specs de feature ficam em specs/NNN-name/. Antes de implementar qualquer coisa, leia o arquivo .status daquela feature.” Essa estrutura de ponteiros faz o Claude ler os arquivos certos na hora certa, e não tudo de uma vez. É ela também que mantém o CLAUDE.md curto: a maior parte do conteúdo tem um lugar melhor.

O diretório completo

Estrutura de projeto para SDD com Claude Code

• CLAUDE.md// ponto de entrada, carregado em toda sessão, roteia o agente para todo o contexto abaixo
• steering/estável
  • product.md// o que é, quem usa, o que explicitamente não é
  • tech-stack.md// stack, versões, bibliotecas e o motivo de cada uma
  • conventions.md// estrutura de API, formato de erros, padrões de auth, regras de nomes
  • principles.md// regras de arquitetura que sustentam o sistema, as inegociáveis
• specs/
  • 001-user-auth/feature
    • requirements.md// comportamentos no formato EARS, critérios de aceite
    • design.md// arquitetura, modelos de dados, contratos de API
    • tasks.md// unidades implementáveis, 2-4h cada, testáveis de forma independente
    • .status// tasks:approved é o único sinal verde para o EXEC
• .claude/
  • commands/slash commands// /spec, /tasks, /review para cada etapa do pipeline
• agents/
  • architect.md// projeta, nunca implementa
  • implementer.md// implementa só depois de tasks:approved, PARA diante de ambiguidade
  • reviewer.md// revisa só contra a spec, não contra preferências

A profundidade é proposital. O CLAUDE.md é um arquivo de roteamento. A pasta steering guarda a memória do produto. A pasta de spec guarda a feature atual. A pasta agents guarda os prompts dos subagents. Você monta essa estrutura uma vez e trabalha a partir dela em toda feature.

O toolkit que transforma isso em slash commands é o meu @felipefontoura/pi-sdd-kit, que implementa a mesma estrutura para o Pi coding agent. O método funciona sem kit nenhum, com markdown puro e disciplina consistente. A estrutura é o que importa; o tooling é opcional.

Steering: a memória que sobrevive à sessão

Os quatro arquivos em steering/ guardam o contexto de que o agente precisa para tomar boas decisões sem você reexplicar tudo a cada sessão.

product.md é uma resposta de duas páginas para o que o produto faz, quem usa e o que ele deliberadamente não faz. Um agente que não sabe que “isto é um backend de pagamentos para lojistas cripto, não um app de consumo” vai derivar para padrões de consumo, adicionar features que ninguém pediu e otimizar as coisas erradas. O escopo negativo importa tanto quanto o positivo.

tech-stack.md diz a stack, as versões e por que cada escolha grande foi feita. Não é uma lista de dependências: é uma justificativa. “PostgreSQL porque registros de pagamento precisam de garantias ACID” é a frase que impede o agente de sugerir SQLite quando você adicionar um módulo novo daqui a três sessões. O motivo é o que torna o arquivo útil entre sessões. Sem ele, o arquivo é um changelog que ninguém lê.

conventions.md vai além das regras de lint. Ele registra padrões: como as rotas de API são estruturadas, qual o formato dos erros, como a autenticação é aplicada na borda. O conhecimento tácito que mora na cabeça dos devs experientes, até alguém escrever.

principles.md é o arquivo mais curto e o mais difícil de escrever bem. Regras de arquitetura que sustentam o sistema, em frases declarativas. Na fintech: “Toda conta com dinheiro é aritmética de inteiros, nunca float.” “Nenhum acesso direto ao banco fora da camada de repositório.” “Se você não tem certeza se algo está no escopo, não está.” Essas restrições evitam erros de categoria antes de o agente gerar uma única linha de código.

Esses arquivos mudam pouco. Quando mudam, é porque você tomou uma decisão de arquitetura deliberada. Escrever em steering/ é como essa decisão vira contexto permanente do agente em todas as sessões futuras.

O pipeline com gates

Toda feature passa por uma sequência definida. IDEA e PLAN são opcionais para trabalho pequeno ou bem conhecido. A sequência central para qualquer feature de verdade vai do PRD ao REVIEW:

Pipeline de SDD no Claude Code

Entrada

Um comportamento a construir: não uma linha de código, algo que o sistema precisa fazer

↓

1. PRDDocumento de requisitos de produto

   Descrição em linguagem de negócio: o que o sistema precisa fazer, quem usa, o que está explicitamente fora do escopo. Sem código. É aqui que entra a técnica da entrevista para spec.

   ↓
2. SPECEspecificação técnica

   Requisitos no formato EARS, decisões de arquitetura, modelos de dados, contratos de API. Gate humano antes de seguir: o .status precisa dizer requirements:approved, depois design:approved.

   ↓
3. TASKSDecomposição em tasks

   Unidades implementáveis de 2-4 horas cada, testáveis de forma independente, com dependências explícitas. O Implementation Readiness Check confirma que todo requisito mapeia para pelo menos uma task. Gate humano: o .status precisa dizer tasks:approved.

   ↓
4. EXECImplementação

   O agente lê o tasks.md e implementa task por task. Só começa depois que o .status diz tasks:approved. Levanta toda ambiguidade antes de agir.

   ↓
5. REVIEWRelatório de verificação

   Cada task verificada: Claim, Command, Exit code, Verdict PASS ou FAIL. Um FAIL quer dizer que a spec estava errada: corrija o documento e gere de novo. Nunca remende o código para esconder um erro da spec.

↓

Saída

Feature implementada com uma trilha de auditoria rastreável do requisito ao resultado da verificação

O gate entre TASKS e EXEC é garantido por um único arquivo .status dentro de cada pasta de feature. Uma linha. O agente lê esse arquivo antes de cada passo de implementação. O estado dele é o único sinal de aprovação que o agente respeita.

Parece óbvio até você ver um agente ansioso sair correndo de uma spec pronta direto para a implementação porque os arquivos existem. O gate impede isso. Você atualiza o .status na mão, depois de ler e aprovar cada fase. Esse passo manual é a aprovação humana em torno da qual o método inteiro foi construído. É também o hábito mais difícil de manter sob pressão de prazo, que é justamente quando ele mais importa.

Três subagents especializados

O padrão mais eficaz é dividir o trabalho entre três subagents estreitos, em vez de pedir para um agente fazer tudo. Cada um tem uma função e uma restrição.

Os três subagents

1. 01

   Architect

   Lê o PRD e todo o contexto de steering. Produz o requirements.md e o design.md: modelos de dados, contratos de API, escolhas de tecnologia com justificativas explícitas e um mapa de rastreabilidade de cada requisito para uma decisão de design.

   Restrição central: nunca escrever código de implementação.
   Se pedirem para implementar, esclareça o escopo.

   +
2. 02

   Implementer

   Lê o tasks.md e o .status (precisa ser tasks:approved). Implementa task por task e escreve os testes junto com o código. Os requisitos EARS da spec são os critérios de aceite, não a interpretação que o Implementer faz deles.

   Restrição central: PARE se encontrar ambiguidade.
   Não presuma. Não deduza. Pergunte.

   +
3. 03

   Reviewer

   Lê o requirements.md, o design.md, o tasks.md e o código gerado inteiro. Revisa só contra a spec: não contra boas práticas genéricas, não contra preferência de estilo. Reporta lacunas, não opiniões.

   Restrição central: revise contra a spec, não contra suas preferências.
   Não adicione requisitos. Só aponte lacunas.

O padrão do Reviewer bate direto com a recomendação da própria Anthropic para execuções autônomas: “antes de considerar uma task pronta, peça para um subagent revisar o diff num contexto limpo e reportar lacunas.” O raciocínio deles é preciso: um reviewer rodando num contexto de subagent limpo vê só o diff e os critérios que você passa, e não o raciocínio que produziu a mudança. Ele avalia o resultado pelo que ele é. O subagent Reviewer aqui é essa recomendação tornada explícita, com uma restrição que impede que ele vire uma segunda sessão de design.

A separação entre Architect e Implementer resolve uma falha específica. Um agente que projeta e implementa tem incentivo para projetar algo que ele já sabe construir. O Architect não pode escrever código, então as decisões de design precisam se sustentar sozinhas. A restrição também torna o documento de design honesto: ele foi escrito por algo que não tem como pegar atalho nas próprias recomendações.

GitHub Spec Kit vs pi-sdd-kit: o que cada um entrega

O Spec Kit do GitHub dá ao seu agente um pipeline de skills para spec-driven development: uma constitution uma vez por projeto, depois /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement e /speckit-converge por feature. Ele codifica o instinto certo, escrever a spec antes do código, e roda no Claude Code, instalando as skills em .claude/skills. É a escolha certa quando a sua equipe usa vários agentes e quer um padrão único. Cubro em detalhe no guia do GitHub Spec Kit. A comparação mais ampla, com OpenSpec e Superpowers, está em OpenSpec vs. Spec Kit vs. Superpowers.

O que cada abordagem entrega

Escopos diferentes, não ferramentas concorrentes. O Spec Kit é um padrão de workflow que roda em vários agentes. A estrutura em três camadas daqui é um sistema de memória e gates para o Claude Code.

Recurso	GitHub Spec Kit	Estrutura do pi-sdd-kit
Workflow spec-first	Sim, do specify ao converge	Sim, via pipeline do PRD ao TASKS
Memória estável do produto entre sessões	Em parte: constitution.md guarda os princípios	Sim, pasta steering/ com 4 arquivos de contexto
Gate de aprovação legível por máquina	Não: --require-spec só confere se o arquivo existe	Sim, arquivo .status com token explícito
Subagents especializados com restrições	Não vem pronto	Sim, Architect / Implementer / Reviewer
Suporte a agentes	42 integrações, Claude Code incluído	O método funciona com qualquer agente

Se você está construindo um protótipo numa tarde, nenhum dos dois é necessário. Uma spec em markdown e o plan mode bastam para colher o benefício. A estrutura ganha valor à medida que sessões, features e pessoas no time se multiplicam.

Uma feature do PRD ao REVIEW

Aqui vai uma feature concreta passando pelo pipeline: PATCH /users/me para um usuário autenticado atualizar o nome de exibição e o fuso horário. É uma versão simplificada de um endpoint real da fintech.

PRD em cinco minutos. A feature em linguagem de negócio: “Usuários autenticados precisam atualizar o nome de exibição (2-64 caracteres) e o fuso horário (string IANA, validada no servidor). Podem atualizar um ou os dois campos numa única requisição. Nenhum outro campo do perfil está no escopo deste endpoint.”

O Architect lê o PRD e o steering/ (especificamente tech-stack.md e principles.md) e produz o requirements.md no formato EARS:

WHEN an authenticated user sends PATCH /users/me,
THE SYSTEM SHALL validate all provided fields before persisting any change.

IF displayName is provided AND length is less than 2 OR greater than 64,
THE SYSTEM SHALL return 400 with message "displayName must be 2 to 64 characters".

IF timezone is provided AND is not a valid IANA timezone identifier,
THE SYSTEM SHALL return 400 with message "Invalid timezone identifier".

THE SYSTEM SHALL NOT allow unauthenticated requests to this endpoint.

Você revisa. Os requisitos batem com o PRD. Nenhuma ambiguidade. Você atualiza o .status para requirements:approved.

O Architect produz o design.md: route handler, camada de validação, método do repositório, formato da resposta e uma nota explícita de que a validação de fuso horário usa a base IANA tz do serviço de auth existente. Você revisa. O design mapeia direitinho para cada requisito e segue o steering/conventions.md. Você atualiza o .status para design:approved.

A decomposição gera quatro unidades no tasks.md:

1. Adicionar a rota PATCH /users/me com guard de autenticação. Testável: a rota retorna 401 sem um token válido.
2. Implementar a validação do displayName. Testável: 400 com menos de 2 ou mais de 64 caracteres.
3. Implementar a validação do fuso horário contra a base IANA. Testável: 400 com uma string de fuso desconhecida.
4. Implementar o método de update no repositório. Testável: persiste as mudanças e retorna o objeto do usuário atualizado.

O Implementation Readiness Check confirma que todo requisito mapeia para pelo menos uma task, que toda task é testável de forma independente e que não há dependências não declaradas. O .status vira tasks:approved.

O Implementer lê o tasks.md, encontra tasks:approved e segue a lista em ordem: testes junto, não depois. No meio da task 3, ele encontra uma ambiguidade: qual status HTTP se a conta do usuário estiver desativada? Ele PARA e pergunta em vez de chutar. Você responde: 403. Essa decisão volta para o requirements.md antes de a implementação continuar.

Depois do EXEC, o Reviewer roda o relatório de verificação:

Relatório de verificação: PATCH /users/me

Todas as linhas deram PASS. Um FAIL significa corrigir a spec primeiro e gerar de novo. Nunca remende o código para encobrir um erro da spec.

Claim	Command	Exit code	Verdict
401 sem token de auth	curl -X PATCH /users/me	0	PASS
400 com displayName curto demais	PATCH /users/me displayName=x (1 caractere)	0	PASS
400 com fuso horário inválido	PATCH /users/me timezone=badzone	0	PASS
403 com conta desativada	PATCH /users/me X-Test-Inactive: 1	0	PASS
200 com update válido	PATCH /users/me displayName=Felipe	0	PASS

Todas as linhas deram PASS. Se alguma desse FAIL, a correção começaria na spec: o requisito estava errado (atualize o requirements.md) ou a implementação deixou algo passar (corrija o tasks.md e gere de novo). A spec é a fonte da verdade. Remendar o código para uma linha da verificação passar e deixar a spec como estava é o jeito silencioso de matar o método.

Esse loop (do PRD ao REVIEW) é o mesmo para toda feature. A disciplina se acumula: depois de dez features, os steering files estão enxutos, o agente quase nunca para por ambiguidade e o Implementation Readiness Check leva dois minutos porque os padrões já estão estabelecidos. O atrito fica todo no começo.

Uma falha real que o gate pegou

Durante a construção da fintech, uma das primeiras specs de criação de cobrança passou pelo PRD e chegou ao gate na revisão de design. Os requisitos EARS estavam corretos. Mas o design.md que o Architect produziu não tinha a restrição de idempotência: o índice UNIQUE(merchant_id, idempotency_key) que garante cobrança exatamente uma vez no nível do banco.

O design era tecnicamente coerente. E estava errado. O gate obrigou uma revisão do design antes de o agente poder implementar. Peguei a restrição faltando nessa revisão, e não num incidente em produção.

Um agente ansioso sem o gate teria implementado a partir do design, o índice não existiria e o primeiro retry sob carga teria gerado uma cobrança duplicada. Num sistema movimentando transações reais em reais, isso não é cenário de teste. O gate pegou o problema enquanto ainda era um arquivo de texto, e não um erro de cobrança. Erro pego no design custa minutos. Erro pego em produção, num sistema de pagamentos, custa semanas e um pedido de desculpas.

É também por isso que o gate é manual. Um gate automático poderia avançar com “o design.md está completo.” O gate humano obriga uma leitura, e ler é o único jeito de pegar o que um documento tecnicamente válido, mas errado, contém.

Como o CLAUDE.md cresce errado, e como podar

O padrão é previsível. Uma sessão ruim gera uma regra. A próxima sessão ruim gera outra. Três meses depois, o CLAUDE.md tem 300 linhas e o agente ignora metade. A descrição da falha, nas palavras da Anthropic: “se o Claude continua fazendo algo que você não quer apesar de haver uma regra contra isso, o arquivo provavelmente está longo demais e a regra está se perdendo.”

Checklist de poda do CLAUDE.md

• ✓Obrigatório:
  Remover isso faria o Claude errar?Se não, corte. É o teste da própria Anthropic, ao pé da letra. Aplique em toda linha, não só nas suspeitas.
• ✓Obrigatório:
  O Claude já faz isso certo sem a instrução?Então a instrução é ruído. Apague ou transforme num hook para garantir de forma determinística.
• ✓Obrigatório:
  Isso é conhecimento de domínio ou um passo de workflow?Leve para um steering file ou para um arquivo em .claude/skills/. O CLAUDE.md não é base de conhecimento; é configuração de comportamento.
• ✓Obrigatório:
  O Claude continua ignorando essa regra mesmo com a instrução?O arquivo está longo demais e a regra está enterrada. Pode primeiro, depois reescreva. Um arquivo curto com três regras ganha de um longo com trinta.
• ✓Obrigatório:
  É uma regra de comportamento não óbvia que vale para toda sessão?Essa fica. O CLAUDE.md serve para instruções de comportamento no nível da sessão que não têm outro lugar.

O formato certo do CLAUDE.md num projeto que usa esse sistema: uma descrição curta da estrutura em três camadas, um ponteiro para steering/ com o contexto do produto, um ponteiro para specs/ com o trabalho de feature, a instrução de checar o .status antes de implementar e as regras de comportamento que valem para tudo. Menos de 30 linhas. Todo o resto tem outro lugar.

FAQ

O Claude Code tem spec-driven development embutido?+

O Claude Code tem plan mode embutido, e as boas práticas da Anthropic descrevem o loop de quatro passos (explorar, planejar, implementar, commitar). Essa é a base do SDD aplicado ao Claude Code.

O que o Claude Code não tem embutido é o sistema de contexto em três camadas, o gate de .status ou os subagents especializados. Essa é a estrutura que você aplica por cima, com markdown puro e disciplina ou com uma ferramenta como o pi-sdd-kit.

O que é o plan mode no Claude Code?+

Plan mode é uma funcionalidade nativa do Claude Code que impede o agente de escrever código enquanto explora e planeja. Aperte Shift+Tab no terminal para entrar. Em plan mode, o Claude lê arquivos e responde perguntas sem alterar nada.

Aperte Ctrl+G para abrir o plano atual no seu editor e editar direto. Depois saia do plan mode e deixe o Claude implementar. A Anthropic recomenda usar plan mode para qualquer coisa além de uma mudança trivial, e pular quando o diff cabe numa frase.

O que é um steering file?+

Um steering file é um documento de contexto persistente que o agente lê em toda sessão através dos ponteiros no CLAUDE.md. Os quatro principais (product.md, tech-stack.md, conventions.md, principles.md) respondem às perguntas em que o agente chutaria: o que é o produto, em que stack ele roda, como o código é escrito e quais regras de arquitetura são inegociáveis.

Eles ficam em steering/ e mudam pouco. Quando mudam, é porque você tomou uma decisão de arquitetura deliberada. Escrever é como essa decisão vira contexto permanente do agente em todas as sessões futuras.

Spec Kit vs Claude Code: qual workflow ganha?+

O GitHub Spec Kit e o Claude Code não são ferramentas concorrentes. O Spec Kit é um kit de workflow que roda em vários agentes, incluindo o Claude Code: ele instala skills (speckit-specify, speckit-plan, speckit-tasks e as demais) que codificam o spec-driven development.

O que a abordagem do pi-sdd-kit adiciona por cima é o steering como memória durável mais ampla que uma constitution, o .status como gate de aprovação legível por máquina e subagents com restrições explícitas. Escopos diferentes, não uma disputa: dá para rodar o pipeline do Spec Kit e manter um gate de .status.

Por que o SDD usa um gate de .status em vez de só revisar a spec?+

Porque 'eu revisei' é um estado mental, não um sinal que o agente consiga ler. O arquivo .status dá ao agente um token explícito, legível por máquina, que ele precisa checar antes de avançar para a próxima fase.

A regra dura (arquivo existir não significa aprovação) existe porque, para um agente varrendo o diretório, um arquivo completo e um arquivo aprovado são idênticos. O token de status elimina essa ambiguidade por completo.

O que é o pi-sdd-kit e eu preciso dele?+

O pi-sdd-kit é o meu pacote npm que codifica o workflow de SDD como slash commands para o Pi coding agent: /skill:sdd-prd, /skill:sdd-spec, /skill:sdd-tasks, /skill:sdd-exec, /skill:sdd-review e a convenção do gate de .status. Publicado como @felipefontoura/pi-sdd-kit.

Você não precisa dele. A pasta steering/, a estrutura specs/NNN-feature/ e o gate de .status funcionam com qualquer agente e qualquer editor usando markdown puro. O kit tira cerimônia e deixa o workflow consistente entre projetos. É infraestrutura, não pré-requisito.

O que é o Implementation Readiness Check?+

Uma validação antes do EXEC de que o tasks.md está mesmo pronto para implementação: todo requisito EARS mapeia para pelo menos uma task, toda task tem critérios de aceite explícitos, toda task é testável de forma independente e nenhuma task tem dependência não declarada de outra.

Ele roda antes de tasks:approved entrar no .status. A função dele é separar 'acho que estamos prontos' de 'a spec está completa o bastante para implementar sem ambiguidade.' São coisas diferentes, e pegar essa diferença aqui sai mais barato do que durante a implementação.

Qual a diferença disso para usar um CLAUDE.md cheio de instruções?+

O CLAUDE.md é uma camada: o ponto de entrada que carrega em toda sessão. O SDD adiciona mais duas: steering/ para o contexto estável do produto, que quase nunca muda, e specs/NNN-feature/ para as specs por feature que evoluem ao longo do pipeline.

O CLAUDE.md diz ao agente como se comportar. O steering diz o que ele está construindo e por que aquelas decisões foram tomadas. A spec da feature diz o que construir agora. As três sustentam o sistema. Cada uma falha sem as outras duas.

Para onde ir agora

SDD com Claude Code é uma estrutura que você aplica na ferramenta que já tem. O problema de memória é real, e o sistema de contexto em três camadas (CLAUDE.md, steering, specs) resolve sem adicionar cerimônia que te atrasa.

O método está explicado por completo em o que é spec-driven development. Para ver ele rodando em escala de produção (13 apps, dinheiro de verdade, 70 dias), o estudo de caso tem as provas. Para os documentos de spec em si (como escrever requisitos no formato EARS, o que uma seção de design completa contém, como decompor tasks), o texto complementar é como escrever uma spec que uma IA consegue construir.

O kit está em @felipefontoura/pi-sdd-kit. Markdown puro e gates de aprovação consistentes bastam para começar sem ele.

O código agora se escreve sozinho. As specs, não. Esse é o trabalho.