Desenvolvimento Orientado por Intenção
Produza critérios de aceitação úteis sem transformar a especificação em cerimônia. Inspecione o contexto disponível primeiro, exponha ambiguidades genuínas e escolha métodos de verificação que se adequem ao trabalho e ao seu risco.
Quando Ativar
- O usuário pede para esclarecer uma funcionalidade, definir critérios de aceitação ou mitigar riscos antes da implementação
- A solicitação envolve segurança, autenticação, dados persistentes, migrações, APIs externas ou conformidade
- O usuário deseja preparar um artefato de transferência para outro agente ou equipe
- A solicitação é ambígua o suficiente para que o resultado esperado ainda não seja observável ou testável
- O usuário invoca explicitamente esta skill com
/intent-driven-development
Não ative para edições triviais, correções diretas de uma linha, sessões de depuração ativas, solicitações de revisão de código ou solicitações de implementação cujas condições de aceitação já estejam claras.
Como Funciona
- Inspecione o contexto primeiro — lê o repositório, documentação, schemas e infraestrutura de teste em busca de fatos técnicos antes de fazer qualquer pergunta, tratando restrições de produto/negócio como algo que apenas o usuário ou um artefato de produto pode fornecer
- Escolha a profundidade — seleciona Captura Rápida (3-7 critérios, risco baixo/moderado) ou Briefing de Aceitação Completo (segurança, dados, migração, mudanças entre sistemas) com base no perfil de risco
- Pergunte minimamente — só faz perguntas cujas respostas não podem ser inferidas e que alteram materialmente o escopo ou comportamento
- Escreva critérios observáveis — cada AC-NNN descreve uma condição inicial, gatilho, resultado esperado, efeito colateral proibido, método de verificação e prioridade; sem palavras vagas como "corretamente" ou "seguramente" sem evidência
- Prosseguir ou transferir — para solicitações claras sem riscos bloqueadores, registra critérios e continua; para mudanças arriscadas, apresenta bloqueadores e aguarda confirmação
- Lidar com revisão — se um AC falhar durante a implementação devido a restrições arquiteturais, marca-o como
[revisado], atualiza escopo ou método de verificação, incrementa o número de revisão e reapresenta apenas os critérios alterados
Exemplos
Captura Rápida — "Adicionar exportação CSV ao painel"
Objetivo: Usuários autenticados podem baixar dados do painel como um arquivo CSV.
Escopo: Exportação das linhas atualmente filtradas; nome do arquivo inclui data.
Fora do escopo: Exportações agendadas, entrega por e-mail, formato Excel.
Suposições: Contagem máxima de linhas é inferior a 10k; sem PII nos campos exportados.
AC-001: Exportação gera arquivo com cabeçalhos corretos
- Cenário: usuário autenticado, pelo menos uma linha de dados visível
- Ação: clicar em "Exportar CSV"
- Esperado: navegador baixa arquivo com colunas [id, nome, created_at]
- Não deve: expor campos internos ou linhas pertencentes a outros usuários
- Verificação: teste de integração automatizado + verificação manual de schema
- Prioridade: Obrigatório
Gatilho de Briefing de Aceitação Completo — "Migrar autenticação de usuário para OAuth"
Mudança de autenticação + dependência externa + dados de sessão existentes → Briefing Completo com tabela de Revisão de Risco, decisões bloqueadoras sobre estratégia de invalidação de sessão e AC de rollback explícito.
Revisão de especificação existente — usuário cola um PRD
A skill revisa o documento em busca de limites de escopo ausentes, requisitos não verificáveis ("o sistema deve ser rápido") e suposições silenciosas, e retorna critérios corrigidos ou suplementares sem reiniciar a descoberta.
Regras Operacionais
- Inspecione o repositório, documentação, issue, design e contexto de teste disponíveis antes de pedir fatos técnicos que podem ser descobertos localmente.
- Não infira restrições de produto ou negócio a partir do código. Regras de negócio, obrigações de conformidade e regulatórias, SLAs contratuais, preços, política de retenção de dados, priorização e usuários-alvo não podem ser lidos de um repositório. Trate-os como desconhecidos até que o usuário os forneça ou um artefato de produto autoritativo (PRD, contrato, documento de política) os declare. Registre-os como suposições sinalizadas para confirmação, nunca como fatos descobertos. O repositório diz como o sistema se comporta hoje, não o que o negócio exige que ele faça.
- Faça apenas perguntas cujas respostas são necessárias e não podem ser inferidas com segurança. Agrupe perguntas curtas e relacionadas quando isso economizar idas e vindas desnecessárias.
- Não bloqueie a implementação por padrão. Quando o usuário pediu para implementar uma mudança suficientemente clara, registre brevemente as principais suposições e critérios de aceitação e, em seguida, prossiga ou passe para o fluxo de trabalho de implementação.
- Exija confirmação explícita do usuário antes de prosseguir apenas quando uma decisão não resolvida puder criar exposição material de segurança, perda de dados, migração irreversível, quebra contratual/API, custo significativo ou ação externa destrutiva.
- Não escreva um documento de aceitação em um repositório, altere arquivos de projeto, crie um branch, faça commit ou invoque outra skill, a menos que o usuário solicite ou o fluxo de trabalho do repositório ativo exija explicitamente.
- Trate testes automatizados como evidência, não verdade. Prefira automação quando confiável e proporcionada; permita verificação manual de UX, acessibilidade, segurança, legal ou operacional onde a automação não puder estabelecer o resultado.
- Nunca inclua segredos reais, credenciais, tokens, chaves privadas, dados pessoais ou payloads de produção sensíveis em critérios de aceitação, fixtures, exemplos ou artefatos salvos. Use valores redigidos ou sintéticos.
- Não execute testes destrutivos, migrações, sondas de segurança, testes de carga, chamadas externas pagas ou operações contra dados de produção/ao vivo sem autorização explícita e um ambiente seguro identificado.
- Quando um critério de aceitação não puder ser satisfeito devido a uma restrição arquitetural, de plataforma ou externa descoberta durante a implementação, não o descarte silenciosamente ou o contorne. Atualize o critério afetado (marque-o como
[revisado], declare a restrição e ajuste escopo ou método de verificação), incremente o número de revisão e reapresente apenas os critérios alterados ao usuário antes de continuar. Exija confirmação explícita apenas se a revisão alterar uma decisão bloqueadora ou reduzir materialmente as garantias de segurança ou correção.
Escolha a Profundidade
Use a menor saída útil.
Captura Rápida
Use para uma mudança clara, mas não trivial, com risco baixo ou moderado. Produza:
- Objetivo
- Escopo / Fora do escopo
- Suposições
- 3-7 critérios de aceitação com métodos de verificação
- Perguntas bloqueadoras, se houver
Não atrase a implementação para aprovação, a menos que exista um risco bloqueador das regras operacionais ou o usuário tenha solicitado especificamente uma especificação primeiro.
Briefing de Aceitação Completo
Use para mudanças ambíguas, entre sistemas, sensíveis à segurança, de alteração de dados, migração, conformidade ou alto custo, ou quando o usuário solicitar um artefato de transferência. Produza o modelo completo abaixo e solicite confirmação para decisões bloqueadoras não resolvidas antes da implementação arriscada.
Revisão de Especificação Existente
Quando o usuário já forneceu um PRD, issue, plano ou critérios de aceitação:
- Revise-o em vez de reiniciar a descoberta.
- Identifique limites de escopo ausentes, suposições inseguras, contradições e requisitos não verificáveis.
- Retorne critérios corrigidos ou suplementares.
Fluxo de Trabalho
1. Estabelecer Objetivo e Risco
Extraia ou pergunte:
- O resultado observável para o usuário ou sistema.
- Os atores afetados.
- A principal consequência de falha.
- Dimensões de risco que realmente se aplicam: segurança/privacidade, dados persistentes, compatibilidade/API, migração, dependências externas, custo, concorrência, desempenho, usabilidade/acessibilidade.
Evite fazer perguntas genéricas sobre riscos irrelevantes.
2. Descobrir Contexto
Quando artefatos locais ou conectados estiverem disponíveis, inspecione apenas o necessário:
- Comportamento existente e arquivos ou interfaces diretamente relacionados.
- Convenções do repositório, documentação do produto, contratos de API, schemas de dados ou histórico de migração.
- Infraestrutura de verificação existente e comandos realistas.
- Dependências externas e se são testáveis isoladamente.
Registre fatos descobertos separadamente das suposições fornecidas pelo usuário. Se o contexto não puder ser inspecionado, diga o que é desconhecido e faça perguntas focadas.
O repositório revela fatos técnicos — como o sistema se comporta hoje, suas convenções e seus contratos. Ele não revela restrições de produto ou negócio: regras de negócio, obrigações de conformidade e regulatórias, SLAs contratuais, preços, política de retenção de dados, priorização e usuários-alvo. Nunca reconstrua isso a partir do código ou de nomes. Capture-as apenas do usuário ou de um artefato de produto autoritativo e liste-as como suposições a confirmar até lá.
3. Definir Escopo
Declare:
- Objetivo: uma frase descrevendo o resultado pretendido.
- Escopo: comportamento que esta mudança deve entregar.
- Fora do escopo: trabalho adjacente tentador explicitamente excluído.
- Suposições: alegações ainda não comprovadas.
- Decisões bloqueadoras: escolhas não resolvidas que afetam materialmente a segurança ou o comportamento.
4. Escrever Critérios de Aceitação
Use AC-001, AC-002 e assim por diante. Cada critério deve descrever comportamento observável e um método de verificação apropriado; critérios e testes não são obrigados a mapear um a um.
Para cada critério aplicável, inclua:
- Cenário ou condição inicial.
- Ação ou gatilho.
- Comportamento observável esperado.
- Efeito colateral proibido quando significativo.
- Método de verificação: teste automatizado, verificação de integração, revisão manual de UX, verificação de acessibilidade, revisão de segurança, verificação operacional ou aceitação das partes interessadas.
- Restrição de ambiente/segurança quando a verificação puder afetar dados, serviços, custo ou segredos.
- Prioridade: obrigatório, importante ou opcional.
Não use palavras como "corretamente", "seguramente", "rápido", "intuitivo" ou "robusto" sem definir evidências observáveis ou registrá-las como um julgamento de revisão humana.
5. Cobrir Apenas Limites Relevantes
Considere estas categorias, mas inclua apenas as que se aplicam:
| Categoria | Incluir quando | Evidência típica |
|---|---|---|
| Caminho feliz | Comportamento novo ou alterado visível ao usuário | Fluxo de trabalho bem-sucedido ou transição de estado |
| Validação | A mudança aceita entrada | Entrada malformada ou de valor limite rejeitada sem mutação |
| Autorização/privacidade | Dados ou ações têm limites de acesso | Acesso negado e sem divulgação sensível |
| Persistência/migração | Dados armazenados ou schemas mudam | Leitura reversa, migração, rollback ou comportamento de backup |
| Compatibilidade | APIs públicas, arquivos, eventos ou clientes podem quebrar | Contrato existente ou fixture permanece válido |
| Recuperação de falha | Rede, serviço ou falha assíncrona existe | Sem estado parcial ou comportamento de repetição/degradação claro |
| Idempotência/concorrência | Repetições ou gravações simultâneas são plausíveis | Sem efeito colateral duplicado ou estado final inválido |
| Desempenho | Um limite de usuário ou serviço é relevante | Condições de medição e limite definidos |
| UX/acessibilidade | Uma pessoa interage com o resultado | Teclado, feedback, recuperação de erro, revisão visual/manual |
6. Apresentar e Continuar
- Para uma solicitação de esclarecimento/especificação, apresente o briefing e peça decisões apenas sobre os bloqueadores listados.
- Para uma solicitação de implementação sem bloqueador, apresente um resumo compacto de critérios como parte do trabalho e continue com a implementação.
- Para transferência para outro agente ou equipe, inclua contexto e detalhes de verificação suficientes para que eles ajam sem inventar requisitos.
- Salve o briefing em um arquivo somente quando solicitado. Use um caminho aprovado pelo repositório quando existir; caso contrário, pergunte ou declare o destino escolhido antes de escrever.
Modelo de Saída
Use este modelo para um Briefing de Aceitação Completo. Omita seções irrelevantes para Captura Rápida.
# Briefing de Aceitação: <Nome da Mudança>
**Status:** Rascunho | Aprovado | Implementado | Verificado
**Revisão:** <número>
**Preparado para:** <usuário/equipe/agente, quando conhecido>
**Aprovação necessária antes de trabalho arriscado:** Sim | Não - <motivo>
## Registro de Revisões
| Rev | Data | Critérios alterados | Motivo |
| --- | --- | --- | --- |
| 1 | <data> | — | Rascunho inicial |
## Objetivo
<Uma frase de resultado observável.>
## Escopo
**Escopo**
- <comportamento incluído>
**Fora do escopo**
- <trabalho adjacente excluído>
## Contexto
**Fatos descobertos** (técnico, verificado do repositório ou artefato)
- <como o sistema se comporta hoje, convenções, contratos>
**Restrições de produto/negócio** (fornecido pelo usuário ou artefato de produto, nunca inferido do código)
- <regra de negócio, obrigação de conformidade/SLA, política de retenção, prioridade, usuário-alvo — ou "nenhum fornecido ainda">
**Suposições**
- <afirmação não verificada a confirmar ou validar>
**Dependências e restrições**
- <serviço externo, convenção local, obrigação de compatibilidade, limite de ambiente>
## Revisão de Risco
| Área de risco | Aplica-se? | Tratamento obrigatório |
| --- | --- | --- |
| Segurança/privacidade | Sim/Não | <redação, autorização, revisão, etc.> |
| Dados persistentes/migração | Sim/Não | <compatibilidade, backup, rollback, etc.> |
| Efeitos externos/custo | Sim/Não | <ambiente sandbox/teste/autorização> |
| Compatibilidade/API | Sim/Não | <contrato a preservar ou versionar> |
| UX/acessibilidade | Sim/Não | <evidência manual ou automatizada> |
## Critérios de Aceitação
### AC-001: <comportamento observável>
- **Cenário:** <condição inicial>
- **Ação:** <gatilho único>
- **Esperado:** <resultado observável>
- **Não deve:** <efeito colateral proibido, se aplicável>
- **Verificação:** <método e evidência pretendida>
- **Ambiente/segurança:** <restrições, se aplicável>
- **Prioridade:** Obrigatório | Importante | Opcional
## Decisões Bloqueadoras
- [ ] <apenas decisões que impedem o progresso seguro ou correto>
## Plano de Verificação
| Critério | Evidência de verificação | Status |
| --- | --- | --- |
| AC-001 | <comando de teste/verificação/revisão ou tipo de evidência> | Pendente |
Exemplos de Aprovação/Reprovação
Use estes para julgar se a skill realmente produziu um briefing verificável, não prosa de planejamento.
Um critério de aceitação falho
AC-001: A exportação funciona corretamente e é segura.
Falha — "funciona corretamente" e "segura" não são observáveis, não há cenário, gatilho, resultado esperado, efeito colateral proibido ou método de verificação.
Um critério de aceitação que passa
AC-001: O botão de exportação fica visível apenas para usuários autenticados
- Cenário: usuário não autenticado na página do painel
- Ação: renderizar o painel
- Esperado: o botão "Exportar CSV" não está presente no DOM
- Não deve: fazer solicitação de rede para /export
- Verificação: `npm run test:integration -- --grep "export visibility"`
- Prioridade: Obrigatório
Passa — a condição inicial, o gatilho, o resultado observável, a proibição e a verificação automatizada são todos declarados explicitamente.