Status para pessoas e status para agentes não cabem no mesmo arquivo

Faz sentido pensar que documentação de status é uma coisa só. Um arquivo, o mais completo possível, que serve para eu entender onde o projeto está e para o agente se orientar quando abre uma sessão nova. Quanto mais detalhe, melhor para os dois. Eu pensava assim.

Para uma pessoa, o arquivo completo é ótimo mesmo. Ele guarda a história inteira das decisões, os caminhos que não deram certo, o contexto de cada mudança de rota. Quando quero reconstruir por que um projeto está do jeito que está, é ali que eu vou.

Para um agente que só precisa saber onde paramos antes de continuar, esse mesmo arquivo é péssimo. Ele paga o preço de ler tudo aquilo antes de fazer qualquer trabalho de fato, e paga com a única moeda que tem: o orçamento de contexto da sessão. Foi um agente abrindo o arquivo errado, sem saber que existia um mais enxuto feito exatamente para aquele momento, que me convenceu de que são dois documentos, e não um.

Um arquivo é para quem lê a história; o outro, para quem decide o próximo passo

No meu sistema, status são dois arquivos. O PROJECT_STATUS.md é o humano: narrativa rica, cresce sem limite fixo e rotineiramente passa de 40 mil tokens. Token é a unidade em que o modelo mede texto, um pedaço de palavra, mais ou menos. Quarenta mil deles é uma leitura longa até para uma pessoa.

O AGENT_STATUS.md é o outro. Tem no máximo 30 linhas e um esquema fixo de 8 campos: Fase, Último marco, Branch ativa, Último commit, Bloqueio, Próxima ação, Decisões em aberto, Handoff ativo. Nada além disso. Um agente que abre uma sessão lê os oito campos e já sabe o que fazer, ou sabe exatamente o que está impedindo.

A regra que deixo escrita nas instruções do Claude Code é curta: agente se orienta pelo arquivo de 30 linhas, nunca pelo arquivo humano. O arquivo humano é para quando uma pessoa quer a história completa e está disposta a pagar o tempo de leitura.

Abrir o arquivo errado custou 55 mil tokens antes do primeiro passo

O número veio de uma sessão real do DT Dashboard, um dos meus sistemas. O agente que estava se orientando abriu o PROJECT_STATUS.md, um painel longo escrito para mim, como primeiro movimento da sessão. Uma única interação. A sessão pulou 55 mil tokens.

Antes de qualquer trabalho de fato. Nenhuma linha de código lida, nenhuma decisão tomada, nenhum commit. Só a orientação, e ela já tinha consumido uma fatia do orçamento que deveria ir para o trabalho.

O agente não errou a resposta. Errou o arquivo que abriu antes de responder.

Eu poderia ter tratado aquilo como deslize de um dia. Mas o arquivo humano cresce a cada marco, por desenho, e o custo de abri-lo cresce junto. O incidente não era exceção; era o comportamento esperado de um agente que segue a instrução "leia o status" quando só existe um status para ler.

Trinta linhas é um corte, e o corte é o que torna o arquivo seguro

Manter o arquivo de orientação em 30 linhas com esquema fixo exige deixar coisa de fora. Histórico, contexto, a nuance de por que uma decisão em aberto ainda está em aberto: tudo isso seria útil de ter ali, e não cabe. Recomendo o corte mesmo assim, e o preço é este: o agente começa a sessão sabendo menos do que poderia. Em troca, o arquivo é seguro de abrir em toda sessão nova, sem nunca estourar o orçamento de contexto da orientação. Perder nuance é o que compra essa garantia.

O arquivo de 30 linhas também não é um histórico. Ele é sobrescrito a cada execução da rotina de documentação — um retrato do momento, não um diário. Se o campo Bloqueio dizia uma coisa ontem e hoje diz outra, a versão de ontem não existe mais nesse arquivo. Ela existe no outro, o humano, para quem quiser ler e puder pagar o custo.

Essa divisão parece óbvia depois de feita. Não parecia antes. A tentação de "só mais um campo" ou "só mais um parágrafo de contexto" aparece toda vez que o agente começa uma sessão sem saber algo que eu sabia. Cada vez que cedo, o arquivo enxuto anda um passo na direção do arquivo gordo, e o incidente de 55 mil tokens volta a ser questão de tempo.

O teste, antes de abrir qualquer arquivo de status, é uma pergunta: quem está abrindo é um agente decidindo o próximo passo, ou uma pessoa reconstruindo a história do projeto? Se a resposta é "agente decidindo o próximo passo", o arquivo certo tem 30 linhas, não 40 mil tokens. Se é "pessoa reconstruindo a história", o arquivo gordo é o certo, e o tempo de leitura é o preço justo.

Eu mudo de ideia no dia em que um único arquivo, sem essa separação, servir para os dois sem custo de contexto. Uma sessão real mostrou o contrário, e foi cara o bastante para eu não precisar de uma segunda.