BriarForge/dev-grill-spec-driven

Grill, depois desenvolvimento orientado por especificação

Dois fluxos de trabalho, executados consecutivamente, com uma transição entre eles:

1. Grill (Matt Pocock, grill-me → to-spec): entreviste o usuário como uma árvore de design, rodada por rodada, até que nada seja assumido silenciosamente. Em seguida, sintetize o entendimento acordado em uma especificação sem fazer novas perguntas.
2. Build (DeepLearning.AI + JetBrains, Spec-Driven Development with Coding Agents): a especificação é colocada no repositório como requirements.md, plan.md e validation.md sob um diretório datado, é implementada grupo de tarefas por grupo de tarefas em sua própria branch, validada contra validation.md, registrada no changelog, mesclada, e o roadmap é replanejado.

O grill substitui a entrevista fixa de três perguntas do curso SDD (Escopo / Decisões / Contexto) por uma entrevista completa de árvore de design. O curso SDD substitui a etapa "publicar no issue tracker" do to-spec por arquivos de especificação que vivem junto com o código e mudam com ele.

Visão Geral

Use quando uma mudança for grande o suficiente para que escrevê-la primeiro seja mais barato que retrabalho: uma nova funcionalidade, uma fase do roadmap, um sprint de MVP ou adicionar SDD a uma base de código legada. Pule para correções de uma linha e para caças de bugs puros (use pstack-engineering para causas raiz).

Frases de gatilho: "me grille e depois especifique", "grille para especificar", "orientado a especificação", "SDD", "especificação de funcionalidade", "trabalhe na próxima fase", "inicie a próxima funcionalidade".

Portões rígidos (nunca pular):

• Nenhum arquivo de especificação é escrito até que o usuário confirme que o grill atingiu um entendimento compartilhado (Portão A).
• Nenhum código é escrito até que o usuário tenha aprovado os arquivos de especificação (Portão B).
• Nada é mesclado até que cada item em validation.md passe (Portão C).

Instruções de Execução

Resolva SPECS=${SDD_SPECS_DIR:-specs} e BASE=${SDD_BASE_BRANCH:-<branch padrão do repositório>} no início. Os caminhos abaixo são relativos à raiz do projeto.

Estágio 0 — Orientar (fatos são seu trabalho)

1. Leia os arquivos AGENTS.md / CLAUDE.md, README.md e qualquer glossário ou ADRs do projeto. Siga as próprias regras de git do repositório (wrappers, nomenclatura de branches, sem force-push).
2. Verifique a existência de uma constituição: $SPECS/mission.md, $SPECS/tech-stack.md, $SPECS/roadmap.md.
   • Todos presentes → vá para o Estágio 1 para a próxima funcionalidade.
   • Ausentes, novo projeto → o primeiro grill é sobre a própria constituição (missão, público-alvo, lacunas de pilha tecnológica). Sua saída são os três arquivos, com roadmap.md dividido em fases muito pequenas, cada uma independente e entregável.
   • Ausentes, base de código existente (legado) → primeiro explore o código e rascunhe a constituição a partir do que realmente existe (pilha, convenções, funcionalidades entregues como fases concluídas), depois grille apenas as lacunas e o roadmap futuro.
3. Se o usuário não nomeou uma funcionalidade, o alvo é a próxima fase: a primeira seção do roadmap cujos itens estão todos desmarcados ([ ]).
4. Explore o código que a funcionalidade tocará. Nunca pergunte ao usuário algo que o repositório, as ferramentas ou a documentação possam responder. Delegue exploração ampla a um subagente fresco se o harness tiver um, e não bloqueie perguntas não relacionadas nisso.

Estágio 1 — Grill (entrevista de árvore de design)

Entreviste o usuário incansavelmente até o entendimento compartilhado. Trate o plano como uma árvore de design: cada decisão se ramifica nas decisões que dependem dela.

