Pular para conteúdo

ADR-0004 — Documentação como código, unificada em docs/

Contexto

Até 2026-08-30, a documentação do repositório vivia espalhada: 46 specs em spec/, 15 fixes em fix/, nenhum registro de tweak (o /tweak nunca escreveu arquivo), e um docs/ pequeno com quatro documentos de design soltos. Cada área tinha sua própria convenção de front matter (nenhuma, na prática — cabeçalho em tabela markdown), sua própria numeração, e nenhum catálogo que permitisse a um agente de IA (ou a uma pessoa nova) descobrir "o que já existe sobre X" sem varrer arquivo por arquivo. Não havia site publicado — ler a documentação significava abrir arquivos Markdown soltos no repositório.

Decisão

Unificar todo o conteúdo documental sob docs/, publicado como site com Material for MkDocs em docs.garantora.com.br, preservando:

  • a numeração histórica de specs e fixes (SPEC-NNNN, FIX-NNNN) — são a mesma identidade que as branches spec/NNNN-* e fix/NNNN-* sempre tiveram;
  • front matter YAML padronizado, com um catálogo (docs/metadata/catalog.yaml) que agrega tipo, status, domínio e relações sem duplicar o conteúdo de cada documento;
  • Mermaid para diagramas de fluxo/jornada/sequência/estado/entidade, dentro do próprio Markdown; Structurizr DSL para o modelo C4 de arquitetura, que precisa de mais de uma vista consistente (contexto, containers, componentes).

Alternativas consideradas

  • Reorganizar specifications/ por domínio, sem número (o desenho inicialmente cogitado). Descartada: ~200 citações cruzadas entre specs e fixes usam o número ("a RN7 da 0038"), a numeração alimenta scripts de validação (spec_lint.py, next-number.sh) e a nota de versão automática do /ship. Renumerar quebraria tudo isso por ganho de organização que o índice por domínio já entrega sem precisar mexer na identidade dos documentos.
  • Mover os quatro documentos de design para docs/product/design/. Descartada pelo mesmo motivo: dezenas de specs e fixes já citam docs/design-tokens.md etc. pelo caminho atual — mover exigiria reescrever essas citações históricas por padronização estética, sem mudar o conteúdo.
  • Manter spec/, fix/, tweak/ como estão e só publicar um site por cima. Descartada: não resolve a fragmentação de convenção nem cria um catálogo navegável por IA, que era o problema original.

Consequências positivas

  • Um agente de IA (ou pessoa) encontra "o que já existe sobre autenticação" pelo catálogo, sem varrer 61+ arquivos.
  • Specs, fixes e ADRs citam-se por ID estável, verificável automaticamente (scripts/docs_lint.py).
  • A documentação fica pesquisável e navegável como site, sem deixar de ser legível direto no repositório.

Consequências negativas

  • Os scripts que faziam RAIZ.glob("spec/*/spec.md") (numeração, lint, citação de arquivo:linha, nota de versão) precisaram ser reapontados para docs/specifications/*/specification.md — ponto único de acoplamento a caminho hardcoded, documentado em ../operations/documentation-platform.md.
  • spec/, fix/ continuam existindo até a validação completa confirmar que nada foi perdido — uma pasta a mais até a limpeza final.

Riscos

Um link relativo não corrigido na migração quebraria silenciosamente até o build --strict do MkDocs (que falha em link quebrado) pegar. Mitigado rodando o build estrito como parte da própria migração, não como validação posterior.

Status

aceita — este documento e a migração que ele descreve.

Documentos relacionados

../index.md, ../metadata/migration-map.yaml, ../operations/documentation-platform.md.