Pular para conteúdo

Checklist: app novo entrando no padrão

Passo a passo para colocar a documentação de um app novo no ar. Em ~30 min o site do app aparece em docs.xadm.biz/aplicacoes/<app>/.

1. Escolha o slug — com calma

O slug (nome do repo e do prefixo no bucket) é o ID público do app, para sempre: vira URL, links e alvo do futuro RAG. Renomear depois quebra tudo.

  • minúsculas, hífens, sem acento: bi-transporte-xls, não BI_TransporteXLS
  • confira a grafia em voz alta antes de criar o repo (um typo aqui já quase ficou permanente)

2. Crie o repo no Forgejo

  • Em fonte.xadm.biz, na organização certa.
  • Estrutura docs/ da constituição §3: index.md (Resumo Executivo), glossario.md e, conforme o caso, projeto/ (Etapas), decisoes/, dev/, operacao/, e public/ (manual + API públicos) (crie public/img/ junto com a primeira screenshot — Git não versiona pasta vazia).
  • Crie docs/anexos/ e docs/anexos/privado/ com os READMEs canônicos (templates/anexos-readme.md e templates/anexos-privado-readme.md do repo central): anexo público em anexos/, dado real de cliente só em anexos/privado/ — nunca publicado (constituição §5).
  • Use os templates de documento — frontmatter no formato da constituição §4.
  • App de cliente? O frontmatter leva cliente: (ver constituição §5).
  • Crie docs/app.json com os metadados do app — é ele que faz o app aparecer com nome e grupo certos na página Aplicações. App Java/Flutter: declare toolchain (ex. { "java": "25" }) — é obrigatório (o validador falha sem ele) e deve casar com a tag que o container: do CI usa. Ordem importa (fábrica de imagens de CI): a versão tem que existir na matriz-baseline.json do central (PR + push → a fábrica builda) antes de o container: apontar pra ela — senão o pull falha. Versão já homologada (Java 25) → só declarar; versão nova → PR na baseline primeiro.
  • Central de Apps: declare o app_id (identidade canônica). As funcionalidades (erros, arquivos, analytics, docs) você configura depois de codar e antes da release, rodando /xadm-setup — ele pergunta o que ativar, provisiona e preenche o bloco features do app.json (build-time). Ver Central de apps.
  • Crie docs/changelog.md a partir de templates/changelog.md — uma linha que embute o CHANGELOG.md da raiz (--8<-- "CHANGELOG.md"); o mkdocs.yml já vem com a entrada de nav "Mudanças". Fonte única: não copie o conteúdo, só o stub.
  • Crie overrides/main.html a partir de templates/overrides-main.html (o mkdocs.yml já aponta theme.custom_dir: overrides) — é o aviso de "versão antiga" do seletor de versão (decisão 0004). O custom_dir exige o arquivo existir, mesmo antes de versionar.
  • Garanta site/ no .gitignore: o build local do MkDocs (passo 5) gera a pasta na raiz do repo, e site gerado nunca é commitado (constituição §1).

3. Copie os templates canônicos do repo central

Antes de copiar, confira a versão vigente da constituição em constituicao-versao.txt — e re-confira ao terminar a adoção: se mudou no meio (já aconteceu), re-derive os templates copiados; o constituicao: do app.json deve registrar a versão que os templates realmente seguem.

Versão da constituição ≠ versão do site. O número que o app registra e compara é só o da constituição (constituicao-versao.txt = app.json constituicao:). O repo central tem também um VERSION (o release do site, ex. 0.18.2, com cara de SemVer), o /versao.txt (rotulado site X.Y.Z) e a tag vX.Y.Z — esses são do site, não da constituição; nunca os use como versão-base (era a confusão clássica num clone local — versionamento).

Baixe sempre do mirror público docs.xadm.biz/toolchain/ — nunca de um clone local (diverge) nem do fonte.xadm.biz (o Forgejo é privado: serve edição/hosting e dá 404 sem auth — inviável num bootstrap, inclusive por agente de IA). A lista canônica e a versão de cada artefato vivem no manifesto.json (a mesma fonte única que a /xadm-docs consulta); o conteúdo cru de cada um está em https://docs.xadm.biz/toolchain/raw/<caminho> — ex.:

