Como escrever boas especificações para agentes de IA

 (addyosmani.com)
110 pontos por GN⁺ 2026-01-19 | 3 comentários | Compartilhar no WhatsApp
  • Jogar uma especificação enorme de uma vez para um agente de codificação com IA não funciona bem; o ponto-chave é escrever especificações inteligentes
  • Recomenda-se apresentar primeiro a visão de alto nível e deixar a IA expandir o plano detalhado; depois, revisar o plano em modo somente leitura no Plan Mode e então passar para a etapa de escrita de código
  • A análise de mais de 2.500 arquivos de configuração de agentes no GitHub mostrou que especificações eficazes incluem 6 áreas centrais: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries
  • Trabalhos grandes devem ser divididos em pequenas tarefas modularizadas, em vez de um único prompt gigante, e é preciso fornecer apenas o contexto necessário para cada tarefa para evitar queda de qualidade
  • O núcleo do fluxo de desenvolvimento orientado por especificações é embutir na especificação limites em 3 níveis (Always/Ask first/Never), autoverificação e testes de adequação, além de testar, iterar e evoluir continuamente

TL;DR

  • Escreva especificações claras com o nível adequado de detalhes (estrutura, estilo, testes, limites etc.)
  • Para trabalhos grandes, recomenda-se dividir em unidades menores em vez de usar um prompt monolítico
  • O plano deve ser elaborado primeiro em modo somente leitura, depois executado e continuamente aprimorado

Princípio central: escrever especificações inteligentes

  • Simplesmente despejar uma especificação enorme em um agente de IA tende a falhar, por esbarrar nos limites da janela de contexto e no orçamento de atenção (attention budget) do modelo
  • Uma “especificação inteligente” é um documento que orienta o agente com clareza, se mantém dentro de um tamanho de contexto prático e evolui junto com o projeto
  • O texto organiza em forma de framework os princípios extraídos do uso de agentes de codificação como Claude Code e Gemini CLI

Princípio 1: dê primeiro a visão geral, e deixe a IA rascunhar os detalhes

  • Em vez de tentar projetar tudo em excesso desde o início, comece definindo com clareza apenas a declaração de objetivo e alguns requisitos centrais
  • A ideia é tratar essa especificação inicial como um “briefing de produto” e deixar que o agente, a partir disso, expanda e escreva uma especificação detalhada
  • Agentes baseados em LLM costumam preencher bem os detalhes quando as instruções de alto nível são claras, mas tendem a se desviar facilmente quando a missão é vaga
  • Por isso, o essencial é fixar logo no começo uma missão clara, para que o agente não fique à deriva

  • Uso do Plan Mode

    • O Plan Mode do Claude Code é um modo que mantém o agente em somente leitura e faz com que ele apenas analise a base de código e monte um plano detalhado
    • Ao entrar no Plan Mode com Shift+Tab e explicar “o que você quer construir”, o agente percorre o código existente e redige um rascunho da especificação
    • Nesse momento, também é possível pedir que ele revise a arquitetura, as boas práticas, os riscos de segurança e a estratégia de testes do plano
    • O ideal é manter o Plan Mode até que o plano esteja refinado o suficiente, sem margem para interpretações equivocadas; só então sair do Plan Mode e entrar na fase de execução

  • Usar a especificação como contexto

    • A especificação finalizada deve ser salva em um arquivo como SPEC.md e, durante o trabalho, apenas as seções necessárias devem ser repassadas ao agente
    • Como o arquivo de especificação permanece entre sessões, ele também serve para fixar a IA no mesmo ponto de referência quando o projeto é retomado
    • Isso ajuda a reduzir o esquecimento que acontece quando o histórico de conversa fica longo ou quando o agente é reiniciado
    • Assim como equipes usam um PRD (documento de requisitos do produto) como referência compartilhada, ele passa a cumprir o papel de “documento único de referência” para humanos e IA

  • Manter o foco nos objetivos

    • Uma especificação de alto nível funciona melhor quando se concentra no what/why em vez de descrever todo o método de implementação desde o início, deixando o how concreto para depois
    • A estrutura pode seguir algo como histórias de usuário e critérios de aceitação: “Quem é o usuário? / O que ele precisa? / Como é o sucesso?”
    • O GitHub Spec Kit também enfatiza esse fluxo: dar uma explicação de alto nível sobre “o que” e “por que” está sendo criado, e então deixar que o agente de codificação produza especificações detalhadas com foco na experiência do usuário e nos critérios de sucesso

