Guia de Arquivos de Convenção para Agentes de IA
Visão Geral
Este guia selecionado (curated guide) cobre os principais arquivos de convenção que agentes de IA modernos leem, escrevem e utilizam para entender projetos, aplicar regras e executar tarefas de forma confiável. Inclui formatos como AGENTS.md, CLAUDE.md, SKILL.md, llms.txt, configurações de servidores MCP (Model Context Protocol), regras personalizadas e exemplos práticos.
Arquivos de Convenção
AGENTS.md
Arquivo que especifica as habilidades (skills) e capacidades de um agente de IA, incluindo descrições de tarefas, dependências, gatilhos (triggers) e o comportamento esperado. É usado por plataformas como Claude Code, Cursor e Codex para registrar e compartilhar habilidades reutilizáveis.
CLAUDE.md
Arquivo de instrução para projetos Claude no Claude Code. Contém diretrizes, preferências de estilo, regras de projeto e restrições que o agente deve seguir ao interagir com a base de código. Pode incluir configurações de ferramentas, comandos de build/teste e convenções de projeto.
SKILL.md
Arquivo de documentação técnica detalhada de uma habilidade (skill) de agente. Geralmente inclui visão geral, pré-requisitos, guias de instalação, exemplos de código, comandos de linha de comando e boas práticas. É o manual principal para desenvolvedores e agentes executarem a skill.
llms.txt
Arquivo de texto otimizado para Large Language Models (LLMs) que fornece contexto de projeto, links para documentação relevante, exemplos de prompt, regras de comportamento e instruções de formatação. Ajuda a melhorar a compreensão e resposta de agentes de IA sobre o projeto.
MCP (Configurações de Servidores)
Configurações do Model Context Protocol, que definem servidores, ferramentas, recursos e regras de acesso que agentes de IA podem utilizar. Exemplo: servidores de banco de dados, APIs, sistemas de arquivos, busca web, etc. Definidos em formatos JSON ou YAML.
Regras Personalizadas (Rules)
Arquivos que definem regras específicas de conduta, validação ou transformação para agentes de IA. Podem ser escritas em linguagem natural, YAML, ou JSON, e são carregadas junto com o contexto do projeto.
Exemplos
Estrutura de um AGENTS.md
# Nome da Habilidade
## Descrição
Faz X, Y e Z.
## Plataformas Suportadas
- Claude Code
- Cursor
- Codex
## Gatilhos (Triggers)
- Quando o usuário menciona um arquivo .pdf
- Quando o usuário pede para extrair texto de PDF
- Quando o usuário pede para gerar um relatório PDF
Estrutura de um CLAUDE.md
# Instruções do Projeto MeuApp
## Objetivo
Este projeto é uma API REST em Python.
## Regras
- Sempre usar type hints.
- Testes obrigatórios para novas funcionalidades.
- Commits no formato conventional.
## Comandos
```bash
pip install -r requirements-dev.txt
pytest tests/
### Estrutura de um llms.txt
Documentação Principal
Regras de Comportamento
- Se for solicitado gerar código, deve-se usar TypeScript.
- As respostas devem ser concisas e em formato markdown.
## Boas Práticas
- **Organize por propósito**: Use `AGENTS.md` para habilidades, `CLAUDE.md` para instruções de projeto, `SKILL.md` para documentação técnica.
- **Mantenha atualizado**: Arquivos de convenção desatualizados podem confundir o agente.
- **Use exemplos**: Sempre inclua exemplos de uso prático.
- **Teste com seu agente**: Verifique se o agente lê e age conforme esperado.
- **Documente dependências**: Ferramentas, bibliotecas, APIs que o agente precisa usar.
## Referências
- [Documentação oficial do Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
- [Guia de Habilidades (Skills)](https://docs.anthropic.com/en/docs/claude-code/skills)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Repositório awesome-agent-conventions](https://github.com/ItamarZand88/awesome-agent-conventions)
## Próximos Passos
- Navegue pelos exemplos do repositório para ver implementações completas.
- Crie seus próprios arquivos de convenção usando os modelos fornecidos.
- Contribua com novos exemplos ou correções abrindo uma issue ou pull request.