A coisa mais cara de trabalhar com um agente é reexplicar o contexto. Toda manhã você reexplica as decisões de ontem, cola a última mensagem de commit, restabelece qual bug bloqueia o deploy. Multiplique por cada sessão e o custo oculto é de horas por semana, não minutos.
STATE.md elimina esse imposto. Um arquivo, atualizado no final de cada sessão, carregado no início da próxima. A disciplina: antes de fechar uma sessão, gaste três minutos atualizando o arquivo. Amanhã, esses três minutos economizam vinte.
STATE.md contém três coisas, nada mais.
Decisões: o que você decidiu e por quê. Sem o porquê, seu eu futuro reabre a decisão. "Triggers do Postgres em vez de cron para o resumo diário: triggers são transacionais, cron corre com o caminho de escrita."
Em andamento: o que está pela metade, específico o suficiente para ser entregue. "Migração 014 escrita em /migrations/014_add_subscription_columns.sql mas não aplicada. Deve ser executada antes que o manipulador de webhook entre em produção."
Bloqueadores: o que impede o progresso, incluindo o que você tentou. "Assinatura do webhook do Stripe falhando no ambiente de teste. Tentei o parser de corpo bruto, ainda 400. Próximo: verificar a variável de ambiente na prévia do Vercel."
Limite-o a 60-80 linhas. Quando algo for resolvido, remova-o. Quando algo for enviado, arquive-o.
A disciplina de atualização. Adicione um hook de Parada para se lembrar:
{
"hooks": {
"Stop": [
{
"command": "echo 'Antes de fechar: atualize STATE.md com decisões, itens em andamento e bloqueadores desta sessão.'"
}
]
}
}O lembrete sozinho não é suficiente; o hábito precisa ser automático. O caminho mais rápido: faça isso por cinco sessões consecutivas. Na sexta sessão, você se sentirá mal ao fechar sem atualizar. O desconforto é o sinal de que o hábito se formou.
MEMORY.md é o índice para tudo o que é durável. Cada entrada é uma linha apontando para um arquivo separado. Quatro tipos:
user_*: fatos duráveis sobre você: fuso horário, contexto de carreira, preferências. user_location.md
feedback_*: regras aprendidas com erros, com um campo de confiança. Comece em 0.3, aumente para 0.5 quando o padrão se repetir, promova para CLAUDE.md em 0.9+. feedback_public_endpoints_need_rate_limits.md
project_*: estado e decisões datadas para um projeto. Arquive quando for enviado. project_stripe_integration_2026_05.md
reference_*: tabelas de consulta para pessoas, ferramentas, APIs. reference_neon_db_config.md
Mantenha cada linha do índice com menos de 200 caracteres e o índice com menos de 200 linhas. Além disso, as entradas são truncadas e Claude não consegue vê-las.
STATE.md é para agora. MEMORY.md é para sempre. A regra geral: se você diria em um standup, vai para STATE.md. Se você escreveria em uma wiki ou documento de integração, vai para um arquivo de memória. Standups são transitórios; wikis são duráveis.
Quando um projeto é enviado e STATE.md ainda contém cinco linhas sobre ele, mova essas linhas para um arquivo de memória project_* datado e limpe-as. O projeto não parou de importar; ele parou de ser atual. Essa distinção mantém STATE.md útil.
Escreva estado, não um diário. Uma entrada de diário: "Trabalhei na integração do Stripe. Foi complicado." Uma entrada de estado: "Endpoint de webhook em app/api/webhooks/stripe/route.ts. A verificação de assinatura funciona localmente, falha na prévia do Vercel (formato de corpo bruto incorreto). Próximo: verificar a configuração do middleware rawBody." Um dá à próxima sessão um ponto de partida; o outro dá uma memória.
Mais dois anti-padrões: entradas em andamento sem uma ação concreta que uma nova sessão poderia executar, e entradas duplicadas para o mesmo tópico em várias sessões. Mescle duplicatas: um tópico, uma entrada, apenas o estado atual.
Uma boa atualização de sessão tem de nove a doze linhas: uma decisão com justificativa, um item em andamento com o próximo passo, um bloqueador com o que você tentou.
Escalando para mais de 50 arquivos de memória: a camada de resumo. Cada linha de ponteiro MEMORY.md custa aproximadamente 100-150 tokens. Em 200 linhas, isso são 20-30K tokens de puros ponteiros. A correção: STRATEGY-DIGEST.md, um resumo de 2-3 frases de cada documento principal mais um campo "Usar quando:":
## q2-positioning.md
O posicionamento do Q2 visa a habilitação de IA em organizações de vendas de médio porte.
Usar quando: discutindo cliente-alvo, preços ou qualificação de leads.Claude lê o resumo (cerca de 3K tokens) e carrega um documento completo apenas quando relevante. Em 25 documentos de estratégia, isso são 3K tokens em vez de 50K. O campo "Usar quando:" é o mecanismo de roteamento: escreva-o como uma condição de gatilho específica, não uma descrição do arquivo.
STATE.md captura o estado atual (decisões, em andamento, bloqueadores) em menos de 80 linhas; atualize-o no final da sessão e arquive o histórico prontamente. MEMORY.md indexa o conhecimento durável em quatro tipos (usuário, feedback, projeto, referência), limitado a 200 linhas. Comece esta noite com três linhas: uma decisão, um item em andamento, um bloqueador. Três linhas são melhores do que zero enquanto o hábito se forma.