Como escrever especificações eficazes para agentes de IA - Addy Osmani

• O que faz a maior diferença na produtividade de agentes de IA → SPEC clara e estruturada
• SPEC ruim = ambiguidade → deriva da IA, falhas repetidas, excesso de contexto
• SPEC boa = documento vivo (SPEC.md) + atualizações contínuas

Componentes centrais de uma boa SPEC

• Objetivo / visão (por que construir, para quem é)
• Lista de funcionalidades + prioridades
• Stack técnica (React 18 + TS, Node 20 etc., de forma específica)
• Comandos de execução (npm test, lint, build etc.)
• Critérios de teste (quais testes precisam rodar para ser considerado sucesso)
• Estrutura de código / guia de estilo
• Workflow de Git (regras de branch, mensagens de commit)
• Definição de limites (✅ sempre / ⚠️ pergunte / 🚫 nunca faça)

Padrão eficaz de prompt inicial

• “Draft a detailed specification for … covering objectives, features, constraints, step-by-step plan”
• Primeiro, Plan Mode → fazer a IA redigir o rascunho da SPEC
• Depois, dividir e instruir em tarefas menores

Dicas práticas (só o essencial)

• Manter SPEC.md como arquivo separado → incluir apenas as seções relevantes em cada tarefa
• Modularização + separação em subtarefas
• Após cada tarefa, testes automáticos + verificação de conformidade com a SPEC
• Deixar claras as 3 camadas de regras de limite (Always / Ask / Never)