Princípio 2: estruturar a especificação como um PRD profissional (ou SRS)

  • É importante tratar a especificação de IA não como uma simples coleção de anotações, mas como um documento estruturado com seções claras
  • Um formato abrangente e organizado, como um PRD ou um documento de design de sistema, funciona especialmente bem para uma IA que interpreta o conteúdo literalmente
  • A análise de mais de 2.500 arquivos de configuração de agentes no GitHub mostrou que especificações eficazes incluem em comum 6 áreas principais

    • 1. Commands

      • Coloque os comandos executáveis no início do documento
      • Em vez de listar apenas o nome da ferramenta, informe o comando completo, incluindo flags: npm test, pytest -v, npm run build

    • 2. Testing

      • Especifique de forma concreta como executar os testes, quais frameworks são usados, onde ficam os arquivos de teste e qual é o nível de cobertura esperado

    • 3. Project Structure

      • Diferencie com clareza onde ficam o código-fonte, os testes e a documentação
      • Exemplo: "src/ é o código da aplicação, tests/ são os testes unitários, docs/ é para a documentação"

    • 4. Code Style

      • Em vez de explicar o estilo longamente, um único snippet de código real é muito mais eficaz
      • Apresente junto as convenções de nomenclatura, os padrões de formatação e exemplos de saída desejada

    • 5. Git Workflow

      • Se você especificar as convenções de nomenclatura de branches, o formato das mensagens de commit e os requisitos de PR, o agente também seguirá esse fluxo

    • 6. Boundaries

      • Defina com clareza as áreas nas quais o agente nunca deve mexer
      • Segredos, diretórios vendor, configurações de produção, pastas específicas etc.
      • A pesquisa do GitHub identificou “nunca faça commit de segredos” como a restrição útil mais frequente

  • Seja específico sobre a stack

    • Em vez de generalizar com algo como “projeto React”, é importante escrever de forma específica, como “React 18 + TypeScript + Vite + Tailwind CSS”
    • Também é preciso informar versões e dependências principais; uma especificação ambígua acaba gerando código ambíguo

  • Use um formato consistente

  • Integre a especificação à toolchain

    • Trate a especificação não como um simples documento, mas como um “artefato executável” conectado ao controle de versão e ao CI/CD
    • O GitHub Spec Kit usa um workflow de gate em 4 etapas que coloca a especificação no centro do processo de engenharia
      • Specify: fornece uma descrição de alto nível do que será criado e por quê, e o agente de codificação gera a especificação detalhada
      • Plan: estabelece um plano técnico com a stack desejada, arquitetura e restrições
      • Tasks: divide a especificação e o plano em unidades reais de trabalho, decompondo cada uma em partes testáveis
      • Implement: o agente de codificação executa as tarefas uma a uma, ou em paralelo

  • Persona especializada por meio de agents.md

    • Em ferramentas como o GitHub Copilot, é possível definir personas de agentes especializados
    • É possível separar papéis como @docs-agent (documentação técnica), @test-agent (QA) e @security-agent (code review)
    • Cada arquivo agents.md atua como uma especificação focada, contendo o modo de agir, os comandos e os limites daquela persona

  • Projetar a Agent Experience (AX)

    • Assim como APIs são projetadas pensando na Developer Experience (DX), as especificações também precisam ser projetadas considerando a Agent Experience (AX)
    • Um formato limpo e fácil de fazer parse é importante
      • O schema OpenAPI das APIs que o agente vai usar
      • Resumos de documentação para consumo por LLM (llms.txt)
      • Definições de tipos explícitas
    • Quanto mais a especificação seguir padrões como MCP (Model Context Protocol), mais o agente conseguirá entendê-la e operar com estabilidade

  • Mantenha como documento vivo

    • A especificação não é um documento que se escreve uma vez e pronto; ela deve ser atualizada continuamente sempre que decisões forem tomadas com a IA ou novos fatos surgirem
    • Em workflows orientados por especificação, a especificação conduz a implementação, os testes e a decomposição de tarefas, e a próxima etapa não começa antes de a especificação ser validada
    • Essa especificação não é um documento apenas para a IA, mas uma ferramenta central para que os desenvolvedores supervisionem todo o fluxo e confirmem se os resultados da IA realmente atendem aos requisitos

