Como Construir Agentes de Código Autoaperfeiçoantes

“Se tenho que repetir a mesma preferência toda sessão, não estou desenvolvendo com IA — estou fazendo babá de um estagiário muito rápido.”

Essa frase de Eric Ma, Principal Data Scientist na Moderna, captura um problema que a maioria dos desenvolvedores enfrenta mas poucos discutem: agentes de IA são tratados como ferramentas descartáveis. Cada sessão começa do zero, sem memória do que funcionou antes.

O resultado? Repetição constante de instruções, correção dos mesmos erros, e produtividade que estabiliza sem evolução contínua.

A Tese Central: Melhoria Operacional, Não do Modelo

A verdadeira melhoria de agentes acontece através de mudanças no ambiente, não em atualizações do modelo.

Pense assim: os pesos do modelo não mudam no meio da semana. Se você quer que seu agente melhore entre segunda e sexta, a melhoria precisa vir de outro lugar — do ambiente que você constrói ao redor dele.

Quando um agente comete um erro ou toma um caminho indesejado, o feedback precisa persistir. Isso requer infraestrutura deliberada.

O insight central: trate a melhoria de agentes como runbooks operacionais — documentando passos repetíveis e aprendizados pós-incidente, convertendo linguagem natural em chamadas de ferramentas acionáveis.

Dois Mecanismos Principais

O framework de Eric Ma propõe dois mecanismos complementares:

AGENTS.md: A Memória do Repositório

AGENTS.md é um arquivo de instruções para agentes de IA, versionado junto com o código. Pense como um README para agentes: enquanto README.md é para humanos, AGENTS.md contém o contexto detalhado que agentes precisam — comandos de build, testes, convenções.

Mais de 20.000 repositórios no GitHub já usam AGENTS.md. O GitHub Blog analisou 2.500+ repositórios para identificar padrões de sucesso.

O arquivo serve duas funções principais:

Navegação: Um mapa do código que ajuda agentes a localizar arquivos relevantes sem buscas exaustivas. Um mapa de código reduziu tempo de busca de 40+ segundos para 2 segundos, eliminando 5-6 operações de busca.

Normas Locais: Regras específicas do repositório que previnem erros repetidos. “Execute Python através do contexto pixi: pixi run python ...”. “Nunca modifique testes para fazê-los passar artificialmente.”

Skills: Playbooks Reutilizáveis

Skills são pastas organizadas de instruções, scripts e recursos que agentes podem descobrir e carregar dinamicamente. Funcionam como “compressão de prompts” — playbooks reutilizáveis que eliminam explicações repetitivas de workflows.

Estrutura básica: uma pasta contendo um arquivo SKILL.md (o prompt) e assets/scripts relacionados (a camada de ferramentas).

Uma boa skill explicita três elementos:

1. Quando usar: Condições claras de acionamento
2. Quais passos seguir: Procedimentos específicos do workflow
3. Como é uma boa saída: Resultados esperados e padrões de qualidade

Boas Práticas para AGENTS.md

A análise do GitHub de 2.500+ repositórios revelou padrões consistentes nos arquivos mais eficazes:

Mantenha Conciso: Objetivo de 150 linhas ou menos. Arquivos longos sobrecarregam o agente e enterram informação útil.

Seja Específico: “Você é um assistente útil” não funciona. “Você escreve testes para componentes React seguindo estes exemplos” funciona.

Comandos no Início: Coloque comandos executáveis cedo — npm test, pytest -v. Use backticks para cópia direta.

Use Arquivos Modulares: Coloque AGENTS.md em cada subpacote. Agentes leem o arquivo mais próximo na árvore de diretórios.

Itere com Base em Erros: Adicione uma regra na segunda vez que ver o mesmo erro. Não tente prever tudo antecipadamente.

Defina Limites Claros: O que nunca fazer — commitar secrets, modificar vendor, editar configs de produção.

Modelo de Três Níveis de Permissão

Defina claramente o que o agente pode, deve perguntar, e nunca deve fazer.

Sempre Fazer (verde): Escrever em diretórios específicos, rodar testes, seguir padrões de código.

Perguntar Primeiro (amarelo): Mudanças de schema, adição de dependências, alterações estruturais.

Nunca Fazer (vermelho): Modificar secrets, tocar configs de produção, remover testes falhando.

A análise do GitHub mostrou que “nunca commitar secrets” foi a restrição mais útil encontrada nos repositórios de sucesso. A OpenAI possui 88 arquivos AGENTS.md em seu repositório principal — um para cada contexto específico.

Exemplos Práticos de Skills

Debugging de CI: Sequência padronizada para falhas de CI — identificar jobs falhando, puxar logs, inspecionar diffs, reproduzir localmente, aplicar patch. Gatilho: “CI está falhando” ou “pipeline quebrou”.

Anúncios de Release: Reduziu tempo de composição de 30 minutos por release para segundos. Produz anúncios formatados para Teams/Slack com emojis padronizados. Gatilho: “Criar anúncio de release”.

