dox: mantenha o AGENTS.md sempre atualizado

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. É escrito 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 build 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 no ficheiro, a shell responde Missing script: "test" e o agente começa a adivinhar. 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 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, tem licença MIT e, em 11 August 2026, todo o projeto consiste num 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 ler a documentação, quando a reescrever 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 o repositório desde a raiz até cada caminho que pretende alterar e ler todos os AGENTS.md encontrados em cada percurso, na sessão atual, sem depender da memória. "Update After Editing" indica que cada alteração relevante exige uma passagem DOX, ou seja, uma etapa de atualização da documentação executada antes de a tarefa ser considerada concluída. A passagem atualiza o documento proprietário mais próximo quando há alterações no propósito, 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 aplicáveis a todo o projeto e o Child DOX Index de nível superior, que permite ao agent descobrir os documentos filhos. "Closeout" é a lista de verificação que o agent executa no final de uma tarefa: verificar novamente os caminhos alterados contra a cadeia, atualizar os documentos proprietários mais próximos, atualizar todos os índices afetados, eliminar contradições, executar a verificação existente e indicar quais os documentos que deixou deliberadamente inalterados.

Fixe o dox num commit, não em main

O repositório não tem tags nem releases, por isso não existe um número de versão a 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 mostrar 3906. Um número diferente significa que não obteve o ficheiro descrito neste guia, por isso leia-o antes de confiar nele. Se introduzir o hash do commit incorretamente, -f faz o curl parar com curl: (22) The requested URL returned error: 404 e não escreve conteúdo, e wc -c mostra então 0. Um ficheiro truncado é pior do que nenhum ficheiro, porque o agente segue metade de um contrato sem saber disso.

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 dox acima do conteúdo existente, mantenha as suas próprias regras abaixo e leia o resultado uma vez, do início ao fim. Dois documentos que se contradizem fazem com que o agente siga a linha que leu por último.

Depois, dentro do repositório, peça ao agente uma primeira passagem. O README apresenta o texto exato:

Initialize DOX tree for this project now.

Isto cria os ficheiros AGENTS.md subordinados 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

Todos os ficheiros dessa saída find devem aparecer algures acima num Child DOX Index. Um documento subordinado que não seja mencionado por nenhum índice pode passar despercebido ao agente, porque o índice é a forma de encontrar documentos que não estão diretamente no caminho que ele está a percorrer.

O que o 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 workflows de CI, os Dockerfiles, os pontos de entrada e CODEOWNERS, se existir. Um inventário criado a partir desses elementos mantém-se realmente atualizado. Quando um pacote muda de localização, a passagem seguinte move a linha que o descreve.

Tudo o que se segue tem de ser declarado 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 remoçã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 atual e um ficheiro útil

O dox sabe isto sobre si próprio. As suas próprias regras dizem que a Work Guidance deve refletir as normas atuais do projeto ou as instruções do utilizador e que, se ainda não existirem, a secção deve ficar vazia. A Verification deve refletir uma verificação existente. Por isso, se não houver um framework de testes no repositório, essa secção permanece vazia até existir um. Um ficheiro gerado que inventa uma norma é 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 de documentação gerada. Você escreve um parágrafo explicando que a fila de jobs deve permanecer com 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 maior parte, apenas reorganiza nomes de arquivos. Ninguém percebe.

Você precisa dos dois mecanismos.

Primeiro, mova a intenção duradoura para outro arquivo. As decisões de projeto e o raciocínio por trás delas devem ficar em 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, que são exatamente a parte que deve mudar quando o código muda.

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

## 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, e o agente continua lendo-os. Agora torne verificável a permanência do bloco, para que uma execução que o remova falhe de forma explícita. Execute isto na 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 permanece intacto. Qualquer saída significa que a execução reescreveu texto mantido por pessoas. Nesse caso, uma pessoa 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 agendamento

O melhor momento para atualizar um documento é o commit que o torna incorreto. Coloque a execução do DOX no mesmo pull request que contém a alteração estrutural, para que o diff continue suficientemente pequeno 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.

Um agendamento é o mecanismo de reserva, não o mecanismo principal. Um job semanal deteta o que ninguém reparou 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 coding agent numa VPS, e faça-o abrir 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 agent tem a sua própria CLI (command line interface) 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 com nothing to commit, working tree clean quando a árvore já está atualizada e, em set -e, isso reportaria uma execução saudável como uma falha.

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

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 sua maior parte, irrelevante para a tarefa atual do agente. A resposta do dox é o Child DOX Index: a raiz contém as regras aplicáveis a todo o repositório e aponta para os ficheiros dos diretórios descendentes; cada limite duradouro tem o seu próprio ficheiro. A forma de organizar essa árvore e as ferramentas que leem ficheiros aninhados são abordadas 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á mal organizada. Os limites são demasiado abrangentes ou uma regra que pertence à raiz foi copiada para cada diretório descendente. O dox indica diretamente a correção: as regras abrangentes devem ficar nos documentos pai; os detalhes concretos devem ficar nos documentos descendentes. As regras duplicadas são o que faz uma passagem de rotina 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 suspeita 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 uma intenção. As adições são fáceis. É nas eliminações que ocorre a perda.
• um caminho absoluto, um hostname, um URL interno ou qualquer conteúdo com formato de credencial
• uma entrada de inventário para 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 para o dividir, porque o valor de toda a cadeia está em o agente ler apenas a parte pequena e relevante, em vez de ler tudo.

Quando algo falha

A passagem eliminou 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 ficheiro. 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, portanto a resolução correta consiste numa nova passagem sobre a árvore resultante da fusão.

O agente ignora completamente o ficheiro. Verifique qual é o nome do ficheiro que a sua ferramenta lê efetivamente. Se ler outro ficheiro, aponte-o para o mesmo conteúdo com ln -s AGENTS.md CLAUDE.md e faça commit do symlink, para manter uma única origem em vez de dois documentos que divergem.

A árvore ganhou elementos filhos que ninguém indexou. Compare o resultado de find . -name AGENTS.md com as entradas de índice nos documentos principais. Um elemento filho que não é mencionado por nenhum índice é um elemento 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 build. Esse é todo o custo de manutenção, e é inferior ao custo da infraestrutura à sua volta.

Vale a pena usar o dox quando o repositório tem limites que nenhuma pessoa conhece por completo: vários pacotes com regras diferentes ou contribuidores que chegam sem contexto. O valor não está no texto gerado. Está em tornar a documentação algo que possa 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, licenciado ao abrigo da MIT, e, em 11 August 2026, o repositório não disponibiliza nenhum pacote nem nenhuma release. 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 criada.

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 permanente num documento separado, e tudo o que tiver de permanecer dentro de AGENTS.md deve ficar dentro de um bloco marcado. Depois, verifique 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. Depois, uma pessoa aprova ou reverte a alteração, em vez de esta passar despercebida dentro de um diff grande.

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

No pull request que o torna incorreto. Uma alteração estrutural e a respetiva documentação devem fazer parte do mesmo diff, porque esse é o único momento em que alguém tem o contexto necessário para rever ambos. Uma execução agendada semanal é a salvaguarda contra alterações divergentes que escaparam a um branch, e deve abrir um pull request em vez de fazer commit para main.

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

No documento mais próximo que seja responsável por eles. As regras para 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 normal reescrever a árvore inteira.

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 deteriora-se lentamente, e pode corrigi-lo no minuto seguinte a detetar o problema. O dox compensa o custo quando o repositório tem vários limites com regras diferentes ou colaboradores sem o contexto necessário, porque, nesse caso, a cadeia de documentos está a executar trabalho que nenhuma pessoa faria sozinha.