ADR-0009 · Documentação como código com Starlight

Status: aceito · Data: 2026-10

Contexto

A documentação estava espalhada (README, .docs/, .docs/ia/, docs/, exportações para Confluence) e desatualizada: descrevia um apps/auth, Django e Pix do Banco do Brasil, que não existem mais.

Decisão

Criar apps/docs com Astro Starlight, navegação Diátaxis, conteúdo arc42 + C4 + ADRs, diagramas Mermaid no próprio Markdown, capturas geradas por script (Playwright) e PDF de entrega ao cliente gerado a partir das mesmas páginas. Os documentos antigos foram usados como fonte e serão aposentados.

Consequências

• ➕ A doc muda no mesmo PR que o código; revisão por pull request.
• ➕ Uma única fonte para o site e para o PDF.
• ➖ Exige disciplina: PR que muda comportamento deve atualizar a página correspondente.