~$ cat ./dossies/claude-code-agents-memory-skills.md
Claude Code: agents.md, memory.md, skills.md — como eles funcionam juntos
Claude Code permite estender o Claude com arquivos de configuração que transformam interações pontuais em agentes de IA duradouros. Os principais arquivos são agents.md, memory.md e skills.md, cada um com função específica na arquitetura.
Compreender como essas camadas interagem é essencial para desenvolvedores que desejam construir sistemas confiáveis e escaláveis. Este artigo detalha o papel de cada arquivo, sua integração e exemplos práticos de uso.
Função de agents.md
O arquivo agents.md contém instruções de projeto que orientam o comportamento geral do agente. Ele define objetivos, restrições e contexto inicial que o Claude deve seguir em todas as interações.
Essas instruções atuam como um contrato de alto nível, garantindo consistência mesmo quando o agente é invocado em diferentes sessões ou contextos.
Developers utilizam agents.md para especificar regras de negócio, tom de resposta e limites éticos do sistema.
Memória persistente com memory.md
memory.md armazena informações que precisam sobreviver entre sessões separadas. O Claude lê e atualiza esse arquivo automaticamente para manter estado.
Essa camada resolve o problema de esquecimento típico em conversas longas ou reiniciadas, permitindo que o agente recorde fatos, decisões e progresso.
O formato costuma ser estruturado em seções claras para facilitar leitura e edição manual quando necessário.
Capacidades reutilizáveis em skills.md
skills.md define habilidades modulares que podem ser acionadas por comandos ou condições específicas. Cada skill descreve passos, ferramentas e critérios de sucesso.
Essas habilidades são reutilizáveis em múltiplos agentes e projetos, promovendo DRY na construção de sistemas baseados em LLM.
O arquivo permite versionamento e compartilhamento entre equipes, aumentando a produtividade.
Como as três camadas se combinam
agents.md fornece o contexto e as regras, memory.md mantém o estado e skills.md oferece ações concretas. O Claude consulta os três arquivos em sequência lógica durante a execução.
Essa arquitetura em camadas permite separar preocupações: instruções de alto nível, memória de longo prazo e execução de tarefas.
Quando bem integradas, as camadas reduzem alucinações e aumentam a confiabilidade do agente em tarefas complexas.
Melhores práticas de estruturação
Mantenha agents.md conciso e focado em objetivos, evitando detalhes de implementação que pertencem a skills.md.
Use seções nomeadas em memory.md para facilitar buscas e atualizações automáticas pelo modelo.
Documente cada skill com exemplos de invocação e resultados esperados para garantir reutilização efetiva.
Exemplos de workflow concretos
Um agente de suporte pode usar agents.md para definir tom corporativo, memory.md para registrar tickets anteriores e skills.md para ações como criar chamados ou consultar base de conhecimento.
Em desenvolvimento de software, agents.md orienta padrões de código, memory.md guarda decisões de arquitetura e skills.md encapsula tarefas como refatoração ou testes.
Workflows de pesquisa combinam as três camadas para coletar dados, armazenar descobertas e gerar relatórios de forma iterativa.
para lembrar
- agents.md estabelece o contrato de comportamento do agente de forma permanente.
- memory.md permite continuidade de estado sem depender de contexto da janela de tokens.
- skills.md transforma ações repetitivas em módulos versionáveis e reutilizáveis.
- A integração das três camadas reduz erros e aumenta a previsibilidade do agente.
- Estrutura clara nos arquivos facilita manutenção e colaboração em equipe.
perguntas frequentes
O que é agents.md no Claude Code?
agents.md contém instruções de projeto que definem objetivos, restrições e contexto inicial do agente. Ele funciona como camada de alto nível que orienta todas as respostas do Claude.
Como memory.md mantém estado entre sessões?
memory.md é lido e atualizado automaticamente pelo Claude para armazenar fatos, decisões e progresso. Isso permite que o agente lembre informações mesmo após reinício da conversa.
Para que serve skills.md?
skills.md define capacidades reutilizáveis que podem ser acionadas por comandos. Cada skill descreve passos, ferramentas e critérios, facilitando modularidade e reutilização.
Como as três camadas trabalham juntas?
agents.md fornece regras, memory.md mantém memória e skills.md executa ações. O Claude consulta os arquivos em sequência para produzir respostas consistentes e persistentes.