Princípio 3: dividir tarefas em prompts e contextos modularizados

  • Em vez de colocar tudo em um único prompt gigantesco, forneça contexto para que o agente foque em apenas uma tarefa por vez
  • Colocar os requisitos, o código e as instruções de todo o projeto em um único prompt tende, na prática, a aumentar a confusão
  • Além do risco de atingir o limite de tokens, a "maldição das instruções (curse of instructions)" pode fazer o modelo perder foco rapidamente

  • A maldição das instruções

    • Segundo pesquisas, quanto mais instruções ou dados são acumulados em um prompt, o desempenho em seguir cada instrução com precisão cai de forma perceptível
    • Mesmo modelos poderosos como GPT-4 ou Claude têm dificuldade quando se pede que satisfaçam muitos requisitos ao mesmo tempo
    • Por exemplo, se você der 10 regras detalhadas em bullets, há uma tendência de o modelo seguir apenas as primeiras e ir ignorando gradualmente as do fim
    • Uma estratégia melhor é o foco iterativo: concentrar o modelo em apenas um subproblema por vez e, depois de terminar, passar ao próximo

  • Divida a especificação em etapas ou componentes

    • Se o documento de especificação for longo ou cobrir um escopo amplo, considere separá-lo em várias partes
    • Exemplo: separar "Backend API Spec" e "Frontend UI Spec" em seções distintas
    • Ao trabalhar no backend, nem sempre é necessário fornecer junto a especificação do frontend
    • Em um ambiente com múltiplos agentes, também é possível ter agentes separados ou subprocessos para cada área
    • O guia de IA da DigitalOcean também alerta para “não misturar tarefas de autenticação e alterações no schema do banco de dados de uma vez”

  • TOC/Resumo expandido para especificações grandes

    • Uma abordagem é pedir ao agente que primeiro escreva um sumário expandido (TOC) de toda a especificação
    • Cada seção é condensada em alguns pontos-chave ou palavras-chave, com referência ao local onde estão os detalhes
    • Exemplo: “Security: usar HTTPS, proteger chaves de API, implementar validação de entrada (ver especificação completa §4.2)”
    • Com esse resumo hierárquico pronto, o prompt pode manter apenas a visão geral, enquanto os detalhes são fornecidos só quando necessário
    • O TOC expandido funciona como um índice e faz o agente perceber “ah, existe uma seção de segurança”, levando-o a pedir aquela parte quando precisar
    • Esse método de resumo hierárquico ajuda os LLMs a manter a estrutura de alto nível

  • Uso de subagentes ou “skills”

    • Como os subagentes (ou “skills”) descritos pela Anthropic, é possível usar múltiplos agentes com papéis separados
    • Cada subagente é configurado para uma área de especialidade específica e recebe apenas a parte da especificação correspondente àquele domínio
    • Exemplo: o subagente Database Designer conhece apenas a seção de modelo de dados, enquanto o subagente API Coder conhece apenas a especificação dos endpoints de API
    • Isso permite que cada agente trabalhe com um contexto menor e uma função mais clara, possibilitando mais precisão e trabalho em paralelo
    • O Claude Code oferece suporte à definição de subagentes com seu próprio system prompt e ferramentas

  • Agentes paralelos para aumentar a vazão

    • Executar vários agentes ao mesmo tempo está surgindo como a próxima etapa da produtividade de desenvolvedores
    • Em vez de esperar um agente terminar, agentes são colocados para trabalhar em paralelo em tarefas que não se sobrepõem
    • Simon Willison descreve isso como “adotar agentes de programação paralelos” e comenta que é surpreendentemente eficaz, mas mentalmente bem cansativo
    • O ponto-chave é dividir claramente o escopo das tarefas para que os agentes não interfiram no trabalho uns dos outros
    • Frameworks de orquestração como LangGraph ou OpenAI Swarm ajudam nessa coordenação,
    • e, ao usar um banco de dados vetorial como o Chroma como memória compartilhada, é possível acessar contexto comum sem repetir prompts

  • Agente único vs. múltiplos agentes: quando usar

    Aspecto Agente único Agentes paralelos/múltiplos
    Vantagens Configuração simples, baixo overhead e facilidade para depurar e rastrear o fluxo Alta vazão, capacidade de lidar com interdependências complexas e especialização por domínio
    Desvantagens Sobrecarga de contexto em projetos grandes, iteração mais lenta, ponto único de falha Maior custo de coordenação, possibilidade de conflitos, necessidade de memória compartilhada
    Quando é adequado Módulos isolados, projetos pequenos ou médios, prototipagem inicial Codebases grandes, separação entre codificação, testes e revisão, desenvolvimento de funcionalidades independentes
    Dicas Usar resumo da especificação, atualizar o contexto por tarefa, resetar a sessão com frequência No início, limitar a 2 ou 3 agentes, compartilhar ferramentas com MCP, deixar os limites bem claros

  • Faça cada prompt focar em uma única tarefa/seção

    • Mesmo sem um ambiente complexo com múltiplos agentes, ainda é possível impor modularidade manualmente
    • Exemplo: depois de escrever a especificação, na etapa “Step 1: implementar o schema do banco de dados”, forneça apenas a seção Database da especificação
    • Sempre que a tarefa principal mudar, reorganize o contexto para reduzir distrações causadas por informações antigas ou irrelevantes
    • Alguns guias recomendam iniciar uma nova sessão ao trocar de funcionalidade principal para limpar o contexto

  • Use instruções inline e TODOs no código

    • Um método é deixar no código comentários // TODO com o que precisa ser feito e fazer o agente preencher um por um
    • Cada TODO funciona como uma mini especificação para uma tarefa pequena
    • Como resultado, a IA passa a focar em um escopo bem estreito, no estilo “implemente apenas esta função de acordo com este trecho da especificação”