• Trabalhe em rodadas. A fronteira é cada decisão em aberto cujos pré-requisitos já estão resolvidos. Pergunte toda a fronteira em uma rodada, então aguarde.
• Numere cada pergunta e dê sua resposta recomendada. Formule-a de modo que "sim" aceite a recomendação.
• Uma pergunta que depende de outra pergunta ainda aberta nesta rodada pertence a uma rodada posterior.
• Cubra, ao longo das rodadas, pelo menos os eixos do SDD: Escopo (o que coleta, expõe, faz; formato dos dados), Decisões (armazenamento, visibilidade, validação, padrão de UX, arquitetura), Contexto (tom, restrições, limites da pilha, perguntas em aberto) e Pontos de teste: onde a funcionalidade será testada. Prefira pontos de teste existentes e o ponto mais alto possível; o ideal é um.
• Novas dependências, mudanças de esquema e mudanças de API pública são sempre perguntas explícitas, nunca suposições (tech-stack.md é a autoridade).

Formato da rodada:

❓ **Q1** - **<título>**: <pergunta, opções se houver>

➡️ <resposta recomendada>

---

❓ **Q2** - ...

Se o harness tiver uma ferramenta de pergunta estruturada (Claude Code AskUserQuestion), você pode usá-la para rodadas de até quatro perguntas de múltipla escolha; caso contrário, use o formato de texto acima.

O grill termina quando a fronteira está vazia. Resuma as decisões acordadas em uma lista curta e peça ao usuário para confirmar.

Portão A: não continue até que o usuário confirme o resumo.

Estágio 2 — Para a especificação (síntese, sem novas perguntas)

Transforme a conversa na especificação. Não entreviste novamente; se uma lacuna real aparecer, significa que o grill perdeu uma ramificação: pergunte apenas aquela questão, depois retome.

1. Crie a branch a partir de $BASE: phase-<N>-<nome-em-kebab> para uma fase do roadmap, caso contrário feature/<nome-em-kebab> (ou a própria convenção do repositório).
2. Releia $SPECS/mission.md e $SPECS/tech-stack.md, e as especificações de funcionalidade existentes para o estilo da casa.
3. Crie $SPECS/YYYY-MM-DD-<nome-da-funcionalidade>/ com a data de hoje e escreva os três arquivos a partir de references/spec-templates.md:
   • requirements.md — o conteúdo do to-spec (problema, solução, uma lista numerada extensa de histórias de usuário, decisões de implementação, decisões de teste, fora do escopo) mais as seções de Escopo / Decisões / Contexto do SDD. Sem caminhos de arquivo ou trechos de código, exceto um trecho de protótipo resumido que fixa uma decisão com mais precisão do que prosa.
   • plan.md — grupos de tarefas numerados, cada um implementável e testável de forma independente, com subtarefas numeradas.
   • validation.md — verificações automatizadas (comandos exatos), passo a passo manual, casos de borda, verificação de tom para texto voltado ao usuário e uma Definição de Pronto.
4. Opcional, se o usuário pedir ou o repositório rastrear trabalho em issues: também publique os requisitos como uma issue (gh issue create) e vincule-a a partir de requirements.md.
5. Mostre ao usuário os três arquivos (caminhos mais um breve resumo).

Portão B: aguarde aprovação. Feedback ("adicione um grupo de tarefas para X", "componentes vão em seus próprios arquivos") é aplicado à especificação primeiro, e cada arquivo mantido em sincronia.

Estágio 3 — Implementar

1. Implemente os grupos de tarefas em ordem. Após cada grupo: execute os testes e a verificação de tipos do projeto, faça commit com uma mensagem nomeando o grupo, marque suas caixas em plan.md.
2. Se a implementação mostrar que a especificação estava errada ou incompleta, atualize a especificação no mesmo commit do código que se desvia dela. Especificações e código nunca divergem.
3. Grupos sem dependência entre si podem ir para subagentes paralelos (cada um em sua própria worktree; siga as regras de worktree do host), mesclados de volta por você.
4. Nenhuma nova dependência sem a aprovação do usuário, mesmo que um grupo "precise" de uma.

Estágio 4 — Validar

