jeffreyehogg/agent-skills

Desenvolvimento de Funcionalidades Orientado por Especificação

Visão Geral

Esta habilidade impõe um Protocolo de Bloqueio Planeje-Antes-de-Codificar. Agentes de codificação autônomos frequentemente falham ao pular diretamente para edições de arquivos, levando a desvio de contexto, APIs alucinadas e desperdício de tokens em depuração por tentativa e erro.

Quando esta habilidade é ativada, nenhum código de aplicação pode ser modificado até que uma especificação formal (SPEC.md ou .specs/<slug-da-funcionalidade>.md) seja redigida, verificada contra as restrições do repositório e aprovada.

---

1. Fase 1: Exploração de Contexto e Restrições

Antes de redigir a especificação:

1. Identifique convenções existentes, modelos de dados e utilitários de API no projeto.
2. Localize definições de tipos ou arquivos de esquema (ex.: schema.prisma, drizzle/schema.ts, schemas Zod, especificações OpenAPI).
3. Não leia arquivos inteiros a menos que necessário; inspecione exportações, cabeçalhos de interfaces e tipos.

---

2. Fase 2: Redigir SPEC.md

Leia ./references/spec_template.md e crie .specs/<slug-da-funcionalidade>.md (ou SPEC.md na raiz do repositório, se solicitado) seguindo exatamente essa estrutura:

1. Objetivo, Critérios de Sucesso e Não-Objetivos Explícitos: Declaração clara do problema em 2 frases, critérios de aprovação determinísticos e limites explícitos fora do escopo.
2. Contratos de Dados e Assinaturas: Interfaces TypeScript exatas, tipos de colunas de banco de dados ou schemas de API.
3. Matriz de Limites de Modificação de Arquivos: Caminhos explícitos de Criar, Modificar (com funções/linhas alvo) e Proibido.
4. Checklist de Implementação e Protocolo de Verificação: Comandos de teste exatos, verificações de linter e casos de borda.

---

3. Fase 3: O Ponto de Verificação de Bloqueio (OBRIGATÓRIO)

Uma vez que a especificação é gerada:

1. Modo Interativo (Sessão de Usuário): Apresente um resumo conciso com link para o arquivo de especificação, destaque quaisquer trade-offs arquiteturais (usando ask_question se houver múltiplas abordagens válidas) e peça confirmação antes de escrever código:

   "Eu redigi a especificação em SPEC.md. Por favor, revise os contratos de dados propostos e a matriz de limites de arquivos. Devo prosseguir com a implementação?"

2. Modo de Subagente Autônomo: Se invocado por um Orquestrador Líder pai (ex.: de code-audit-orchestrator) que já forneceu um Plano de Remediação aprovado, verifique se a Matriz de Limites de Arquivos não tem conflitos com caminhos Proibido e prossiga para a Fase 4.
3. PARADA OBRIGATÓRIA: Em sessões interativas, aguarde aprovação ou feedback. Não toque nos arquivos fonte até receber o sinal verde.

---

4. Fase 4: Execução Faseada e Protocolo de Emenda Durante o Voo

Após a aprovação:

1. Isolamento em Sandbox Opcional: Para mudanças em vários arquivos ou quando a árvore de trabalho principal tem alterações não relacionadas, provisione uma worktree isolada via git-worktree-isolator antes de modificar arquivos.
2. Implemente a funcionalidade em marcos discretos e atômicos (ex.: Esquema $\to$ Lógica Central $\to$ Handlers de API $\to$ UI/Integração).
3. Marque as checkboxes de progresso no arquivo de especificação à medida que os marcos forem concluídos.
4. Mantenha os commits do git focados em marcos individuais.

Saída de Emergência: Emenda de Especificação Durante o Voo

Se a implementação descobrir uma restrição imprevista (ex.: um arquivo Proibido deve ser modificado, um tipo de SDK upstream não corresponde ao contrato redigido, ou o usuário altera os requisitos durante o voo):

1. Pare as edições imediatamente no marco afetado.
2. Acrescente uma entrada em ## 6. Emendas de Especificação (Registro de Delta) no arquivo de especificação documentando:
   • Gatilho / Bloqueador: Por que o contrato original não pode ser mantido.
   • Seção Emendada e Delta: Mudanças exatas nos Contratos de Dados ou na Matriz de Limites de Modificação de Arquivos.
3. Se o delta tocar em um arquivo antes Proibido ou alterar um contrato de API/schema público, pause e solicite confirmação rápida do usuário antes de retomar. Se o delta for puramente interno (ex.: extrair um arquivo auxiliar interno), registre o delta na especificação e continue.

---

5. Fase 5: Verificação e Arquivamento

1. Execute o conjunto de testes determinísticos especificado na Fase 2.
2. Verifique se todas as verificações de tipo e linters passam limpo.
3. Atualize o status da especificação para Concluído e arquive-a em .specs/completed/YYYY-MM-DD-<nome-da-funcionalidade>.md (ou remova arquivos de especificação temporários se o repositório não rastrear .specs/).