Princípio 4: incorporar autoinspeção, restrições e expertise humana

  • Trate a especificação não apenas como uma lista de tarefas do agente, mas como um guia para controlar a qualidade, refletindo ativamente sua própria expertise
  • Uma boa especificação antecipa onde a IA pode errar e estabelece guardrails nesses pontos
  • Inclua conhecimento de domínio, casos de borda e vários “cuidados” para que a IA não opere em um vácuo sem contexto
  • É mais fácil entender se você pensar na especificação como o treinador e árbitro da IA: orienta a abordagem correta e freia imediatamente comportamentos errados
  • Segundo a análise de mais de 2.500 arquivos de agentes do GitHub, as especificações mais eficazes não usam apenas uma lista de proibições, mas um sistema de limites em 3 níveis
    • Elas deixam claro quando o agente pode seguir em frente normalmente, quando deve parar e perguntar, e quando deve interromper totalmente

    • ✅ Always do (sempre fazer)

      • Tarefas que devem ser executadas sem perguntar
      • Ex.: “sempre executar testes antes do commit”, “sempre seguir as convenções de nomenclatura do guia de estilo”, “sempre registrar erros no serviço de monitoramento”

    • ⚠️ Ask first (pergunte antes)

      • Tarefas que exigem aprovação humana
      • Ex.: “perguntar antes de modificar o schema do banco de dados”, “perguntar antes de adicionar uma nova dependência”, “perguntar antes de alterar a configuração de CI/CD”
      • Pode até ser tecnicamente possível, mas aqui são filtradas mudanças que exigem julgamento humano por terem grande impacto

    • 🚫 Never do (nunca fazer)

      • Áreas de parada obrigatória e explícita
      • Ex.: “nunca fazer commit de segredos ou chaves de API”, “nunca editar node_modules/ ou vendor/”, “nunca remover testes que falham sem aprovação explícita”
      • A pesquisa também confirmou que “nunca fazer commit de segredos” foi uma das restrições úteis mais frequentes

  • Incentive a autoverificação

    • Oriente o agente a verificar o próprio resultado com base na especificação
    • Se as ferramentas permitirem, inclua no fluxo de trabalho a execução direta de testes unitários ou lint após gerar o código
    • Também é possível dar instruções de rechecagem no nível do prompt
      • Ex.: “depois de implementar, compare o resultado com a especificação, verifique se todos os requisitos foram atendidos e, se houver itens não atendidos, liste-os”
    • Isso faz o LLM confrontar sua própria saída com a especificação, reduzindo omissões

  • LLM-as-a-Judge para verificações subjetivas

    • Para critérios difíceis de automatizar, como estilo de código, legibilidade e conformidade com padrões de arquitetura, use a abordagem LLM-as-a-Judge
    • Um segundo agente (ou um prompt separado) revisa a saída do primeiro agente com base nos critérios de qualidade da especificação
    • Ex.: “revise se este código segue nosso guia de estilo e marque as violações”
    • O agente no papel de árbitro devolve feedback, que pode ser incorporado ou usado como gatilho para revisão

  • Teste de conformidade

    • Willison recomenda criar uma suíte de conformidade (conformance suite)
    • Trata-se de testes independentes de linguagem, muitas vezes baseados em YAML, que funcionam como um contrato que toda implementação deve cumprir
    • Ao criar uma API, a suíte de conformidade define entradas e saídas esperadas, e o código produzido pelo agente precisa satisfazer tudo isso
    • Na seção Success da especificação, explicite critérios como “é obrigatório passar em todos os casos de conformance/api-tests.yaml”

  • Use testes na especificação

    • Quando possível, inclua diretamente no fluxo da especificação e do prompt um plano de testes ou testes reais
    • Assim como no TDD, os casos de teste tornam os requisitos mais claros
      • Ex.: em Success Criteria, “esta entrada de exemplo deve necessariamente gerar esta saída”
    • Willison descreve uma suíte de testes robusta como algo que dá ao agente praticamente um superpoder
    • Isso porque, quando um teste falha, é possível validar na hora e iterar
    • Em uma composição com subagentes, também é possível ter um agente de testes dedicado, que recebe os critérios da especificação e continua validando a saída de código

  • Reflita o conhecimento de domínio

    • A especificação deve conter insights práticos que só desenvolvedores experientes ou pessoas com conhecimento do contexto costumam ter
    • Ex.: ao criar um agente para e-commerce, deixe explícito que “products” e “categories” têm relação muitos-para-muitos
      • Não espere que a IA deduza isso sozinha
    • Se uma biblioteca específica for traiçoeira, documente também armadilhas comuns e pontos de atenção
    • É uma forma de incorporar sua mentoria à especificação
      • Ex.: “ao usar a biblioteca X, existe um problema de vazamento de memória na versão Y, então aplique a solução alternativa Z”

  • Minimalismo para tarefas simples

    • Embora especificações rigorosas sejam importantes, parte da expertise é saber quando simplificar
    • Em tarefas relativamente simples e isoladas, uma especificação excessiva pode acabar gerando mais confusão
    • Ex.: em uma tarefa como “centralizar uma div na página”
      • Algo como “mantenha a solução concisa e não adicione markup ou estilos desnecessários” já é suficiente
    • Em contrapartida, tarefas complexas como “implementar um fluxo OAuth com renovação de token e tratamento de erros” exigem uma especificação detalhada
    • Um critério prático é ajustar a densidade da especificação à complexidade da tarefa

  • Mantenha o ser humano como filtro final de qualidade

    • A especificação delega autoridade ao agente, mas a responsabilidade final pela qualidade continua sendo do desenvolvedor
    • Mesmo que o agente tecnicamente cumpra a especificação, confie no seu próprio julgamento se a solução não parecer certa ou não se encaixar no contexto
    • Se necessário, refinar a especificação de novo ou ajustar manualmente o resultado é uma parte natural do processo
    • Willison compara trabalhar com agentes de IA a “uma forma muito estranha de gestão” e diz que isso “se parece de forma desconfortável com gerenciar um estagiário humano”
    • No fim, o papel de fornecer instruções claras (a especificação), contexto suficiente e feedback acionável continua sendo humano

