dox: mantenha o AGENTS.md atualizado automaticamente

Por que o seu AGENTS.md está errado três semanas depois

Um ficheiro AGENTS.md fica desatualizado porque nada o liga ao código. Você escreve-o uma vez, manualmente, no dia em que o repositório tem uma determinada estrutura. Depois, o executor de testes muda, um pacote é renomeado, um serviço é eliminado, e o ficheiro continua a descrever junho. Nada falha, porque nenhuma etapa da compilação o lê.

O agente lê o ficheiro e acredita nele. É isso que lhe causa problemas. Num repositório sem AGENTS.md, um agente de programação analisa o conteúdo antes de agir. Num repositório com um AGENTS.md incorreto, deixa de analisar, porque já tem uma resposta. Executa o comando indicado pelo ficheiro, a shell responde Missing script: "test", e o agente começa a fazer suposições. Muitas vezes, edita package.json para adicionar o script prometido pela documentação. O ficheiro desatualizado não falhou silenciosamente. Causou uma alteração que você não queria.

O dox é uma resposta a esse problema. É um conjunto de regras, escrito para o agente, que torna a atualização da documentação parte da conclusão do trabalho. Assim, o ficheiro é alterado no mesmo commit que o código que o tornou incorreto.

O que é o dox e o que ele não é

dox é um único ficheiro Markdown. O repositório está em agent0ai/dox, é licenciado sob MIT e, em 11 August 2026, todo o projeto consiste num único AGENTS.md de 3906-byte, num README, numa LICENSE e em duas imagens. Não há nenhum pacote para instalar nem nenhum runtime.

Isto é importante porque a palavra generator sugere um programa que analisa o seu código. Nada analisa o seu código. dox é um contrato que o seu coding agent lê: o seu agent é o generator, e dox é o conjunto de instruções que lhe indica quando deve ler a documentação, quando deve reescrevê-la e qual deve ser a estrutura de cada documento.

O ficheiro tem dez secções, e duas delas executam o trabalho principal. "Read Before Editing" indica ao agent que deve percorrer, a partir da raiz do repositório, todos os caminhos que planeia alterar e ler todos os AGENTS.md ao longo de cada percurso, na sessão atual, sem depender da memória. "Update After Editing" indica que toda alteração relevante exige uma passagem DOX, ou seja, uma etapa de atualização da documentação que deve ser executada antes de a tarefa ser considerada concluída. A passagem atualiza o documento responsável mais próximo quando há alterações na finalidade, na estrutura, no fluxo de trabalho, nas permissões ou nas preferências do utilizador.

O restante define a estrutura. Um AGENTS.md filho tem uma ordem de secções predefinida: Purpose, Ownership, Local Contracts, Work Guidance, Verification e Child DOX Index. O ficheiro raiz contém as regras de todo o projeto e o Child DOX Index de nível superior, que é a forma como um agent descobre os documentos filhos. "Closeout" é a checklist que o agent executa no fim de uma tarefa: verificar novamente os caminhos alterados em relação à cadeia, atualizar os documentos responsáveis mais próximos, atualizar todos os índices afetados, eliminar contradições, executar a verificação existente e indicar quais documentos deixou deliberadamente inalterados.

Fixe a documentação num commit, não na main

O repositório não tem tags nem releases, por isso não existe um número de versão para fixar. Fixe o commit. O AGENTS.md atual está no commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, datado de 1 August 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c deve imprimir 3906. Um número diferente significa que não obteve o ficheiro descrito neste guia, por isso leia-o antes de confiar nele. Se escrever o hash do commit de forma incorreta, -f faz o curl parar com curl: (22) The requested URL returned error: 404 e não escreve conteúdo, e wc -c imprime depois 0. Um ficheiro truncado é pior do que nenhum ficheiro, porque o agente segue metade de um contrato sem o saber.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

Esse cp destina-se a um repositório que ainda não tem AGENTS.md. Se já tiver um, não o substitua. Coloque as secções de documentação acima do conteúdo existente, mantenha as suas regras por baixo e leia o resultado uma vez, de cima para baixo. Dois documentos que se contradizem fazem o agente seguir a linha que leu por último.

