DimonSmart/DesenvolvimentoGuiadoPorEspecificacao

O que DesenvolvimentoGuiadoPorEspecificacao faz?

No desenvolvimento com IA, a habilidade principal não é mais apenas escrever código, mas descrever a intenção com precisão suficiente para que tanto humanos quanto agentes de IA possam agir sobre ela.

Visão Geral

Este skill define uma metodologia onde especificações claras e detalhadas substituem ou complementam a implementação direta. Ao invés de solicitar "implemente uma função de login", você especifica o comportamento esperado, entradas, saídas, tratamentos de erro e restrições de forma estruturada. Agentes de IA utilizam essa especificação para gerar código consistente e testável.

Como Usar

1. Defina a especificação: Em markdown ou formato estruturado, descreva o que deve ser feito, incluindo:

   • Objetivo do componente ou funcionalidade
   • Interfaces (API, CLI, etc.)
   • Comportamento esperado e casos de borda
   • Critérios de aceitação

2. Compartilhe com o agente de IA: Forneça a especificação como contexto para o modelo (ex.: em um arquivo .md ou diretamente no prompt).

3. Solicite implementação: Peça ao agente para gerar código de acordo com a especificação, revisando e iterando conforme necessário.

Exemplos

Exemplo 1: Função de cálculo

Especificação:

calcular_imc(peso_kg, altura_m) -> float

• Calcula o Índice de Massa Corporal (IMC) dado peso em kg e altura em metros.
• Retorna o IMC como float com duas casas decimais.
• Se altura_m <= 0, levanta ValueError("Altura deve ser positiva").
• Se peso_kg <= 0, levanta ValueError("Peso deve ser positivo").

Implementação gerada pelo agente:

def calcular_imc(peso_kg: float, altura_m: float) -> float:
    if altura_m <= 0:
        raise ValueError("Altura deve ser positiva")
    if peso_kg <= 0:
        raise ValueError("Peso deve ser positivo")
    imc = peso_kg / (altura_m ** 2)
    return round(imc, 2)

Exemplo 2: Componente React

Especificação:

<UserProfile userId={string} />

• Busca dados do usuário via GET /api/users/{userId}.
• Exibe loading com texto "Carregando..." enquanto a requisição não termina.
• Em caso de erro (status != 200), exibe mensagem "Falha ao carregar perfil".
• Em sucesso, renderiza nome, email e avatar.

Implementação pelo agente: (exemplo truncado)

function UserProfile({ userId }) {
  // ... lógica com fetch e renderização condicional
}

Suporte a Plataformas

• Claude Code: Funciona bem com descrições em linguagem natural e listas de requisitos.
• Cursor: Use arquivos .spec.md para especificações que o Cursor pode referenciar.
• Codex: Similar, forneça a especificação como parte do prompt.

Boas Práticas

• Seja específico: evite ambiguidades como "rápido" ou "bom"; prefira métricas concretas.
• Inclua casos de erro: especifique o que acontece em entradas inválidas ou falhas.
• Mantenha a especificação versionada junto com o código (specs/ ou na raiz do projeto).
• Revise a especificação com outros membros da equipe antes de implementar.

Conclusão

Adotar o desenvolvimento guiado por especificação melhora a previsibilidade e qualidade do código gerado por IA, reduzindo iterações e alinhando expectativas entre equipe e agentes de IA.