Princípio 5: testar, iterar e evoluir a especificação (usando as ferramentas certas)

  • Encare a escrita da especificação e a construção do agente não como uma tarefa feita de uma vez só, mas como um loop iterativo
    • Um fluxo de testar rápido, coletar feedback, refinar a especificação e automatizar verificações com ferramentas
  • A especificação inicial não é a versão final, mas o ponto de partida do ciclo

  • Testes contínuos

    • Não espere toda a implementação terminar; faça testes ou verificações manuais simples em marcos importantes ou no nível de função
    • Se uma falha for encontrada, não siga em frente como se nada tivesse acontecido; primeiro ajuste a especificação ou o prompt
    • Testes automatizados são especialmente eficazes e, se existirem, você pode fazer o agente executar diretamente comandos como npm test
    • Use o resultado bruto da falha no teste como entrada do próximo prompt
      • Ex.: “A saída não atende à especificação em X, Y e Z, então corrija isso”
    • O loop agêntico de código → teste → correção → repetição é uma abordagem muito poderosa

  • Iteração da própria especificação

    • Se ficar claro que o agente entendeu errado ou que faltou algum requisito, não encubra o problema; corrija primeiro o documento da especificação
    • Sincronize explicitamente a especificação revisada com o agente
      • Ex.: “Atualizei a especificação da seguinte forma. Ajuste o plano ou refatore o código para refletir essa mudança”
    • Mantenha a especificação sempre como a única fonte de verdade
    • Se possível, registre o histórico de versões em mensagens de commit ou notas para rastrear o que mudou e por quê

  • Gerenciamento de contexto e uso de ferramentas de memória

    • O ecossistema de ferramentas para ajudar no gerenciamento de contexto e conhecimento de agentes de IA está crescendo rapidamente
    • Ao usar o padrão RAG (geração aumentada por recuperação), o agente pode buscar imediatamente só as informações necessárias em uma base de conhecimento, como um banco de dados vetorial
    • Se a especificação for muito grande, você pode gerar embeddings das seções e configurar o agente para buscar apenas as partes mais relevantes, em vez de receber tudo
    • Frameworks baseados em MCP (Model Context Protocol) fornecem automaticamente o contexto adequado para a tarefa atual
    • Ferramentas como Context7(context7.com) carregam automaticamente snippets relevantes da documentação de acordo com o que está sendo feito

  • Paralelização com cautela

    • Alguns desenvolvedores aceleram o trabalho executando múltiplas instâncias de agentes em paralelo em tarefas diferentes
    • Ex.: um agente gera código enquanto outro escreve testes ao mesmo tempo
    • Se você optar por esse método, as tarefas precisam ser realmente independentes ou claramente separadas para evitar conflitos
    • Ex.: imponha restrições para que dois agentes não editem o mesmo arquivo ao mesmo tempo
    • Para reduzir a sobrecarga de gerenciamento, no começo é mais realista trabalhar com no máximo 2 ou 3 agentes

  • Controle de versão e bloqueio da especificação

    • Acompanhe cuidadosamente o trabalho do agente com ferramentas de controle de versão como Git
    • Quanto mais você usa IA, mais importantes ficam os bons hábitos de controle de versão
    • Faça commit do próprio arquivo de especificação no repositório para manter o histórico de mudanças
    • O agente também consegue ler git diff ou blame e entender o contexto das mudanças
      • Na prática, LLMs são bastante competentes em interpretar diff
    • Ao manter a especificação no repositório, tanto desenvolvedores quanto IA podem acompanhar juntos a evolução do projeto
    • Willison descreve os modelos como “furiosamente competentes em Git”

  • Considerações de custo e velocidade

    • Trabalhos com modelos grandes e contexto longo podem ser lentos e caros
    • Separe estrategicamente a escolha de modelos
      • Para rascunhos iniciais ou trabalho iterativo, use modelos rápidos e baratos
      • Para saída final ou raciocínio complexo, use o modelo mais competente (e mais caro)
    • Ex.: GPT-4 ou Claude para planejamento e etapas centrais; expansão simples ou refatoração podem ficar com modelos locais ou APIs menores
    • Agentes de execução de testes ou de lint podem funcionar bem com modelos relativamente menores
    • O tamanho do contexto também precisa ser gerenciado

  • Monitore e registre tudo

    • Em workflows complexos com agentes, os logs de comportamento e saída do agente são indispensáveis
    • Pelos logs, é possível verificar se o agente se desviou da intenção ou se ocorreu algum erro
    • Muitos frameworks oferecem logs de trace ou suporte para exibir o raciocínio etapa por etapa
    • Ao examinar os logs, fica claro onde a especificação ou a instrução foi mal interpretada

  • Aprendizado e melhoria

    • Trate cada projeto como uma oportunidade de aprendizado para aprimorar sua capacidade de escrever especificações
    • É possível observar se certas formulações confundem repetidamente a IA e que estruturas de especificação tendem a ser seguidas com mais consistência
    • Reflita ativamente essas lições nas próximas especificações
    • A área de agentes de IA está evoluindo rapidamente, e novas ferramentas e boas práticas continuam surgindo