Depois, peça ao seu agente, dentro do repositório, para fazer a primeira passagem. O README fornece o texto exato:

Initialize DOX tree for this project now.

Ele cria os ficheiros AGENTS.md secundários e os índices que apontam para eles. Verifique o que fez antes de confiar no resultado:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Cada ficheiro apresentado nessa saída find deve aparecer nalgum Child DOX Index acima dele. Um documento secundário que não seja mencionado por nenhum índice pode passar despercebido ao agente, porque o índice é a forma como ele encontra documentos que não estão diretamente no caminho que está a percorrer.

O que dox consegue ver e o que não consegue saber

O agente que cria a sua árvore lê o repositório. Por isso, tudo o que estiver no repositório pode entrar no inventário: a estrutura de diretórios, os manifestos de pacotes e os lockfiles, os scripts em package.json, Makefile ou pyproject.toml, os ficheiros de workflow de CI, os Dockerfiles, os pontos de entrada e CODEOWNERS, se existir. Um inventário criado a partir desses elementos é realmente autossustentável. Quando um pacote muda de localização, a passagem seguinte move a linha que o descreve.

Tudo o que se segue tem de ser indicado por si, porque não está no repositório para ser lido:

• por que motivo uma regra existe, o que impede um agente de a remover por a considerar complexidade desnecessária
• qual dos dois caminhos funcionais é suportado e qual está a aguardar eliminação
• qualquer elemento fora do repositório, como o ambiente de staging ou o motivo pelo qual uma dependência está fixada duas versões atrás
• o que planeia fazer na próxima semana, que é a diferença entre um ficheiro atualizado e um ficheiro útil

O dox sabe isto sobre si próprio. As suas próprias regras dizem que a Orientação de Trabalho deve refletir os padrões atuais do projeto ou as instruções do utilizador e que, se ainda não existirem, a secção deve ficar vazia. A Verificação deve refletir uma verificação existente. Por isso, sem um framework de testes no repositório, essa secção permanece vazia até existir um. Um ficheiro gerado que inventa um padrão é pior do que uma secção vazia, porque o agente passará a impor essa invenção.

Mantenha a intenção escrita manualmente fora do inventário gerado

Esta é a falha que faz as pessoas desistirem da documentação gerada. Você escreve um parágrafo explicando que a fila de tarefas deve manter um único consumidor. Três semanas depois, uma execução reescreve o arquivo, e o seu parágrafo desaparece dentro de um diff de quarenta linhas que, na maioria, apenas reorganiza nomes de arquivos. Ninguém percebe.

Use dois mecanismos. Você precisa dos dois.

Primeiro, mova a intenção duradoura para outro arquivo. As decisões de design e o raciocínio por trás delas pertencem a um DESIGN.md escrito para o agente, e as notas destinadas às pessoas devem ficar onde você separa o HUMAN.md do AGENTS.md. O AGENTS.md passa então a conter o inventário e os contratos locais. Essa é exatamente a parte que deve mudar quando o código mudar.

Segundo, delimite a intenção que precisa permanecer no AGENTS.md. Envolva-a em marcadores e trate o bloco como conteúdo mantido por uma pessoa:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Os comentários Markdown não são renderizados na página, mas o agente continua a lê-los. Agora torne verificável a permanência do bloco, para que uma execução que o remova falhe de forma explícita. Execute isto no CI (integração contínua) em cada pull request:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff não imprime nada e termina com código 0 quando o bloco não foi alterado. Qualquer saída significa que a execução reescreveu texto mantido por uma pessoa. Nesse caso, alguém deve aprovar a alteração ou revertê-la. A verificação funciona sem depender da memória de ninguém.

Regenerar no pull request, não por temporizador

O melhor momento para atualizar um documento é no commit que o torna incorreto. Inclua a execução do DOX no mesmo pull request que contém a alteração estrutural. Assim, o diff permanece pequeno o suficiente para ser lido de facto.

Uma verificação bloqueante que impõe esta regra:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Ajuste os caminhos ao seu repositório. A vantagem é que a verificação falha no branch, onde a correção é barata, e falha por um motivo que o revisor consegue resolver.

