# Hermes Agent para vibe coding: contexto, AGENTS.md e autonomia com método > Use AGENTS.md e arquivos de contexto para fazer o Hermes Agent entender seu produto, respeitar limites e transformar vibe coding em um processo revisável. **Autores:** Mauro Mequelussi **Publicado:** 2026-07-19T12:00:00.000Z **Atualizado:** 2026-07-20T15:00:47.070211276Z **Tags:** hermes-agent, agentes-de-codigo, agents-md, vibe-coding, engenharia-de-software --- Vibe coding funciona melhor quando a IA recebe contexto que parece uma boa passagem de trabalho: o que o produto faz, quais são as regras, onde ficam os arquivos, como testar e o que ela não pode mudar. Sem isso, o agente tende a produzir uma aplicação plausível em uma pasta que talvez nem pertença ao seu sistema. O Hermes Agent resolve parte desse problema porque reconhece arquivos de contexto de projeto. Para um produto real, `AGENTS.md` deixa de ser uma nota para humanos e vira uma interface entre sua arquitetura e o agente que vai operar sobre ela. ## O que Hermes Agent lê no seu projeto? Hermes procura arquivos como `.hermes.md`, `AGENTS.md`, `CLAUDE.md` e regras do Cursor. A prioridade começa em `.hermes.md`; quando ele não existe, `AGENTS.md` é a referência principal. Conforme o agente entra em subdiretórios, ele também pode descobrir instruções mais específicas, sem carregar todo o repositório de uma vez. Isso é útil porque um monorepo raramente tem uma única regra. O Portal pode usar Nuxt, a API pode usar Hono, o banco pode ter rollouts e o painel administrativo pode exigir permissões próprias. O agente precisa descobrir a regra no lugar em que ela vale. ::callout{type="info" title="Contexto não é prompt mágico"} Um arquivo de contexto não substitui testes nem revisão. Ele reduz ambiguidade: explica o que já existe para que o agente não tente reinventar a arquitetura. :: ## O AGENTS.md que ajuda um agente de verdade Um bom arquivo de contexto é curto o suficiente para ser lido e específico o suficiente para orientar decisões. Ele responde cinco perguntas: 1. qual é o produto e quais apps existem? 2. quais comandos validam uma mudança? 3. onde estão os contratos, schema e rotas importantes? 4. quais segredos e dados o agente nunca deve abrir ou registrar? 5. quais ações exigem aprovação humana? ::code-demo{language="md" filename="AGENTS.md"} ```md # Contexto do projeto Aplicação de agenda para pequenos negócios brasileiros. ## Arquitetura - `apps/web`: Nuxt, interface do cliente; - `apps/api`: Hono, regras e integrações; - `packages/db`: schema e rollouts do SurrealDB. ## Regras obrigatórias - Leia a rota e o contrato antes de editar a interface. - Não altere migrations ou rollouts existentes. - Não leia `.env`, arquivos de credencial ou dados reais. - Não faça deploy, push ou publicação sem confirmação explícita. - Antes de concluir, rode `pnpm lint` e os testes afetados. ## Como trabalhar 1. Explique o plano e os arquivos que pretende alterar. 2. Faça mudanças pequenas e coerentes. 3. Mostre testes executados, riscos e pendências. ``` :: Esse documento não precisa explicar cada função. Ele precisa apontar as fronteiras. Código, testes e documentação específica continuam sendo a fonte para detalhes. ## Um fluxo de vibe coding em quatro fases O erro comum é pedir uma funcionalidade inteira em uma frase e deixar o agente decidir o resto. Um fluxo melhor divide descoberta, proposta, implementação e verificação. | Fase | Pedido ao Hermes | Saída esperada | | --- | --- | --- | | descoberta | leia contexto, rota e contrato | resumo do que já existe | | proposta | liste arquivos, riscos e critérios | plano revisável | | implementação | altere só o escopo aprovado | diff pequeno e explicado | | verificação | rode testes e revise o comportamento | evidências e limitações | Para uma tela de orçamento, por exemplo, não comece com “crie um CRM”. Comece pedindo que o Hermes encontre como clientes e propostas são modelados, identifique permissões e proponha a menor mudança viável. A construção vem depois do entendimento. ::prompt-snippet{title="Planejar antes de escrever código" model="Hermes Agent"} Leia AGENTS.md, a rota de orçamento e os testes relacionados. Quero permitir que um atendente salve um orçamento como rascunho. Entregue somente: 1. entidades e estados já existentes; 2. arquivos que precisam mudar; 3. regras de autorização; 4. critérios de aceite; 5. plano de implementação em ordem. Não altere arquivos, não instale dependências e não faça consultas em produção. :: ## Contexto local para regras locais Uma regra de front-end não deve contaminar o agente que está mexendo no banco. Crie arquivos de contexto em subdiretórios quando as regras divergem. ```text meu-produto/ ├── AGENTS.md # visão geral e regras globais ├── apps/web/AGENTS.md # componentes, acessibilidade e testes de UI ├── apps/api/AGENTS.md # autenticação, contratos e observabilidade └── packages/db/AGENTS.md # schema, rollouts e dados de teste ``` O ganho é previsibilidade. Ao ler `packages/db`, o agente aprende que uma mudança de campo exige rollout. Ao trabalhar em `apps/web`, ele aprende que não deve colocar uma chave administrativa no navegador. ::read-more{slug="skills-hermes-agent-aprender-fluxos" label="Continuar: transforme um fluxo validado em skill reutilizável" placement="mid_content"} ## Cenário brasileiro: produto com LGPD e WhatsApp Um app de atendimento pode guardar telefone, histórico de conversa, pedidos e dados financeiros. Um agente precisa saber que esses campos existem, mas não precisa receber uma exportação completa para criar uma tela. No contexto, descreva o princípio e faça o agente trabalhar com dados sintéticos: - use `cliente:teste` em exemplos; - não copie CPF, telefone ou conversa real para prompt, log ou issue; - prefira ambiente de desenvolvimento; - exponha apenas campos necessários a cada tarefa; - peça uma revisão de privacidade quando a mudança tocar coleta, retenção ou compartilhamento. Esse cuidado melhora também a qualidade do produto. O agente fica obrigado a perguntar onde uma operação acontece, quem pode executá-la e qual é o comportamento esperado em erro. ## Como pedir uma implementação sem perder o controle Depois de aprovar o plano, envie uma instrução que preserve decisões importantes. ::prompt-snippet{title="Implementar uma mudança aprovada" model="Hermes Agent"} Implemente apenas o plano aprovado para salvar orçamento como rascunho. Restrições: - mantenha os contratos atuais da API; - não altere schema ou migrations; - use o padrão de autorização existente; - crie ou ajuste testes para rascunho, acesso negado e validação; - não faça deploy, git push ou publicação. Ao terminar, mostre: 1. resumo por arquivo; 2. testes executados e resultado; 3. comportamento que não foi coberto; 4. qualquer decisão que precise de revisão humana. :: Uma instrução assim não deixa o agente “menos criativo”. Ela troca criatividade aplicada ao acaso por criatividade aplicada ao problema certo. ## O que não colocar no contexto Evite transformar o `AGENTS.md` em um cofre ou em uma documentação infinita. - não inclua tokens, chaves, URLs assinadas ou senhas; - não coloque dados de clientes, relatórios financeiros ou conversas privadas; - não escreva instruções que pedem para ignorar revisão e segurança; - não repita arquivos inteiros que o agente pode ler quando necessário; - não misture decisões temporárias com regras permanentes. Hermes faz varredura de arquivos de contexto para padrões comuns de injeção, mas essa proteção não elimina a necessidade de revisar arquivos recebidos de terceiros. Um repositório desconhecido pode conter instruções maliciosas disfarçadas de convenção técnica. ## Checklist para um projeto pronto para Hermes - [ ] existe um `AGENTS.md` na raiz; - [ ] os comandos de teste funcionam como estão escritos; - [ ] ambientes e dados de teste são separados de produção; - [ ] segredos ficam em variáveis e não em arquivos de contexto; - [ ] ações de deploy, pagamento e publicação exigem confirmação; - [ ] cada subdiretório crítico tem regras próprias quando necessário; - [ ] o agente recebe uma tarefa pequena antes de receber uma missão ampla. ## Perguntas frequentes ### Hermes usa AGENTS.md automaticamente? Sim, quando esse é o arquivo de contexto de maior prioridade disponível no projeto. A documentação também descreve descoberta progressiva de arquivos em subdiretórios à medida que o agente navega pelo código. ### Posso usar o mesmo AGENTS.md com Codex, Claude Code e Hermes? Sim. Esse é um bom motivo para manter regras portáveis e específicas do projeto. Evite instruções que dependem de uma interface ou ferramenta exclusiva quando a regra de engenharia é a mesma. ### Um contexto grande deixa o agente melhor? Nem sempre. Contexto excessivo aumenta custo e pode esconder a regra importante. Comece por arquitetura, limites e comandos; deixe detalhes para arquivos e docs que o agente lê na tarefa. ## Próximo passo Escreva um `AGENTS.md` de uma página, escolha uma funcionalidade pequena e peça somente o plano. Se o plano não refletir seu produto, melhore o contexto antes de dar poder de escrita. Essa é a forma mais barata de evoluir de vibe coding para uma rotina de engenharia assistida. ### Fontes e leitura recomendada - [Context Files no Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) - [Quickstart do Hermes Agent](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart/) - [Boas práticas oficiais](https://hermes-agent.nousresearch.com/docs/guides/tips/)