Evitando erros comuns

  • A análise de mais de 2.500 arquivos de agentes no GitHub mostrou que a principal causa de falha é a ambiguidade excessiva nas especificações e instruções

  • Prompts vagos

    • Pedidos como “faça algo legal” ou “faça funcionar melhor” deixam o agente sem nenhum critério de julgamento
    • É preciso especificar da forma mais concreta possível as entradas, saídas e restrições
    • Designações genéricas de papel como “você é um assistente de programação útil” quase não têm efeito
    • Em contraste, algo como “você é um engenheiro de testes que escreve testes para componentes React, segue este exemplo e nunca modifica o código-fonte” funciona muito melhor porque define papel, escopo e restrições ao mesmo tempo

  • Contexto excessivo sem resumo

    • Despejar um documento de 50 páginas inteiro no prompt e esperar que o modelo entenda tudo sozinho quase sempre falha
    • É preciso usar resumo hierárquico ou RAG para expor apenas o que é diretamente relevante para a tarefa atual
    • Aumentar o tamanho do contexto não compensa a falta de qualidade do contexto

  • Pular a revisão humana

    • Regra pessoal de Willison: “não faço commit de código que eu não consiga explicar para outra pessoa”
    • Só porque o agente produziu algo que passa nos testes não significa que o código esteja automaticamente correto, seguro e fácil de manter
    • Especialmente em caminhos críticos de código, a revisão humana deve sempre acontecer
    • A metáfora da “casa de cartas” se encaixa bem no código gerado por IA: por fora ele pode parecer sólido, mas pode ruir em casos de borda não testados

  • Confundir vibe coding com engenharia de produção

    • A prototipagem rápida com IA, o chamado “vibe coding”, é adequada para fases exploratórias ou projetos pontuais
    • Colocar esse resultado em produção sem especificações rigorosas, testes e revisão tem grande chance de causar problemas
    • “Vibe coding” e “engenharia assistida por IA” devem ser claramente diferenciados; esta última exige a disciplina e os processos descritos neste guia
    • É importante ter consciência de em qual modo você está trabalhando no momento

  • Ignorar o “trio fatal”

    • As três propriedades que, segundo Willison, tornam agentes de IA perigosos
      • Velocidade: geram resultados mais rápido do que humanos conseguem revisar
      • Não determinismo: produzem saídas diferentes a cada execução, mesmo com a mesma entrada
      • Custo: incentivam atalhos em vez de validação suficiente
    • A especificação e o processo de revisão precisam ser projetados levando os três em conta
    • Em especial, é preciso controlar conscientemente para que a velocidade não ultrapasse a capacidade de verificação

  • Omissão das 6 áreas essenciais

    • Se a especificação não cobrir Commands, Testing, Project Structure, Code Style, Git Workflow e Boundaries, o agente tende a perder informações importantes para executar o trabalho
    • Antes de passar a tarefa ao agente, é mais seguro fazer uma última revisão com a checklist das 6 áreas