O agendamento é o mecanismo de reserva, não o mecanismo principal. Um job semanal deteta o que ninguém notou num branch: ficheiros movidos por um rebase, um pacote eliminado num merge ou um documento que referencia um diretório que já não existe. Execute-o numa máquina pequena, a mesma que poderia usar para executar um agente de programação numa VPS, e faça com que abra um pull request em vez de fazer push para main.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

Esse comentário é intencionalmente um placeholder. Cada agente tem a sua própria CLI (interface de linha de comandos) e a sua própria flag não interativa. Um comando copiado de uma página Web que não corresponda à sua versão falha dentro do cron, onde ninguém vê o erro. Preencha-o e execute o script manualmente uma vez antes de o agendar. O || exit 0 também é importante: git commit termina com um código diferente de zero usando nothing to commit, working tree clean quando a árvore já está atualizada. Com set -e, isso seria reportado como uma falha, embora a execução tenha sido concluída corretamente.

Cada execução consome tokens, porque "Read Before Editing" faz com que o agente leia toda a cadeia em cada tarefa. Esse é o compromisso. Vale a pena monitorizá-lo se já está a contabilizar quanto custam as execuções do seu agente.

Monorepos: muitos contratos, um índice

Um único AGENTS.md na raiz de um repositório com quarenta pacotes produz um diff de regeneração que ninguém lê e um documento que é, na maior parte, irrelevante para o que o agente está a fazer naquele momento. A resposta dox é o Child DOX Index: a raiz contém as regras aplicáveis a todo o repositório e aponta para os seus filhos, e cada fronteira duradoura tem o seu próprio ficheiro. A forma de organizar essa árvore e quais ferramentas leem ficheiros aninhados estão descritas em ficheiros AGENTS.md aninhados para monorepos.

O que o dox altera é a superfície de revisão. Um pull request que altera packages/api deve produzir um diff de documentação dentro de packages/api e em nenhum outro local:

git diff --stat -- '*AGENTS.md'

Se esse comando listar seis ficheiros para uma alteração num único pacote, a árvore está incorreta. As fronteiras são demasiado amplas ou uma regra que pertence à raiz foi copiada para todos os filhos. O dox indica diretamente a correção: as regras gerais devem ficar nos documentos-pai, e os detalhes concretos devem ficar nos documentos-filho. As regras duplicadas são o que faz uma passagem normal reescrever tudo. Se as mesmas regras se aplicarem realmente a repositórios separados, esse é outro problema, e partilhar competências de agentes entre repositórios é a ferramenta mais adequada.

Revise o diff como código

É fácil aprovar um diff de documentação gerado sem o ler. É assim que um ficheiro incorreto é publicado. Leia-o com a mesma desconfiança que aplicaria a código gerado e procure quatro coisas.

• um comando que o ficheiro passa a mencionar e que deve executar antes de fazer o merge. Instruções de build inventadas são a falha mais comum.
• uma linha eliminada que continha informação sobre a intenção. As adições são fáceis de fazer. A perda acontece nas eliminações.
• um caminho absoluto, um hostname, um URL interno ou qualquer conteúdo com formato de credencial
• uma entrada de inventário referente a algo que já não existe, o que ls confirma num segundo

Depois, verifique o tamanho com wc -l AGENTS.md. Um ficheiro root com mais de duzentas linhas é um sinal de que deve ser dividido, porque o valor principal da cadeia é o agente ler apenas a parte pequena e relevante, em vez de ler tudo.

Quando falha

A passagem apagou o seu bloco de instruções. A verificação diff acima mostra as linhas removidas. Restaure o ficheiro a partir do ponto de ramificação com git restore --source=origin/main AGENTS.md e execute novamente a passagem com uma instrução mais restrita, indicando as secções que pode alterar.

Duas ramificações regeneraram o mesmo conteúdo. O ficheiro contém CONFLICT (content): Merge conflict in AGENTS.md e marcadores de conflito <<<<<<< HEAD. Não edite os marcadores manualmente. O ficheiro é gerado, por isso a resolução correta é executar uma nova passagem sobre a árvore resultante da fusão.

