Quarto Markdown combina documentação com código executável em um único artefato. Na Amazing, a spec é QMD: exemplos viram testes, contratos viram validação automática. Se o código diverge da documentação, o build quebra. Documentação sempre atualizada vira consequência da build, não disciplina do time.
Em projeto que evolui rápido, documentação atrasa. Ninguém é vilão. Simplesmente o código mudou e ninguém lembrou de atualizar a doc. Em três sprints, a doc vira ficção: descreve um sistema que não existe mais.
O custo aparece tarde: onboarding novo confia na doc, descobre divergência tarde, perde dias debugando o que devia ser óbvio. Auditoria descobre que contrato documentado não corresponde ao implementado. Cliente reclama de comportamento que a doc dizia ser diferente.
QMD elimina o problema na origem. Doc e código são o mesmo arquivo. Se o que está escrito não bate com o que roda, a build falha. Doc desatualizada vira bug, não negligência.
Toda spec Amazing nasce em formato Quarto Markdown. Texto narrativo descreve intenção. Blocos de código mostram exemplo. Output esperado é parte do arquivo.
Cada bloco de código roda no CI. Se a saída diverge do esperado, build falha. Spec não consegue ficar desatualizada sem alguém perceber imediatamente.
Os exemplos no QMD da spec são executados como testes de contrato. Se o código real implementa diferente, o teste falha. Documentação valida implementação.
O mesmo QMD vira HTML pro time interno, PDF pra auditoria, dashboard pro stakeholder. Uma fonte, vários consumidores, sempre sincronizados.
## Validação de saldo A operação verifica saldo antes de processar pagamento. Saldo insuficiente gera erro InsufficientFunds. ```{python} def check_balance(account, amount): if account.balance < amount: raise InsufficientFunds( account=account.id, requested=amount, available=account.balance ) return True ``` ### Exemplo ```{python} acc = Account(balance=Decimal("50.00")) check_balance(acc, Decimal("100.00")) ``` › Output esperado: InsufficientFunds(account=acc-1, requested=100, available=50) $ quarto render payment.qmd ✓ build · 0 erros ✓ saída validada · contrato ok ✓ HTML, PDF e teste gerados
QMD muda a relação entre código e doc: deixam de ser dois artefatos separados que precisam ser sincronizados manualmente e viram um só, validado em build.
Build falha se doc diverge do código. Sincronização automática.
Doc confiável reduz tempo de novo membro entender o sistema.
Auditor lê QMD e roda. Implementação valida documentação.
HTML, PDF, dashboard, teste. Mesma fonte, vários formatos.
QMD não é Markdown estilizado. É documento que roda, valida e gera artefatos. Na Amazing, é a base de toda spec, doc técnica e contrato versionado.
Não é exceção pra projeto fancy. É o formato base de toda spec, em todo cliente Amazing.
CI roda QMD e valida. Doc desatualizada não chega em produção.
HTML, PDF, dashboard, teste. Geram do mesmo arquivo, sempre sincronizados.
Em fintech global, QMDs derivados da base existente geraram testes automáticos que documentaram o legado e protegeram contra regressão.
Ver o caso completoEm 30 minutos a gente compartilha QMD funcional e mostra build executando, validando contrato e gerando docs em múltiplos formatos.
