Regras de Projeto para AI Coding: AGENTS.md, CLAUDE.md, Cursor Rules e Specs
Entenda como AGENTS.md, CLAUDE.md, Cursor Rules, MCP, specs e gates de verificação dividem responsabilidades — para que agentes continuem úteis sem dominar seu release.
Ferramentas de AI coding se comportam melhor quando o repositório explica como o trabalho deve ser feito. Essa orientação aparece como AGENTS.md, CLAUDE.md, Cursor Rules, configs de MCP, specs e gates de verificação.
Esses arquivos são instruções e contratos. Não substituem a revisão humana nem um build verde.
Resposta direta
| Artefato | Função principal |
|---|---|
AGENTS.md / CLAUDE.md / Cursor Rules | Informar aos agentes convenções do projeto, limites e comandos preferidos |
| Specs / briefs de tarefa | Definir o que significa "pronto" para uma mudança |
| Configs de MCP / ferramentas | Controlar quais ferramentas externas um agente pode chamar |
| Gates de verificação | Comprovar a mudança com testes, builds, lint e checklists de revisão |
Use regras curtas e aplicáveis. Textos longos que ninguém atualiza se tornam ruído ignorado.
Para builders não técnicos, comece com vibe coding sem perder o controle. Para checagens de release, use a checklist de fluxo.
Quando este guia ajuda
- Seus agentes continuam editando as pastas erradas ou inventando novos padrões.
- O time discorda sobre qual arquivo de instrução é a autoridade.
- Você quer habilitar o MCP sem conceder poder ilimitado de rede ou repositório.
- Você precisa de uma linha clara entre "orientação do agente" e "requisitos de merge".
Explore plugins e skills relacionados no diretório de plugins de AI Coding.
Arquivos de instrução: limites, não magia
AGENTS.md
Comumente usado como um brief de agente em nível de repositório: stack, estrutura, comandos obrigatórios, ações proibidas e links para documentação mais profunda.
Bom conteúdo:
- Gerenciador de pacotes e versão exigida de Node/Java/Python
- Como rodar testes e lint
- Pastas que os agentes devem evitar
- Como nomear PRs ou commits
Conteúdo ruim:
- Marketing copiado e colado sobre o produto
- Segredos e URLs de produção
- Regras contraditórias que ninguém mantém
CLAUDE.md
Frequentemente usado para orientação de projeto direcionada ao Claude. Trate como o AGENTS.md: mantenha atualizado, específico e curto. Se ambos existirem, defina qual arquivo prevalece para regras compartilhadas, ou mantenha-os sincronizados de forma deliberada.
Cursor Rules
Cursor Rules são tipicamente instruções escopadas ao editor/agente (regras de projeto ou de usuário). Use-as para:
- Estilo de código e convenções de framework
- "Sempre rode X antes de declarar pronto"
- Caminhos que precisam de cuidado extra (auth, faturamento, migrations)
Não esconda política de segurança crítica apenas em uma regra de usuário pessoal se colegas de equipe não puderem vê-la.
Specs e partes de tarefa
Specs respondem o quê construir e como aceitar. Regras respondem como os agentes devem se comportar enquanto constroem.
Uma mini-spec útil inclui:
- Resultado visível para o usuário
- Fora de escopo
- Arquivos ou áreas provavelmente afetados
- Passos de teste ou verificação manual
- Nota de rollback se for arriscado
Agentes sem uma spec inventam escopo. Humanos sem uma spec discutem depois do fato.
MCP e acesso a ferramentas
MCP (e pontes de ferramentas similares) permitem que agentes chamem sistemas externos. Isso é poderoso e perigoso.
Antes de habilitar ferramentas:
- Prefira acesso somente leitura primeiro
- Faça allowlist de hosts e comandos quando possível
- Nunca cole segredos de produção em configs de MCP versionadas no git
- Registre quais ferramentas rodaram para mudanças não triviais
Configuração de MCP é controle de capacidade, não documentação de produto.
Gates de verificação
Regras podem dizer "rode os testes". Gates exigem evidência:
npm test/npm run build(ou equivalentes do seu stack)- Lint e typecheck quando aplicável
- Revisão do diff em busca de segredos e mudanças de arquivo inesperadas
- Checklists como revisão de código de IA e checklist de ship
Veja também gates de verificação para agentes de AI coding.
Sem gate verde → sem "pronto".
Uma ordem prática de configuração
- Escreva um
AGENTS.mdde uma página (ou equivalente) com comandos e zonas proibidas. - Adicione Cursor Rules /
CLAUDE.mdapenas para extras específicos de ferramenta; evite guerras de duplicação. - Exija uma spec curta para qualquer tarefa não trivial.
- Habilite ferramentas de MCP de forma restrita.
- Faça o merge depender de gates de verificação, não da confiança do agente.
Limites
- Nomes de arquivo e recursos de produto evoluem; verifique a documentação atual do Cursor, Claude Code, Codex e outros.
- Regras não conseguem corrigir propriedade de produto ambígua.
- Conjuntos de regras longos demais são ignorados — prefira links para documentos vivos em vez de colar tudo.
FAQ
Preciso de todos os tipos de arquivo?
Não. Comece com um brief autoritativo mais specs para tarefas reais. Adicione arquivos específicos de ferramenta quando um produto precisar deles.
Onde os segredos devem ficar?
Em configuração de ambiente e gerenciadores de segredos — não em arquivos de regras, prompts ou configs de MCP versionadas.