curl -fsSLO https://docs.xadm.biz/toolchain/raw/templates/mkdocs.yml

Copie cada artefato para o destino abaixo (o nome do template ≠ caminho no app em alguns casos — o mesmo mapa que a /xadm-docs aplica):

  • templates/mkdocs.yml → mkdocs.yml na raiz do app (troque <app>)
  • templates/docs.yml → .forgejo/workflows/docs.yml (troque <app> e os passos de Javadoc/dartdoc conforme a stack; o branch é master, já no template — constituição §5)
  • xadm.css → docs/stylesheets/xadm.css (identidade visual)
  • templates/claude-regras.md → bloco no topo do CLAUDE.md do repo (regras de IA: não decide sozinha, não commita sozinha — constituição §6).
  • Skills (.claude/skills/<nome>/SKILL.md) — instale TODAS, não só duas. Copie todas as *-skill.md que o manifesto.json lista, exceto as do campo opcionais (hoje só xadm-docx — export Word para a diretoria; instale apenas se o app gera .docx). O conjunto core que todo app conformante carrega são 10: as 6 de workflow x-desenhar, x-definir, x-refinar, x-planejar, x-implementar, x-documentar + xadm-meta-audit-work, xadm-docs, xadm-release e xadm-setup (Central de Apps — o passo 2 manda rodá-la depois de codar, antes da release). As x-* são diretórios (templates/<nome>/ com SKILL.md + references/) → copie o diretório inteiro para .claude/skills/<nome>/; as xadm-* são arquivo único (templates/<nome>-skill.md → .claude/skills/<nome>/SKILL.md). Não pare em docs+release (erro real de bootstrap): o manifesto.json é a lista mecânica completa — cruze com ele, não com esta prosa. Duas skills têm passo extra:
    • xadm-docs — copie também templates/checa-constituicao.sh → .claude/checa-constituicao.sh (+ hook SessionStart no .claude/settings.json, snippet no topo do script). Preencha constituicao: no docs/app.json com a versão vigente (constituição §6) e anote-a no CLAUDE.md.
    • xadm-release — troque <app>/<repo> e mantenha só o bloco de "Particularidades" da sua stack. É o wiring de release, fácil de esquecer porque a doc flui antes: instale junto, não depois. O CHANGELOG.md não se cria à mão — nasce na primeira /xadm-release (infere do git log e cobre o histórico). Ver versionamento.