Conclusão

  • Escrever especificações eficazes para agentes de codificação com IA exige combinar princípios sólidos de engenharia de software com uma compreensão das características dos LLMs e uma abordagem ajustada a elas
  • Tudo começa com a definição clara do objetivo, e então a divisão de papéis para que a IA expanda o plano e os detalhes com base nisso
  • A especificação não deve ser tratada como um memorando, mas como um documento de projeto sério, incluindo 6 áreas centrais e sendo tratada como um artefato executável conectado à toolchain
  • Em vez de fornecer tudo de uma vez, divida e entregue por unidade de trabalho para manter o foco do agente
    (TOC resumido, subagentes e orquestração paralela são meios práticos para lidar com especificações de grande porte)
  • Com os limites em 3 níveis (Always / Ask first / Never), autoverificação e testes de adequação, é possível bloquear com antecedência as armadilhas em que a IA tende a cair
  • O ponto-chave é tratar a especificação e a implementação não como resultados fixos, mas como um processo iterativo, refinando continuamente especificação e código juntos por meio de testes e feedback
  • Seguindo essas diretrizes, é possível reduzir de forma perceptível a chance de o agente de IA se perder em contextos amplos ou descambar para alucinações

Leituras relacionadas

3 comentários

 
gomjellie 2026-01-22

Embora seja uma tradução por IA, existe uma versão em coreano, então estou compartilhando o link.

https://rosetta.page/post/…
 
qor0923 2026-01-20

Obrigado.
 
googol 2026-01-19

Pessoalmente, quando desenvolvi um projeto com SDD (Specs Driven Development), no início senti um ganho claro de produtividade, mas como ainda não dá para escrever todo o código com base em especificações e, sempre que é preciso fazer ajustes manuais, é necessário atualizar o código e a especificação juntos, acabei tendo a experiência de uma queda de produtividade.