O agente ignora completamente o ficheiro. Verifique qual é o nome de ficheiro que a sua ferramenta lê. Se ler outro ficheiro, aponte-a para o mesmo conteúdo com ln -s AGENTS.md CLAUDE.md e confirme o link simbólico, para manter uma única fonte em vez de dois documentos que divergem. Se o nome de ficheiro já estiver correto e as regras continuarem a ser ignoradas, execute o diagnóstico sobre por que motivo os agentes de programação ignoram as suas instruções antes de reescrever o documento novamente.

A árvore ganhou ficheiros descendentes que ninguém indexou. Compare o resultado de find . -name AGENTS.md com as entradas de índice nos documentos-pai. Um descendente que não seja mencionado por nenhum índice é um descendente que o agente pode ignorar completamente.

Quando um gerador é excessivo

Um pacote, um comando de teste e duas pessoas que conhecem o repositório: escreva as vinte linhas manualmente. Um AGENTS.md com vinte linhas não fica desatualizado depressa o suficiente para justificar uma árvore, um índice, uma verificação de CI e uma tarefa semanal. Volte a lê-lo quando alterar o processo de build. Esse é todo o custo de manutenção, e é inferior ao custo da maquinaria envolvente.

O dox compensa quando o repositório tem limites que nenhuma pessoa consegue manter na memória: vários pacotes com regras diferentes ou contribuidores que chegam sem o contexto necessário. O valor não está no texto gerado. Está no facto de a documentação passar a ser algo que pode fazer um pull request falhar, que é a única razão para qualquer ficheiro de um repositório se manter atualizado.

FAQ

Preciso de instalar alguma coisa para usar o dox?

Não. O dox é um único ficheiro Markdown, com licença MIT, e, em 11 August 2026, o repositório não disponibiliza pacotes nem releases. Copie o conteúdo para o ficheiro AGENTS.md do seu projeto e o seu agente de programação seguirá as regras a partir daí. Fixe o commit que copiou, f34ec7ad1055d3393887e5a2670e8cb7320c9165 no momento da redação, e indique-o na mensagem do commit para poder identificar mais tarde a versão das regras em que a sua árvore foi baseada.

Como impeço que uma regeneração elimine as minhas regras escritas manualmente?

Mantenha a intenção e o inventário separados. Coloque o raciocínio duradouro num documento separado e tudo o que tiver de permanecer dentro de AGENTS.md num bloco marcado. Depois, valide o bloco na CI: extraia-o do branch e de origin/main com sed, compare os dois com diff e faça a compilação falhar perante qualquer diferença. Em seguida, uma pessoa aprova ou reverte a alteração, em vez de esta passar despercebida no meio de um diff grande.

Com que frequência devo regenerar o AGENTS.md?

Na pull request que o torna incorreto. Uma alteração estrutural e a respetiva documentação devem pertencer ao mesmo diff, porque esse é o único momento em que alguém tem contexto para rever ambos. Uma execução agendada semanal é o mecanismo de reserva para o desfasamento que passou por um branch e deve abrir uma pull request, em vez de fazer commit diretamente em main.

Os comandos de compilação devem ficar no AGENTS.md da raiz ou num documento filho?

No documento mais próximo que os abrange. As regras de todo o repositório e o índice filho ficam na raiz. Um comando aplicável a um único pacote fica no AGENTS.md desse pacote. O dox resolve conflitos por distância: o documento mais próximo controla os detalhes locais e nenhum filho pode enfraquecer uma regra do pai. Copiar o mesmo comando para todos os filhos é o que faz uma execução de rotina reescrever toda a árvore.

O dox vale a pena num repositório pequeno?

Normalmente, não. Um pacote com um comando de teste e um AGENTS.md de vinte linhas degrada-se lentamente, e pode corrigi-lo no minuto seguinte a detetar o problema. O dox justifica o custo quando o repositório tem vários limites com regras diferentes ou contribuidores sem o contexto necessário, porque, nesse caso, a cadeia de documentos está a executar um trabalho que nenhuma pessoa isolada executa.