1. Execute cada verificação automatizada em validation.md e cole a saída real.
2. Percorra as verificações manuais (para uma UI, realmente a acione: automação de navegador ou capturas de tela, não "deve funcionar").
3. Revisão aprofundada opcional: gere revisores de três perspectivas (correção, conformidade com a especificação, manutenibilidade) sobre o diff da branch, depois corrija o que os segura.
4. Pergunte ao usuário se a especificação precisa ser esclarecida à luz do que foi construído.

Portão C: cada item da Definição de Pronto passa, ou o usuário explicitamente renuncia a um (registre a renúncia em validation.md).

Estágio 5 — Fechar o ciclo

1. Marque a fase como completa em $SPECS/roadmap.md ([x]).
2. Atualize CHANGELOG.md (# Changelog, ## YYYY-MM-DD cabeçalhos do mais recente primeiro, um marcador por mudança significativa desde a última data registrada). Use um skill de changelog do projeto se existir um.
3. Faça commit, mude para $BASE, mescle a branch, delete-a, envie de acordo com as regras do repositório.
4. Replaneje: pergunte se algo aprendido muda mission.md, tech-stack.md ou o roadmap (mesclar, dividir ou reordenar fases). Decisões transversais (ex.: "usar Vitest", "UI responsiva") vão para tech-stack.md / mission.md e são portadas de volta para especificações existentes.
5. Ofereça a próxima fase: ela começa novamente no Estágio 1.

Variáveis de Ambiente

Variável	Padrão	Descrição
SDD_SPECS_DIR	specs	Diretório da constituição e especificações de funcionalidade, relativo à raiz do projeto
SDD_BASE_BRANCH	branch padrão do repositório	Branch da qual as funcionalidades são cortadas e na qual são mescladas

Lista de Verificação

• Constituição existe (mission.md, tech-stack.md, roadmap.md) antes de qualquer especificação de funcionalidade
• Cada pergunta do grill foi feita com uma resposta recomendada; nenhum fato foi perguntado que o repositório pudesse responder
• Usuário confirmou o resumo de decisões (Portão A) antes de qualquer arquivo de especificação ser escrito
• requirements.md, plan.md, validation.md existem sob $SPECS/YYYY-MM-DD-<nome>/ em uma branch de funcionalidade
• Usuário aprovou a especificação (Portão B) antes de o código ser escrito
• Cada grupo de tarefas foi commitado com testes passando; caixas do plano marcadas
• Especificação atualizada sempre que a implementação se desviou dela
• Todas as verificações de validation.md executadas com saída real (Portão C)
• Fase do roadmap marcada, changelog atualizado, branch mesclada e deletada
• Pergunta de replanejamento feita

Armadilhas Conhecidas

• Grillar para sempre. O grill termina quando a fronteira está vazia, não quando você fica sem curiosidade. Não repita decisões já acertadas; não pergunte sobre detalhes que pertencem à revisão de código.
• Entrevistar no to-spec. O Estágio 2 sintetiza; novas perguntas lá significam que o grill estava incompleto. Pergunte a única questão faltante, não uma segunda entrevista.
• Escrever antes do Portão A/B. O curso SDD é explícito: nada vai para o disco até que a entrevista seja respondida. Código antes da aprovação da especificação derrota o método.
• Fases grandes demais. Uma fase que não pode ser revisada em uma única sessão deve ser dividida no roadmap antes de especificar.
• Deriva da especificação. Uma mudança solicitada durante a implementação é aplicada à especificação primeiro, depois ao código. Uma especificação que não corresponde mais ao código é pior do que nenhuma.
• Caminhos de arquivo nos requisitos. Eles apodrecem rápido; descreva módulos e interfaces em vez disso (caminhos pertencem no máximo a subtarefas de plan.md).
• Regras do repositório vencem. Nomes de branch, wrappers de push, locais de worktree e regras de atribuição do AGENTS.md do repositório substituem os padrões aqui.

Veja references/spec-templates.md para os modelos de arquivo e references/sources.md para a origem de cada parte.