Relatórios de ML: Documentação pós-treinamento usando formato IMRAD. Extrai dados de stdout, métricas, código, configs e diffs do git automaticamente. Gatilho: “Documentar experimento”.

Conhecimento de Domínio: Um especialista documentou seu conhecimento implícito de debugging de cromatografia como skill — tornando expertise tácito explícito e reutilizável. Gatilho: “Analisar cromatograma”.

O Modelo de Maturidade

Eric Ma propõe quatro estágios evolutivos de uso de agentes:

Estágio 0: Prompting Ad Hoc

Explicando conceitos repetidamente sem acúmulo sistemático de conhecimento. Cada sessão começa do zero.

Estágio 1: Memória Local do Repositório

Implementação de AGENTS.md como documentação específica do repositório que fornece guardrails e mapeamento de código.

Estágio 2: Skills Pessoais Globais

Workflows que se repetem em repositórios são elevados a skills reutilizáveis em toda a máquina do desenvolvedor.

Estágio 3: Skills Compartilhadas

Workflows de equipe são formalizados em locais compartilhados — comece local e promova após sentir a dor duas vezes.

Framework de Decisão

Quando usar AGENTS.md vs. criar uma skill?

Atualize AGENTS.md para:

• Orientação de navegação no código
• Normas e convenções locais
• Guardrails específicos do repositório
• Comandos de build e teste
• Restrições de segurança

Crie skills para:

• Procedimentos reutilizáveis de múltiplos passos
• Workflows entre repositórios
• Tarefas com contratos de saída estritos
• Conhecimento de domínio formalizado
• Automações que economizam tempo significativo

A regra de ouro: “Sinta a dor duas vezes” — só promova para skill quando encontrar a mesma necessidade repetidamente.

Considerações de Segurança

Arquivos de instrução de agentes são superfícies de ataque.

Pesquisas de segurança demonstraram que repositórios maliciosos podem conter instruções ocultas que fazem agentes executar comandos arbitrários — incluindo se propagar para outros repositórios. Um “vírus de IA” embutido em AGENTS.md pode instruir agentes a propagar-se automaticamente para outros repos que o desenvolvedor acessa.

Perguntas que precisam de resposta:

• Quem pode modificar AGENTS.md?
• Como auditar mudanças em instruções de agentes?
• Quais procedimentos de rollback existem?
• Como revisar skills antes do deploy?
• Quais são as implicações de compliance?

Segundo IBM e KPMG, 80% dos líderes empresariais citam cibersegurança como a maior barreira para estratégia de IA.

Esclarecendo “Autoaperfeiçoamento”

O mecanismo descrito é melhoria mediada por humanos, não modificação autônoma.

O humano identifica o padrão, escreve a instrução, e faz o commit. O agente não se aprimora sozinho — ele opera dentro de um ambiente que humanos deliberadamente melhoram.

A vantagem: explícito sobre implícito. AGENTS.md é curado, auditável e controlável, diferente de memória de chat que evolui de forma opaca.

Mudanças ambientais criam estado oculto. Um novo membro da equipe herda instruções que não escreveu e pode não entender. Documentação e onboarding precisam acompanhar.

A Habilidade Mais Valiosa

“A skill mais valiosa é metacognição — a prática deliberada de observar qual trabalho se repete e sistematizá-lo.”

O ciclo é simples:

1. Observe: Preste atenção em padrões de comportamento do agente
2. Identifique: Caminhos complicados, arquivos perdidos, refatorações desnecessárias
3. Sistematize: Codifique o aprendizado em AGENTS.md ou skill

Como Começar

Passo 1: Crie seu primeiro AGENTS.md

Comece com comandos de build/teste e um mapa básico das pastas principais. Mantenha abaixo de 100 linhas. Inclua entry points do sistema, convenções de nomes, e onde ficam os testes.

Passo 2: Observe e Itere

Use o agente normalmente e preste atenção em padrões problemáticos — caminhos muito complicados, arquivos relevantes não encontrados, refatorações globais quando cirúrgicas bastam.

Passo 3: Adicione Regras na Segunda Ocorrência

Quando ver o mesmo erro duas vezes, adicione ao AGENTS.md. Seja específico sobre o problema, inclua exemplo do comportamento esperado, mantenha conciso.

Passo 4: Promova para Skill Quando Maduro

Workflows que se repetem entre projetos viram skills. Documente quando usar, passos a seguir, e como é uma boa saída.

Conclusão

Seu agente não está ficando mais inteligente. Você está apenas se repetindo.

A diferença entre usar IA e desenvolver com IA está na infraestrutura de aprendizado que você constrói ao redor. O problema difícil não é o modelo — é o sistema.

AGENTS.md para contexto local, Skills para workflows reutilizáveis, e metacognição para identificar o que sistematizar. Esse é o caminho de maturidade que separa times que usam IA de times que desenvolvem com IA.

---

No Victorino Group, ajudamos times a implementar sistemas de IA com governança e resultados reais. Se você quer acelerar seu desenvolvimento sem perder controle, vamos conversar.