Pular para o conteúdo
LabS Atlas
Agentic AI
Entrar

Arquivos de Contexto de Agentes de Código

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Arquivos de contexto de agentes de código são arquivos markdown no repositório, como o CLAUDE.md, que o agente lê sempre para conhecer stack, convenções, decisões e escopo do projeto.

Eles são a frente de contexto do harness. Um agente que começa numa pasta vazia não sabe que banco usar, que framework de front-end preferir, se o sistema vai para produção ou é só um protótipo. Sem essa informação, ele decide sozinho, e decide diferente a cada execução. Os arquivos de contexto transformam essas escolhas em texto fixo, versionado junto com o código, que acompanha toda interação com o modelo. Funcionam como prompts melhorados e permanentes: o time escreve uma vez e o agente consulta sempre.

Arquivo raiz e arquivos temáticos

No Claude Code, o arquivo principal é o CLAUDE.md. A própria ferramenta o gera a partir do projeto, e ele costuma receber poucas edições manuais, apenas pontos específicos que o time quer garantir. Ele é enviado junto em toda chamada, até numa simples saudação, e descreve o que o projeto é e o que não é, as stacks, as skills disponíveis e onde estão as specs.

O arquivo raiz não precisa carregar tudo. Ele aponta para arquivos temáticos, e o agente vai até eles quando a tarefa pede aquele assunto. Exemplos de uma estrutura desse tipo:

  • Convenções: padrões de código que o time quer ver seguidos.
  • Stacks: tecnologias, versões e até o provedor de IA do próprio sistema, para o agente não se perder ao pesquisar ou escolher dependências.
  • O que o projeto não é: num boilerplate para MVPs, deixa explícito que não haverá produção nem autenticação. Sem isso, o agente trata o projeto como produção e implementa testes extensivos, autenticação e autorização que ninguém pediu.
  • Design: telas exportadas de uma ferramenta de protótipo como o Google Stitch, entregues em HTML e não só como imagem, para que o layout seja reproduzido fielmente em vez de reinventado.
  • Regras por domínio: um arquivo só para banco de dados, por exemplo, lido apenas quando a tarefa toca o banco.

Esses arquivos não são padronizados: cada projeto define os que precisa. Skills, agentes e suas memórias seguem a mesma lógica e podem existir localmente, na pasta do projeto, ou globalmente, na pasta do usuário, valendo para qualquer projeto.

Contexto que sobrevive ao histórico

Um projeto construído em cerca de 40 minutos teve o histórico de chat perdido, de tão grande que ficou. Não fez falta: o prompt inicial tinha sido só pedir para implementar o design seguindo as specs. Banco, front-end, back-end e estética já estavam definidos nos arquivos de contexto e nas specs do SDD. O conhecimento do projeto estava no repositório, não na conversa.

O custo de um arquivo inchado

Como o arquivo raiz é lido em toda sessão, cada linha dele ocupa janela de contexto e gasta tokens. Se ele cresce demais, ou se o modelo tem janela pequena, o agente pode nem conseguir processar a pergunta do usuário. Um modelo local, menos potente, ao abrir um projeto preparado para o Claude Code, leu o CLAUDE.md, ficou sobrecarregado com o volume e desistiu da tarefa. Por isso vale separar por assunto: o que não é necessário em toda chamada vai para um arquivo temático.

Sugestão, não barreira

Um arquivo de contexto orienta, mas o agente pode ignorá-lo. Regra que não pode ser quebrada precisa de hooks, que são código executado.

Convenções que se repetem entre ferramentas

O Claude Code usa CLAUDE.md; o OpenCode usa AGENTS.md com o mesmo papel. As convenções de fundo (regras de projeto, agentes, skills, tools) são compatíveis o bastante para que o OpenCode trabalhe num projeto estruturado para o Claude Code sem renomear pastas nem arquivos. O caminho inverso também funciona: criar um link simbólico da pasta de configuração do Claude Code para a pasta de agentes já existente fez as skills antigas aparecerem sem retrabalho. A exceção são os servidores MCP, configurados na própria ferramenta e não num arquivo compartilhado, que precisam ser refeitos na troca. Assim, o investimento em contexto não fica preso a um fornecedor.