Wiki
Um wiki de projeto é uma pasta de páginas em Markdown que explica o projeto: o que suas partes fazem, por que funciona da maneira como funciona e onde está a evidência. Pessoas leem. Agentes mantêm. Cada nova fonte, pergunta ou alteração de código deve deixá-lo um pouco mais completo e preciso.
Isso segue o padrão "wiki LLM": manter fontes brutas, escrever páginas que as resumem e as conectam, e manter um índice e um log para que tudo permaneça navegável.
Regras do repositório vêm primeiro
Se o repositório já possui um wiki, leia seu arquivo de esquema ou instruções (geralmente
wiki/README.md, wiki/AGENTS.md ou wiki/schema.md) antes de alterar qualquer coisa. Seu
layout, metadados, estilo de link e comandos têm precedência sobre os padrões aqui. Use os scripts
do wiki do repositório quando existirem e não edite manualmente arquivos que eles geram.
As partes
| Parte | O que é | Quem edita |
|---|---|---|
| Fontes | Cópias de material bruto: issues, PRs, artigos, anotações, transcrições | Adicionadas uma vez, nunca alteradas |
| Páginas | Explicações escritas de tópicos, citando fontes e código | Atualizadas sempre que os fatos mudam |
| Esquema | Um arquivo com as regras do wiki: layout, metadados, convenções | Alterado deliberadamente |
| Índice | Uma lista de cada página com um resumo de uma linha | Regenerado ou mantido completo |
| Log | Uma lista datada e somente de acréscimos de alterações no wiki | Uma entrada por operação |
Um layout padrão, para um novo wiki:
wiki/
├── README.md # o que é o wiki e como usá-lo
├── schema.md # as regras (o único lugar onde estão escritas)
├── index.md # cada página, uma linha cada
├── log.md # o que mudou, mais recente por último
├── pages/ # páginas de tópico
└── sources/ # material bruto, inalterado após ser adicionado
Um projeto pequeno pode parar por aí. Adicione subpastas apenas quando houver páginas suficientes para que as pessoas não consigam encontrar as coisas.
Quem está certo quando as fontes discordam
Escreva, no esquema, qual fonte vence para cada tipo de afirmação. Para a maioria dos projetos de software:
- Como o código se comporta hoje: o código e seus testes.
- O que foi decidido e por quê: o registro de decisão, issue ou PR onde foi decidido.
- O que está planejado ou em andamento: o rastreador de issues ou roadmap.
Quando uma página e sua autoridade discordam, corrija a página e mantenha uma breve nota do que mudou se a crença antiga valer a pena ser lembrada. Nunca edite uma fonte para fazê-la concordar.
Páginas
-
Um tópico por página, com um título claro. Atualize a página existente em vez de adicionar uma quase duplicata.
-
Cite o que você afirma. Vincule à fonte ou nomeie o arquivo. Um leitor deve ser capaz de verificar qualquer afirmação importante.
-
Use links relativos de Markdown (
[Parser](parser.md)) a menos que o wiki já use outro estilo. -
Mantenha o frontmatter pequeno. Um mínimo útil:
--- title: Parser summary: Como os arquivos de entrada são lidos e validados. sources: [sources/issue-42.md] code: [src/parser.ts] updated: 2026-01-31 ---Adicione campos apenas quando uma pessoa ou um script for usá-los.
-
Cada página é acessível a partir do índice e de pelo menos uma página relacionada.
Operações
Configurar um novo wiki
- Veja quais documentos já existem e quem os lê. Não duplique um site de documentação funcional.
- Proponha o layout e o esquema ao usuário e concorde com eles antes de escrever páginas.
- Crie
README.md,schema.md,index.mdelog.md. - Escreva algumas páginas para as partes mais importantes do projeto e então pare e verifique com o usuário antes de preencher o restante.
- Aponte as instruções do agente do repositório (
AGENTS.md,CLAUDE.md) para o esquema, em vez de copiar as regras para dentro deles.
Adicionar uma fonte
- Salve o material bruto em
sources/, com sua origem e data. - Leia tudo.
- Encontre cada página existente que ela afeta e atualize-as. Crie uma nova página apenas para um tópico que não tenha nenhuma.
- Observe qualquer coisa nela que contradiga as páginas atuais e resolva usando as regras de autoridade.
- Atualize o índice e adicione uma entrada no log.
Salvar uma fonte sem atualizar nenhuma página não está concluído. As páginas são o que as pessoas leem.
Responder a uma pergunta
- Comece pelo índice e depois pesquise títulos e textos das páginas.
- Leia as páginas relevantes e verifique afirmações importantes contra suas fontes ou o código.
- Responda com links para as páginas e evidências que você usou. Diga onde elas discordam ou onde o wiki não tem resposta.
- Se a resposta for nova e provável de ser perguntada novamente, ofereça-se para adicioná-la ao wiki.
Atualizar após uma alteração de código
Quando uma alteração modifica como algo funciona:
- Pesquise no wiki os arquivos, funções e termos que a alteração tocou.
- Atualize cada página afetada no mesmo PR da alteração de código.
- Atualize o índice se títulos ou resumos mudaram e adicione uma entrada no log.
Verificar a saúde do wiki
Procure por:
- links quebrados e caminhos de código que não existem mais;
- páginas sem links de entrada;
- páginas duplicadas sobre o mesmo tópico;
- fontes que nenhuma página cita;
- páginas que discordam entre si ou com o código;
- um índice que está faltando páginas ou lista páginas deletadas.
Corrija problemas mecânicos, como links e o índice, diretamente. Relate decisões de julgamento, como mesclar páginas ou decidir qual afirmação está correta, ao usuário.
Entradas de log
Adicione uma entrada por operação, no final de log.md:
## 2026-01-31 14:05 UTC: ingest | Issue 42, linhas de entrada vazias
Adicionou a issue como fonte e atualizou a seção de validação da página do parser.
Sempre inclua o horário e o fuso horário para que entradas no mesmo dia permaneçam em ordem.
Não faça
- Editar uma fonte depois de adicioná-la.
- Reestruturar ou renomear grandes partes do wiki sem perguntar.
- Deletar páginas porque estão desatualizadas. Marque-as como desatualizadas e vincule ao que as substituiu.
- Escrever as mesmas regras em vários lugares. O esquema é a única cópia.
- Tratar o wiki como mais autoritativo do que o código que ele descreve.
- Escrever em um sistema externo (Confluence, Notion, um rastreador de issues) sem a aprovação do usuário.