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.
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:
- qual é o produto e quais apps existem?
- quais comandos validam uma mudança?
- onde estão os contratos, schema e rotas importantes?
- quais segredos e dados o agente nunca deve abrir ou registrar?
- quais ações exigem aprovação humana?
# 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.
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:
- entidades e estados já existentes;
- arquivos que precisam mudar;
- regras de autorização;
- critérios de aceite;
- 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.
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 testeO 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.
[ CONTEÚDO_INTEGRAL_DISPONÍVEL ]
Continuar: transforme um fluxo validado em skill reutilizável CLIQUE PARA DESBLOQUEAR A LEITURA
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
Construindo aplicações robustas com arquitetura de alto nível e infraestrutura otimizada na edge do Cloudflare Workers com SurrealDB.
Segurança de dados e conformidade com privacidade desde o primeiro dia de código com tratamento de estados e sessões resilientes.
Métricas de performance para monitorar a experiência do usuário e otimizar custos operacionais em produção com dashboards estruturados.
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:testeem 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.
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:
- resumo por arquivo;
- testes executados e resultado;
- comportamento que não foi coberto;
- 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.mdna 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.