App que renderiza HTML no servidor (Micronaut Views/Thymeleaf — telas de admin/ops/dev, inclusive internas e atrás do gate de auth) copia também o kit de UI opcional (templates/views/** + templates/public/** → layout.html, custom-theme.css, logo.png, favicon.ico) e usa o layout padrão X-Adm em vez de reinventar o visual (constituição §5). Copie também o scaffold templates/app.css → public/css/app.css (CSS de componentes deste app; o head sempre o linka — sem o arquivo, 404 em toda página). Ausente no opcionais do manifesto para app headless/Flutter. Receita e static-resources em Java/Micronaut §UI.

Hook de estilo terso (recomendado): some ao .claude/settings.json o hook SessionStart que injeta a regra de output terso + o carve-out verbatim da casa (.claude/caveman.sh) — corta ~65–75% dos tokens de output do agente, exatidão intacta, e protege os deliverables (mensagem de commit, §6, .ia/) da compressão. Receita em Ferramentas de token § caveman. Opcional no mesmo array: .claude/token-check.sh (lembrete de eficiência do rtk gain no start — auto-análise).

Higiene do settings.json: versionado enxuto (padrões largos compartilhados) + pessoal em .claude/settings.local.json gitignored — senão o allow-list incha a cada sessão e o --amend solta a tag da release. Regra em Ferramentas § higiene do settings.json.

Não copie de outro app — clones divergem do padrão.

Template × piloto — não confundir a fonte

O template (vem do central, sincronizado via manifesto) é a única fonte de cópia para um app novo. Um app piloto / de referência (por stack, citado nas páginas de Engenharia) é o exemplo onde o padrão foi provado e destilado — serve de referência, nunca de base de cópia (copiar dele = "clones divergem"). O que um app novo segue vem de: templates + a página de Engenharia da stack + a skill da stack, não de clonar um piloto.

4. Secrets — nada a criar, só confira

Os secrets DOCS_S3_ENDPOINT, DOCS_S3_ACCESS_KEY e DOCS_S3_SECRET_KEY já existem na organização xadm do Forgejo (key única de escrita no bucket docs-sites, compartilhada por todos os apps — ver Garage). O aviso de falha do CI não precisa de secret nem de passo no YAML — é um webhook nativo da organização que cobre todos os workflows (Forgejo e CI). Repo criado na organização herda automaticamente; só confira que o repo está na org.

Credenciais — não confundir (Central de Apps é build-time)

O client-grade (DSN, app key, bucket) não é secret — vive no app.json (o /xadm-setup grava). São secrets (fora do app.json): (1) DOCS_S3_* — publicação de docs, herdada da org; (2) key de escrita do Garage (só web/server, se usa arquivos) — o /xadm-setup registra e o deploy injeta no Coolify (mobile escreve via presign); (3) SENTRY_AUTH_TOKEN (upload de sourcemap do GlitchTip), idem. Ver Central de apps.

5. Valide e publique

  • Local (opcional): mkdocs build --strict e o validador de frontmatter — no Ubuntu, instale o MkDocs via pipx (como configurar); o validador, baixe do site (não copie para o repo do app): curl -fsSLO https://docs.xadm.biz/toolchain/valida-frontmatter.py && python3 valida-frontmatter.py docs/.
  • Push no branch padrão → o workflow builda, valida e publica no bucket → em ~2 min o site está em docs.xadm.biz/aplicacoes/<app>/.
  • A entrada na página Aplicações (e na API Reference, se houver api/) é automática — confira se o app apareceu no grupo certo; se caiu em "Outros", o app.json não foi publicado ou está inválido.
  • Resumo Executivo (constituição §2): a home (index.md) é a porta do diretor — problema + como resolve, sem jargão, 1–2 parágrafos, terminando em "→ Documentação Completa". Ponha <!-- etapas --> e o hook injeta as listas "entregue/planejado" do campo entrega: + status de cada etapa. Template: Resumo Executivo.
  • Documentação Completa = o livro do sistema, autorado (constituição §2): crie docs/projeto/index.md a partir do template — um esqueleto na ordem lógica (contexto → dados → modelo → mapeamento → fluxos → transversais → contratos → changelog) que mostra o sistema no estado atual, não a soma das etapas. Você escreve o fio narrativo; o factual vem das fontes: o <!-- GERADO: changelog --> injeta etapas+decisões, e um <!-- RECONCILIAR: … --> falha o build até reconciliar. Projeto com banco: crie também projeto/modelagem.md — o modelo de dados consolidado (ER Mermaid), embutido no livro e atualizado por toda etapa que evolui o banco, no mesmo PR (§5).
  • Etapas do Projeto (constituição §5): os docs de projeto/ são NN-titulo.md (duas casas, sem PROJ-/ano); avulso vai em projeto/diversos.md. A seção no site chama-se "Etapas do Projeto".
  • Público/privado (constituição §5): docs/ é privado por padrão; o público vive em docs/public/ (public/index, public/manual/, public/api/) — uma pasta, sem marcação por página. O manual do usuário e a API exposta moram aí. Guarda: página em public/ não linka para fora de public/ (o validador falha). Login e dois domínios são specs futuras — por ora um site só, nada de infra.
  • Referência de API (constituição §5): se o app expõe API, descomente no docs.yml o passo "Gerar referência de API" da sua stack — o CI de docs gera do código, antes do build, para dentro de docs/: Javadoc/dartdoc (interno) → docs/dev/api/ (linke com [API Reference](api/index.html) numa página dev/); OpenAPI (público) → docs/public/api/openapi.yaml + a página docs/public/api/index.md (template). .gitignore: docs/dev/api/ e docs/public/api/openapi.yaml são gerados — ignore-os (junto com site/).

6. CI de código (dois workflows)

O docs.yml cuida só da documentação. O código do app tem dois workflows de papéis distintos (constituição §6):

ci.yml — gate de qualidade (push/PR): roda o gate completo de análise estática + testes da stack — só testes deixa lint/estilo (checkstyle, analyze) escapar para o master. Por stack:

Stack Comando do gate
Java/Gradle ./gradlew check (testes + checkstyle + verificações)
Flutter dart format --output=none --set-exit-if-changed . && flutter analyze && flutter test
Dart dart format --output=none --set-exit-if-changed . && dart analyze && dart test
Node npm run lint && npm test

App só-script (sem suíte): lint é o piso (sempre); testes cobrem a lógica pura onde existir; não invente suíte para um script trivial.

release.yml — rede de segurança do release (push de tag): roda o valida-release.py (SemVer no manifesto ↔ CHANGELOG ↔ tag). Independe da skill /xadm-release — pega tag fora-de-banda ou bug da skill.

Templates canônicos: templates/ci.yml e templates/release.yml. Sem passo de aviso — a falha vai pelo webhook nativo da org (Forgejo 15).

Migração (apps com ci.yml antigo): se o seu ci.yml já rodava o valida-release.py em push de tag, ele virou release.yml — renomeie e adote o novo ci.yml (gate de qualidade) ao lado.

7. Container — se o app deploya

App que sobe no Coolify leva Dockerfile + .dockerignore na raiz desde o primeiro commit de código (constituição §3). O Coolify builda o Dockerfile do repo (não há buildpack) e o ci.yml não builda imagem: se faltar, o primeiro a descobrir é o deploy em produção — foi assim que um app da casa passou em testes e e2e local e quebrou só no Coolify. Derive de templates/dockerfile-java e templates/dockerignore-java; não copie do repo irmão. App Java/Gradle leva junto o .gitattributes (templates/gitattributes-java) — sem ele, checkout Windows deixa o gradlew com CRLF e o docker build morre com ./gradlew: not found no Alpine. Detalhe por stack: Java/Micronaut §Deploy.

Repo que não deploya (biblioteca, CLI distribuído pela aba Releases) pula este passo.

Repo que era só doc e passou a ter código?

Caso comum: o repo entrou no padrão pela documentação (pré-projeto, projeto), o projeto foi aprovado e virou app. O checklist acima é doc + CI; ao aparecer o primeiro src/, faltam os passos de código:

  1. ci.yml com o gate da sua stack (passo 6) — sem ele, nada roda em push.
  2. release.yml (passo 6) e a fonte de versão da stack (gradle.properties/pubspec.yaml).
  3. Dockerfile + .dockerignore (passo 7) se o app deploya.
  4. toolchain no docs/app.json, dentro da baseline da fábrica.
  5. /health com shape {status, versao} e o health check (versionamento).

O plano do primeiro ciclo de código (/x-planejar) puxa esses itens para a fase de bootstrap. Deploy não é só "operação humana no painel": a metade que mora no repo é tarefa de código como qualquer outra.

Migrando de doc legada (arc42 monolítico)?

Se o app vinha de um doc único arc42 (um index.html com tabela de ADRs), a migração para os seis níveis é trabalho da skill /xadm-docs. Um cuidado específico: gere uma tabela de equivalência ADR-legado → decisão NNNN (ex. ADR-004 BYTEA → 0008) na primeira migração — quem conhecia a numeração antiga não acha a nova sem ela. Barato de fazer uma vez, caro de reconstruir depois.

Achou brecha no padrão?

Se ao aplicar o padrão algo travou, ficou ambíguo ou você decidiu às cegas: não contorne localmente. Peça ao Claude do seu app um texto descrevendo o problema e cole-o numa sessão do Claude Code no repo central documentacao — a correção sai de lá, para todos (constituição §6).