📝A anatomia de um arquivo de instruções que funciona
Aakash Gupta passou meses iterando o arquivo CLAUDE.md - o documento que o Claude Code lê em cada mensagem que você manda, não só na primeira - e abriu publicamente o que aprendeu. O mesmo padrão serve pra outros agentes que dependem de arquivo de instruções, como Cursor, Codex CLI, Cline e companhia. --- Ele divide o arquivo em seis seções fixas: quem você é (nome, função, foco do trimestre), como você trabalha (estilo de comunicação, gatilhos como 'quando eu disser sobe um sub-agente, delegue'), suas ferramentas (quais CLIs e MCPs estão instaladas), prioridades atuais (as três coisas que importam essa semana), skills (atalho pra pasta de habilidades) e preferências (formatação, tom, estilo de saída). --- O truque mais importante é o que ele chama de efeito composto: toda vez que o agente faz algo errado, você pega a correção e cola no CLAUDE.md como regra fixa. Em poucos meses o arquivo vira um manual extremamente preciso de como você gosta de trabalhar. Os erros mais comuns: deixar o documento gigante (depois de 100 linhas o agente começa a ignorar), não atualizar nunca, e escrever instrução genérica tipo 'seja útil'. Regra com gatilho específico pega - frase vaga não pega.
The CLAUDE.md file loads into context for every single message you send in Claude Code. Not the first message. Every message. Most people either skip it entirely or fill it with generic instructions that waste tokens. After iterating on mine over 100 times, here's what actually moves the needle. Six sections. Who you are (name, role, team, current quarter focus). How you work (communication style, delegation triggers like "when I say spin up, delegate to a sub-agent"). Your tools (which CLIs are installed, which MCPs are active). Current priorities (the 3 things that matter this week). Skills (pointer to your skills folder). Preferences (formatting, tone, output style). The compounding trick is what separates a good CLAUDE.md from a great one. Every time Claude Code does something wrong, you pull the fix into CLAUDE.md. "Always use Jupyter notebooks for data analysis." "Check /knowledge/people/ before drafting any message." "Do not run research in the main session." Over months, this file becomes an incredibly precise instruction set. Claude feels like it already knows you. Dave Killeen, the CPO at Pendo, told me his Claude Code system built on this foundation is better than the human executive assistant he used to have. The common mistakes: making it too long (Claude ignores noise after 100 lines), not updating it weekly, vague preferences like "be helpful" or "be concise." What actually works: specific rules with clear triggers. "When I say spin up, delegate to a sub-agent." "Use Jupyter notebooks for any data analysis." "Check knowledge/people before drafting." If you only set up one file, make it this one.
— @aakashgupta View on X
O arquivo CLAUDE.md é carregado no contexto de **todas** as mensagens enviadas ao Claude Code, não apenas na primeira interação. Essa distinção técnica transforma o documento no ponto de configuração mais crítico para quem trabalha com o agente da Anthropic: ele funciona como um system prompt persistente, moldando cada resposta sem necessidade de repetição.
A arquitetura das seis seções
Aakash Gupta, product leader que iterou seu arquivo mais de 100 vezes, estrutura o documento em seis campos obrigatórios:
- **Identidade**: nome, função, time e foco do trimestre
- **Protocolos de trabalho**: estilo de comunicação e gatilhos específicos (ex: "quando eu disser 'spin up', delegue a um sub-agente")
- **Stack técnico**: CLIs instaladas e MCPs (Model Context Protocols) ativos
- **Prioridades**: as três iniciativas que importam na semana atual
- **Habilidades**: ponte para past