Loop Guiado por Especificação

Transforme um pedido de software incerto em uma especificação aprovada, uma implementação controlada e uma aceitação baseada em evidências. Mantenha os documentos do projeto na localização estabelecida do repositório; caso contrário, use docs/spec-driven/<feature-slug>/.

Quando Usar

Use esta habilidade para novos produtos, recursos de médio a grande porte, alterações entre módulos ou solicitações que necessitem de PRD/design técnico, esclarecimento ativo, execução multiagente ou um juiz principal. Não a use para uma pequena alteração em um único arquivo, uma correção de bug minúscula, explicação de código, trabalho apenas de revisão ou diagnóstico, pesquisa pura ou uma tarefa simples cuja especificação já esteja completa.

Exemplo Rápido

$spec-driven-loop Build a multi-tenant job dashboard with role-based access and evidence-backed acceptance.

Limitações

• Não se destina a edições pequenas e isoladas, trabalho apenas de revisão, diagnóstico ou pesquisa pura.
• Não substitui testes específicos do ambiente nem concede autorização para alterações não relacionadas ou ações externas.
• A implementação em produção não pode começar até que o usuário aprove explicitamente a especificação congelada e o contrato de aceitação.

Siga as instruções do repositório e os limites de autorização durante todo o processo. Combine os documentos de projeto gerados com o idioma do usuário ou o idioma da documentação existente do repositório; mantenha identificadores como FR-001 e AC-001 estáveis.

Invariantes Operacionais

• Fatos são responsabilidade do agente. Decisões pertencem ao usuário.
• Investigue fatos descobertos antes de fazer perguntas. Peça apenas decisões reais do produto ou trocas técnicas consequentes.
• Nunca escreva ou modifique código de produção até que o usuário aprove explicitamente a especificação, o escopo e o contrato de aceitação para implementação.
• Nunca disfarce incertezas. Marque-as como TBD, ASSUMPTION ou BLOCKED.
• O relatório de conclusão de um subagente é evidência, não aceitação. O agente principal é responsável pela integração e pelo julgamento final.
• Congele interfaces compartilhadas, estruturas de dados e tipos públicos antes do trabalho paralelo. Atribua propriedade de arquivos não sobreposta; serialize o trabalho sobreposto.
• Atualize os documentos duráveis após cada decisão ou loop de implementação. Uma transcrição de chat não é a fonte da verdade.
• Se a implementação revelar uma mudança de requisito em vez de um defeito de código, interrompa o trabalho afetado, revise a especificação, obtenha nova aprovação do usuário e, em seguida, retome.
• Preserve o escopo de autorização do usuário. Uma aprovação de especificação autoriza a implementação aprovada, não alterações não relacionadas ou ações externas.

O estágio de "interrogatório de requisitos" é informado pela árvore de decisão e método de fronteira grill-me / grilling com licença MIT de Matt Pocock.

Limites de Documentos

Mantenha cada fato em um documento autoritativo e referencie seu ID estável em outros lugares:

• PRD.md: por que e o que o produto deve fazer; é responsável pelo escopo, comportamento do usuário, regras de negócio, suposições e decisões do produto.
• TECH_DESIGN.md: como o comportamento aprovado do produto funcionará; é responsável pela arquitetura, contratos, dados, operações, segurança e decisões técnicas.
• ACCEPTANCE.md: prova observável de que os requisitos congelados foram atendidos; é responsável pelos critérios de aprovação/reprovação e evidências necessárias.
• AGENT_PLAN.md: quem executa o trabalho de implementação aprovado; é responsável por dependências, propriedade de arquivos, validação e contratos de tarefas do agente.
• LOOP.md: estado de execução recuperável atual e histórico de loops somente de adição; é responsável por tentativas, evidências, julgamentos, retrabalho, riscos e próxima ação.

Leia references/document-templates.md ao criar ou atualizar esses cinco documentos. Leia references/agent-and-judge-contracts.md antes de atribuir tarefas de implementação, integrar o trabalho do agente, julgar a aceitação ou emitir retrabalho.

1. Inspecione o Sistema Atual

Antes de fazer perguntas ao usuário:

1. Leia os AGENTS.md aplicáveis, instruções do projeto, especificações existentes e convenções do repositório.
2. Inspecione a arquitetura relevante, módulos, interfaces, banco de dados, testes, método de implantação e convenções de código.
3. Identifique termos de domínio estabelecidos e locais de documentação.
4. Resolva fatos de código, arquivos, ferramentas e documentação. Registre as descobertas e fontes no rascunho em vez de pedir ao usuário para redescobri-los.
5. Separe as escolhas do produto das escolhas técnicas e anote as dependências das decisões.

…