Como se trabalha
08 · Sistema de documentação
Cada tipo de conhecimento tem um lugar. Quem procura sabe onde olhar, e quem escreve sabe onde pôr. O agente segue o mesmo mapa.
Onde cada coisa vive
Cada documento, seu papel
| Documento | Responde | Ciclo de vida | Quem atualiza |
|---|---|---|---|
README.md | Responde: O que é, estado atual, pré-requisitos, como rodar em 5 comandos, onde ler mais | Ciclo de vida: vivo | Quem atualiza: toda change que muda um desses pontos |
docs/ARCHITECTURE.md | Responde: Como o sistema é: aplicações, módulos, domínio em mapa, identidade, implantação, observabilidade — com diagramas | Ciclo de vida: vivo, sempre reflete o presente | Quem atualiza: toda change que muda a forma do sistema |
docs/stack.md | Responde: Com que tecnologia e versão, e onde cada versão mora | Ciclo de vida: vivo | Quem atualiza: change que troca dependência |
docs/produto/ | Responde: Para quem, o quê, o método do negócio (a visão de produto) | Ciclo de vida: vivo | Quem atualiza: mantenedor + agente |
docs/decisoes/ | Responde: Por que, com alternativas | Ciclo de vida: imutável depois de aceita | Quem atualiza: nova ADR |
docs/solucoes/ | Responde: Como um pedaço difícil foi montado: algoritmos, telas complexas, fluxos internos | Ciclo de vida: vivo | Quem atualiza: a change que monta o pedaço |
docs/guias/ | Responde: Como operar: rodar local, testar, implantar, restaurar backup | Ciclo de vida: vivo | Quem atualiza: a change que muda a operação |
docs/acesso/<app>.md | Responde: Permissões, perfis, grupos, como dar acesso, como outra aplicação obtém acesso | Ciclo de vida: vivo | Quem atualiza: change que mexe em acesso |
docs/design-system/ | Responde: Aplicações e famílias, mapa de estados, pedidos, aprendizados | Ciclo de vida: vivo | Quem atualiza: change de tela |
openspec/specs/ | Responde: O comportamento vivo, por capability | Ciclo de vida: vivo, via archive | Quem atualiza: archive de change |
openspec/changes/archive/ | Responde: Como cada comportamento chegou | Ciclo de vida: imutável | Quem atualiza: archive |
Por que o ARCHITECTURE.md precisa de disciplina
Sem disciplina, o ARCHITECTURE.md acumula o detalhe de cada capability (uma seção "Domínio"
de centenas de linhas) e parágrafos datados ("Estado em 2026-09-12…"). Regra do modelo:
- o
ARCHITECTURE.mdtem um parágrafo e um link por capability; o detalhe vai paradocs/solucoes/ou para a spec; - nada de "estado em data X" — o presente é o que está escrito; o passado está no Git e no arquivo de changes;
- todo bloco grande ganha um diagrama antes do texto.
A forma do ARCHITECTURE.md
Seções fixas, na ordem, para toda stack. A primeira tela responde "o que é isto e como se encaixa"; o resto aprofunda.
Diagramas
- Um diagrama abre cada documento grande (ORG-0005). O leitor entende o assunto antes de ler, e o texto ao redor diz o mesmo que o diagrama;
- Recomendado: rabisco desenhado por código, no estilo de rabisco do design system (traço de
lápis, Caveat, só as cores da marca, nos dois temas), com o kit que vem no modelo
(
eng/sketches/). Serve ao que se lê muito e muda pouco: o README, a visão de produto, os guias, a abertura dos documentos. É como este repositório desenha; - Permitido: Mermaid, escrito no próprio texto, para o que muda em quase toda change ou precisa sair rápido. Tipos e usos:
| Tipo Mermaid | Para quê |
|---|---|
flowchart | Para quê: caminhos de decisão, dependências |
sequenceDiagram | Para quê: conversa entre partes no tempo (login OIDC, deploy, setup do E2E) |
stateDiagram-v2 | Para quê: estados de uma entidade |
erDiagram | Para quê: modelo de dados |
- Imagem que não é diagrama é, de preferência, SVG desenhado por um script versionado em
eng/(diff legível, regerável, nítido em qualquer tamanho — como o banner deste repositório); quando precisa de um gerador de imagens, o agente escreve o prompt em<caminho-da-imagem>.prompt.mde o mantenedor gera a imagem.
Guias que toda stack tem
O modelo traz os guias com a estrutura pronta; a Fase 2 preenche o específico.
| Guia | Nasce em | Conteúdo |
|---|---|---|
fluxo-openspec.md | Nasce em: Fase 0 (pronto) | Conteúdo: como trabalhar com changes |
definir-a-stack.md | Nasce em: Fase 0 (pronto) | Conteúdo: o roteiro da Fase 1 |
desenvolvimento-local.md | Nasce em: change esqueleto | Conteúdo: os dois caminhos locais, portas, usuários por perfil |
testes.md | Nasce em: esqueleto + e2e-base | Conteúdo: as três camadas, recortes, ler resultados, E2E por nível |
identidade.md | Nasce em: identidade | Conteúdo: provisionar realms e clients, dar acesso, IdP externo, produção |
observabilidade-local.md | Nasce em: observabilidade | Conteúdo: ver trace, métrica e log na máquina |
implantacao.md | Nasce em: implantacao | Conteúdo: primeiro deploy (checklist do portão 3), deploys seguintes |
backup-e-restauracao.md | Nasce em: implantacao | Conteúdo: backup manual, restauração, teste de restauração |
atualizar-design-system.md | Nasce em: aparencia | Conteúdo: caminho da atualização por change; pedidos |
nova-aplicacao.md | Nasce em: Fase 0 (pronto) | Conteúdo: acrescentar uma aplicação à stack (ver 18) |
Guias genéricos de plataforma (inicializar VPS, apontar DNS, gerenciar segredos no
Bitwarden) vivem no toolbox e são referenciados, nunca copiados.
O template de ADR
# ADR-NNNN — Título curto no imperativo
- **Status:** proposta | aceita (AAAA-MM-DD) | substituída por ADR-XXXX | não adotada
- **Data:** AAAA-MM-DD
- **Cumpre:** ORG-NNNN, ORG-NNNN (as ORGs dentro das quais decide)
- **Change:** `<nome-da-change>` (quando nasce de uma)
- **Revisa:** ADR-XXXX (quando revisa outra)
## Contexto
## Decisão
## Alternativas consideradas
## ConsequênciasO documento de solução
Uma solução nasce quando a change monta algo que o leitor futuro não entenderia só pelo código e pela spec: um algoritmo (motor de agendamento), uma tela com muitos estados (agenda do gestor), um fluxo entre várias partes (prévia de links com proteção de SSRF). Forma:
- o problema em um parágrafo;
- um diagrama;
- as peças (classes, tabelas, rotas) e como se ligam;
- as armadilhas conhecidas;
- links: change de origem, ADRs, spec.