Sobre este livro

Este é um livro vivo sobre governança de DevOps: como desenhar a entrega de software para que segurança, qualidade e conformidade sejam garantidas pela plataforma, e não pela disciplina de cada time.

Ele começa onde o manifesto termina. O manifesto diz por que mudar; este livro diz como fazer e como medir.

Como está organizado

• Práticas: o desenho de referência, da estrutura da organização no Azure DevOps à governança de arquitetura, com um glossário dos termos de CI/CD.
• Modelo de maturidade: 55 indicadores em 9 domínios, com critérios objetivos de N1 a N5 e uma regra de pontuação que classifica a organização.
• Dicionário: cada sigla, tecnologia e conceito de system design citado no livro, com o significado e uma referência para aprofundar. Todo termo leva para lá na primeira vez que aparece em uma página; passe o mouse para ver o resumo.
• Decisões do projeto: os ADRs que explicam por que o livro e suas ferramentas são do jeito que são.

Cada prática aponta para o domínio de auditoria que a mede, e cada domínio aponta de volta para a prática.

Por que “vivo”

O texto está em um repositório aberto e é publicado de novo a cada mudança aprovada. Toda página tem um link para ser editada.

• Discorda de uma prática ou de um limiar? Abra uma issue contando o seu contexto.
• Tem um indicador melhor? Proponha pelo modelo de issue de indicador.
• Achou um erro? Edite a página e abra um pull request.

As páginas de indicadores são geradas a partir de modelo/indicadores.yaml, que é a fonte única do modelo de maturidade.

Licença

O conteúdo está sob CC BY 4.0: use, adapte e redistribua, dando o crédito.

Práticas de system design para DevOps

O template é a política. Toda regra de segurança, qualidade e conformidade vive em código reutilizável que a plataforma impõe, e não em documentos que os times precisam lembrar de seguir.

Estas práticas formam um desenho de referência para entrega de software em organizações que usam Azure DevOps. Os conceitos valem para qualquer plataforma; os nomes de recursos são do Azure DevOps.

01 · Princípios de design

Oito princípios orientam todas as outras práticas. Quando duas regras parecerem conflitar, estes princípios desempatam. Vários deles vêm do 12-Factor, a metodologia de referência para aplicações prontas para a nuvem.

02 · Estrutura organizacional

Uma organização, poucos projetos por domínio de negócio e um projeto platform que publica tudo o que é compartilhado.

Organização

• Uma única organização conectada ao Entra ID. Várias organizações fragmentam auditoria, Artifacts e governança.
• Process template herdado e único (Agile ou Scrum customizado), com campos padronizados.
• Iterations com a mesma cadência em todos os projetos, o que viabiliza Delivery Plans entre times.

Projetos

Times

• Cada time é um Area Path dentro do projeto do seu domínio.
• O projeto platform concentra templates de pipeline, módulos de IaC, imagens base, extensões e a documentação da plataforma.
• A própria organização (projetos, grupos, policies, service connections) é gerenciada com o provider Terraform azuredevops.

Indicadores: D1 · Estrutura organizacional

03 · Repositórios e fluxo de trabalho

Trunk-based development com branches curtas, e a main protegida por políticas que nenhum time consegue desligar.

• Nomenclatura: <dominio>-<app>-<tipo>, por exemplo frota-abastecimento-api e frota-abastecimento-infra.
• Estrutura mínima de repo: README, required reviewers por path, azure-pipelines.yml, /docs/adr.
• Branches: main sempre implantável; feature branches com vida de no máximo alguns dias; release/* só quando houver suporte a múltiplas versões.

Branch policies obrigatórias na main

Versionamento

• Semantic Versioning (MAJOR.MINOR.PATCH) calculado no pipeline (GitVersion ou conventional commits), nunca à mão.
• A versão vira o nome do run, a tag git e o rótulo do artefato, o que liga as três coisas.

Indicadores: D2 · Repositórios e fluxo

04 · Pipelines como produto

Os times escrevem só o que é específico da aplicação; build, scans, publicação e deploy vêm de templates versionados do projeto platform.

Mecanismo de imposição

• Pipelines de aplicação usam extends para um template do platform, referenciado por tag (ref: refs/tags/v3).
• Required template check em Environments, service connections e agent pools de produção: um pipeline que não estende o template aprovado não consegue fazer o deploy.
• Classic pipelines desabilitados na organização; somente YAML.
• Parâmetros tipados no template expõem o que o time pode escolher (linguagem, testes extras) e escondem o que não pode (scans, assinatura).

# azure-pipelines.yml de uma aplicação
resources:
  repositories:
    - repository: templates
      type: git
      name: platform/pipeline-templates
      ref: refs/tags/v3

extends:
  template: java/servico.yml@templates
  parameters:
    jdk: 17
    testesIntegracao: true

Build pipeline (CI)

1. Restore com feeds internos (sem acesso direto à internet).
2. Compilação e testes unitários com cobertura.
3. SAST, SCA, secret scanning e IaC scanning.
4. Geração de SBOM e de provenance.
5. Publicação do artefato imutável, versionado e assinado.

Deployment pipeline (CD)

• Deployment jobs apontando para Environments, consumindo o artefato do CI pelo ID do run.
• Configuração por ambiente injetada no deploy (variable groups ligados ao Key Vault), nunca recompilada.
• Smoke test após cada deploy e verificação de saúde antes de promover.

Quality gates

Artifact repository

• Azure Artifacts para pacotes (Maven, npm), com upstream sources e views @prerelease / @release para promoção.
• Registry de imagens com retenção e bloqueio de tag mutável em produção.

Indicadores: D3 · Pipelines como produto

05 · Segurança da supply chain

Cada artefato que chega a produção precisa ter origem comprovada, componentes inventariados e scans aprovados, todos impostos pelo template.

Rumo ao SLSA

• Build isolado e efêmero: agentes descartados a cada execução, sem estado entre builds.
• Definição de build controlada: template obrigatório via extends e required template check.
• Provenance: gerada pelo pipeline (não pelo desenvolvedor), assinada, ligada ao commit e ao run ID.
• Verificação no deploy: o stage de produção recusa imagem sem assinatura ou provenance válida.

Dependências

• Todo download passa por feeds internos com upstream; agentes não acessam registros públicos diretamente.
• SBOMs enviados ao Dependency-Track viram o inventário vivo da organização e a base para responder a novos CVEs em minutos.

Indicadores: D4 · Supply chain

06 · Ambientes, agentes e infraestrutura

Os ambientes são recursos protegidos do Azure DevOps, e é neles, não no pipeline, que ficam as regras de entrada.

Environments

Agentes

• Self-hosted em scale set (VMSS) ou containers, com tear down after each use: build limpo e sem vazamento de segredo.
• Pools separados por zona de confiança (build vs deploy em produção), com permissão por projeto.
• Imagem do agente versionada e construída por pipeline, com as ferramentas pré-instaladas e pinadas.
• Rede de saída restrita: apenas feeds internos, registry e alvos de deploy.

Infraestrutura como código

• Terraform (ou Bicep) em repos *-infra, com o mesmo fluxo de PR, scan e plano revisado antes do apply.
• plan publicado como artefato do PR; apply só por pipeline, nunca da máquina de alguém.
• Detecção de drift agendada, com alerta.
• Paridade entre ambientes: mesma definição, parâmetros diferentes.

Indicadores: D5 · Ambientes, agentes e IaC

07 · Identidade e acesso

Ninguém recebe permissão como indivíduo e nenhum pipeline guarda segredo de longa duração.

Modelo de grupos (todos vindos do Entra ID)

Identidades de pipeline

• Service connections com Workload Identity Federation: sem client secret para rotacionar ou vazar.
• Uma service connection por projeto e por ambiente, protegida pelos mesmos checks do Environment.
• Segredos de aplicação no Key Vault, consumidos via variable groups vinculados.

Políticas de organização

• Projetos públicos desabilitados; acesso OAuth de aplicações de terceiros desabilitado.
• Criação de PAT restrita, sem full scope e com validade máxima curta.
• Conditional Access do Entra aplicado ao Azure DevOps.
• Audit log enviado continuamente (audit streaming) para Log Analytics ou SIEM.
• Revisão de acessos trimestral, automatizada a partir dos grupos.

Indicadores: D6 · Identidade e acesso

08 · Estratégias de deploy e release

Separe implantar (técnico, frequente, reversível) de liberar (decisão de negócio, via feature flag). Isso reduz risco sem reduzir frequência.

Recuperação

• Rollback: reexecutar o stage de deploy de um run anterior; funciona porque o artefato é imutável e o deploy é idempotente. Automatizado no hook on: failure.
• Roll forward: preferido quando há migração de dados; usa o mesmo pipeline, com caminho rápido de hotfix.
• Migrações de banco compatíveis com a versão anterior (expand/contract), para que o rollback seja sempre possível.

Controle de mudança

• Change management: mudanças padrão (pipeline verde, template aprovado) são pré-aprovadas; aprovação humana só para mudança normal ou emergencial. Integração com ITSM via check (ex.: ServiceNow) quando exigido.
• Deployment freeze: check de business hours ou check customizado consultando um calendário central de freeze; exceções registradas.
• Release management: histórico de deploys por Environment, release notes geradas a partir dos work items, e Delivery Plans para coordenar releases entre times.

Indicadores: D7 · Deploy e release

09 · Observabilidade e métricas

A plataforma mede a si mesma com as métricas DORA, extraídas automaticamente dos eventos do Azure DevOps e do monitoramento.

Feedback de produção

• Todo deploy emite um evento (versão, commit, run) para a stack de observabilidade, permitindo correlacionar anomalias com mudanças.
• Verificação pós-deploy automática (erros, latência, health checks) decide entre promover e reverter.
• Telemetria padronizada (OpenTelemetry) incluída nas imagens base e templates.

Auditoria

• Audit log da organização, histórico de Environments e SBOMs formam a trilha de evidência para auditorias e incidentes de segurança.
• Painel de conformidade por repo: policies ativas, template usado, scans em dia, dependências EOL.

Indicadores: D8 · Observabilidade e DORA

10 · Governança de arquitetura

A governança orienta por padrões e verifica por automação; revisão humana fica reservada para decisões de alto impacto.

Exceções

• Desvio do padrão = ADR com justificativa, dono e data de expiração.
• Exceções vencidas aparecem no painel de conformidade e voltam para o ARB.

Indicadores: D9 · Governança de arquitetura

11 · Antipadrões a evitar

12 · Roadmap de adoção e checklist

A adoção avança em quatro fases, e cada uma só termina quando o seu gate é verificável no painel de conformidade.

flowchart TB
    F1["Fase 1 · Fundação<br/>Org única + Entra ID<br/>Grupos e políticas<br/>Org em Terraform"]
    F2["Fase 2 · Golden path<br/>Templates CI/CD<br/>extends obrigatório<br/>Agentes efêmeros"]
    F3["Fase 3 · Supply chain<br/>Inventário via SBOM<br/>Artefato assinado<br/>Gates bloqueantes"]
    F4["Fase 4 · Otimização<br/>Métricas DORA<br/>Canary e blue-green<br/>Fitness functions"]
    F1 -- "Gate 1: 1º time no golden path" --> F2
    F2 -- "Gate 2: 100% dos repos em extends" --> F3
    F3 -- "Gate 3: prd exige artefato assinado" --> F4

As fases não têm datas fixas; o ritmo depende da capacidade do time de plataforma e do número de repositórios a migrar.

Checklist de conformidade por repositório

• Nome segue <dominio>-<app>-<tipo>
• Branch policies da main aplicadas (revisão, build validation, work item, comentários)
• Pipeline usa extends do template aprovado, em versão suportada
• Versão SemVer calculada pelo pipeline
• SAST, SCA, secret e IaC scanning ativos, sem críticos abertos
• SBOM publicado no Dependency-Track
• Artefato assinado, com provenance
• Deploy apenas via Environments com checks
• Service connection com Workload Identity Federation; segredos no Key Vault
• ADRs em /docs/adr para decisões relevantes
• Nenhum runtime ou dependência em EOL sem exceção registrada

Glossário de CI/CD, entrega e governança

Cada termo traz a definição e onde ele se materializa no Azure DevOps. Legenda: ✅ recurso nativo · 🔌 extensão ou ferramenta no pipeline · ⛔ fora do Azure DevOps.

Integração e entrega

Supply chain e segurança

Controle e conformidade

Estratégias de deploy

Governança de arquitetura

Dicionário

44 siglas, 46 tecnologias e 33 conceitos de system design usados neste livro, cada um com o significado e uma referência para aprofundar. Em todas as páginas, a primeira vez que um termo aparece ele leva para cá; passe o mouse para ver o resumo.

Siglas

12-Factor

The Twelve-Factor App · aplicação de doze fatores

Metodologia com doze práticas para construir aplicações prontas para a nuvem: configuração no ambiente, dependências declaradas, processos sem estado, paridade entre ambientes, entre outras. Muitos dos princípios deste livro, como build once deploy many, vêm dela.

Referência: 12factor.net

ACL

Access Control List · lista de controle de acesso

Lista que associa identidades a permissões sobre um recurso. No Azure DevOps, as ACLs são a forma como cada permissão é armazenada e podem ser consultadas pela API para auditar acessos.

Referência: Azure DevOps REST · Access Control Lists

ADO

Azure DevOps

Plataforma da Microsoft com repositórios Git, pipelines, quadros de trabalho, artefatos e planos de teste. É a plataforma de referência das práticas deste livro.

Referência: Documentação do Azure DevOps

ADR

Architecture Decision Record · registro de decisão de arquitetura

Documento curto que registra uma decisão de arquitetura, o contexto que a motivou e suas consequências. Neste livro, os ADRs ficam versionados junto do código e também registram as exceções ao padrão, com dono e prazo.

Referência: adr.github.io

API

Application Programming Interface · interface de programação de aplicações

Contrato pelo qual um sistema expõe dados e operações para outros sistemas. A coleta automatizada das evidências de auditoria usa as APIs REST do Azure DevOps e das ferramentas de segurança.

Referência: Azure DevOps REST API

ARB

Architecture Review Board · comitê de revisão de arquitetura

Grupo responsável por revisar e orientar decisões de arquitetura de alto impacto e exceções ao padrão. Neste livro, ele atua como revisor obrigatório de ADRs, não como aprovação caso a caso.

Referência: TOGAF · Architecture Board

ARM

Azure Resource Manager

Camada de gerenciamento do Azure que recebe as requisições de criação e alteração de recursos. Os ARM templates (JSON) são o formato para o qual o Bicep é compilado.

Referência: Microsoft Learn · Azure Resource Manager

CD

Continuous Delivery · entrega contínua

Prática de manter o software sempre em condição de ser implantado em produção, de forma frequente, controlada e repetível. Não confundir com continuous deployment, em que a implantação em produção é automática.

Referência: continuousdelivery.com

CI

Continuous Integration · integração contínua

Prática de integrar mudanças ao tronco principal com frequência, cada uma validada por build e testes automatizados. Neste livro, o CI roda em todo pull request como build validation.

Referência: Martin Fowler · Continuous Integration

CLI

Command-Line Interface · interface de linha de comando

Programa operado por comandos de texto no terminal. As ferramentas deste projeto são uma CLI em Rust chamada governanca.

Referência: MDN · Command line crash course

CNCF

Cloud Native Computing Foundation

Fundação, parte da Linux Foundation, que hospeda projetos de código aberto do ecossistema cloud native, como Kubernetes, OpenTelemetry, OpenFeature, Envoy e in-toto.

Referência: cncf.io

CVE

Common Vulnerabilities and Exposures · vulnerabilidades e exposições comuns

Catálogo público que dá um identificador único a cada vulnerabilidade conhecida, como CVE-2021-44228. É a referência usada por ferramentas de SCA e pelo Dependency-Track para dizer quais componentes estão afetados.

Referência: cve.org

DAST

Dynamic Application Security Testing · teste dinâmico de segurança de aplicações

Teste de segurança feito contra a aplicação em execução, de fora para dentro, simulando um atacante. Complementa o SAST e, neste livro, roda em homologação antes da promoção para produção.

Referência: OWASP · DAST

DORA

DevOps Research and Assessment · pesquisa e avaliação de DevOps

Programa de pesquisa que definiu as quatro métricas-chave de entrega de software: frequência de deploy, lead time para mudança, taxa de falha de mudança e tempo de recuperação.

Referência: dora.dev

EOL

End of Life · fim de vida

Data a partir da qual uma versão de software deixa de receber suporte e correções de segurança. Rodar componentes em EOL é um dos indicadores críticos do modelo de maturidade.

Referência: endoflife.date

HTTP

Hypertext Transfer Protocol · protocolo de transferência de hipertexto

Protocolo de comunicação da web, usado por navegadores e pelas APIs REST. Nos sites e APIs deste livro, sempre na forma segura, HTTPS.

Referência: MDN · HTTP

IaC

Infrastructure as Code · infraestrutura como código

Prática de descrever e provisionar infraestrutura em arquivos versionados, como Terraform ou Bicep, em vez de configurá-la à mão. Permite revisar, testar e reproduzir ambientes.

Referência: Microsoft · O que é infraestrutura como código

IEC

International Electrotechnical Commission · Comissão Eletrotécnica Internacional

Organização internacional de normas para tecnologias elétricas e eletrônicas. Publica normas de software em conjunto com a ISO, como a ISO/IEC 5962, que padroniza o SPDX.

Referência: iec.ch

ISO

International Organization for Standardization · Organização Internacional de Normalização

Organização que publica normas técnicas internacionais. No contexto deste livro, aparece na norma ISO/IEC 5962, que padroniza o formato SPDX de SBOM.

Referência: iso.org

ITSM

IT Service Management · gestão de serviços de TI

Conjunto de práticas para planejar, entregar e controlar serviços de TI, incluindo gestão de mudanças e de incidentes. Ferramentas de ITSM podem ser integradas como check de deploy.

Referência: PeopleCert · ITIL

JSON

JavaScript Object Notation · notação de objetos JavaScript

Formato de texto leve para troca de dados estruturados. É o formato das respostas das APIs e do resultado de governanca pontuar –json.

Referência: json.org

KQL

Kusto Query Language

Linguagem de consulta do Azure Data Explorer, do Log Analytics e do Microsoft Sentinel. É com ela que se consulta o log de auditoria enviado pelo audit streaming.

Referência: Microsoft Learn · Kusto Query Language

OAuth

Open Authorization · autorização aberta

Padrão aberto de autorização delegada, que permite a uma aplicação agir em nome do usuário sem conhecer a senha dele. Neste livro, o acesso OAuth de aplicações de terceiros fica desabilitado.

Referência: oauth.net · OAuth 2.0

OWASP

Open Worldwide Application Security Project · projeto aberto e mundial de segurança de aplicações

Fundação sem fins lucrativos que mantém guias, padrões e ferramentas abertas de segurança de aplicações, como o OWASP Top 10 e o ZAP.

Referência: owasp.org

PAT

Personal Access Token · token de acesso pessoal

Credencial gerada por um usuário para autenticar scripts e ferramentas em seu nome. Por ser de longa duração e ligada a uma pessoa, o livro recomenda restringir seu escopo e validade.

Referência: Azure DevOps · Personal access tokens

PIM

Privileged Identity Management · gestão de identidades privilegiadas

Serviço do Microsoft Entra ID que concede privilégios administrativos apenas quando necessários e por tempo limitado, com aprovação e auditoria.

Referência: Microsoft Entra · PIM

PR

Pull Request · solicitação de integração

Pedido para integrar as mudanças de uma branch em outra, com revisão e validações automáticas antes do merge. É a porta de entrada de toda mudança na branch principal.

Referência: Azure DevOps · Pull requests

REST

Representational State Transfer · transferência de estado representacional

Estilo de arquitetura para APIs sobre HTTP, baseado em recursos identificados por URLs e operações padronizadas. As APIs do Azure DevOps seguem esse estilo.

Referência: Roy Fielding · tese que definiu o REST

SAST

Static Application Security Testing · teste estático de segurança de aplicações

Análise do código-fonte, sem executá-lo, em busca de padrões vulneráveis. Neste livro, roda em todo pull request e bloqueia vulnerabilidades críticas novas.

Referência: OWASP · Source code analysis tools

SBOM

Software Bill of Materials · lista de materiais de software

Inventário formal dos componentes e dependências de um software, com versões e licenças. Gerado a cada build, nos formatos CycloneDX ou SPDX, é a base para responder rapidamente a novos CVEs.

Referência: CISA · SBOM

SCA

Software Composition Analysis · análise de composição de software

Análise das dependências de terceiros de um software para encontrar vulnerabilidades conhecidas, licenças problemáticas e componentes em EOL.

Referência: OWASP · Component Analysis

SDK

Software Development Kit · kit de desenvolvimento de software

Conjunto de bibliotecas e ferramentas para integrar uma aplicação a uma plataforma ou serviço.

Referência: AWS · What is an SDK?

SemVer

Semantic Versioning · versionamento semântico

Convenção de versões no formato MAJOR.MINOR.PATCH, em que cada parte indica o tipo de mudança: incompatível, nova funcionalidade compatível ou correção.

Referência: semver.org

SIEM

Security Information and Event Management · gestão de informações e eventos de segurança

Sistema que centraliza logs e eventos de segurança de várias fontes para correlação, alerta e investigação. O audit log do Azure DevOps deve ser enviado continuamente para um SIEM.

Referência: Microsoft · O que é SIEM

SLA

Service Level Agreement · acordo de nível de serviço

Compromisso formal sobre o nível de serviço que será entregue, normalmente com consequências se não for cumprido. É mais amplo e menos exigente que o SLO interno.

Referência: Google SRE · Service Level Objectives

SLO

Service Level Objective · objetivo de nível de serviço

Meta interna e mensurável de qualidade de um serviço, como disponibilidade ou latência. Neste livro, a plataforma é tratada como produto e tem os seus próprios SLOs.

Referência: Google SRE · Service Level Objectives

SLSA

Supply-chain Levels for Software Artifacts · níveis da cadeia de suprimentos para artefatos de software

Framework com níveis progressivos de garantias sobre como um artefato foi construído, da provenance documentada a builds isolados e verificáveis.

Referência: slsa.dev

SPDX

System Package Data Exchange · troca de dados de pacotes de sistemas

Padrão aberto, também norma ISO/IEC 5962, para descrever componentes, licenças e metadados de software. Chamava-se Software Package Data Exchange até a versão 3.0, de 2024. É um dos dois formatos comuns de SBOM, ao lado do CycloneDX.

Referência: spdx.dev

TI

Tecnologia da Informação

Área que cuida dos sistemas, da infraestrutura e dos serviços de tecnologia de uma organização. Em inglês, IT (Information Technology), como em ITSM.

URL

Uniform Resource Locator · localizador uniforme de recursos

Endereço que identifica um recurso na web, como uma página, um arquivo ou um endpoint de API.

Referência: MDN · URL

VM

Virtual Machine · máquina virtual

Computador emulado por software sobre um hardware físico. Agentes de pipeline e alvos de deploy podem rodar em VMs.

Referência: Microsoft Azure · O que é uma máquina virtual

VMSS

Virtual Machine Scale Sets · conjuntos de dimensionamento de máquinas virtuais

Recurso do Azure que cria e remove VMs idênticas sob demanda. No Azure DevOps, permite agentes self-hosted efêmeros, descartados após cada execução.

Referência: Azure DevOps · Scale set agents

YAML

YAML Ain’t Markup Language

Formato de serialização de dados legível por pessoas. Os pipelines do Azure DevOps e as fontes únicas deste projeto, como o modelo de indicadores e este dicionário, são escritos em YAML.

Referência: yaml.org

ZAP

Zed Attack Proxy

Ferramenta aberta de DAST, originalmente do OWASP, que testa aplicações web em execução em busca de vulnerabilidades.

Referência: zaproxy.org

Tecnologias e ferramentas

ADO Security Scanner

Módulo PowerShell de código aberto (ADOScanner, do projeto AzSK) que audita a configuração de organizações, projetos, pipelines e service connections do Azure DevOps contra controles de segurança. Útil para coletar evidências dos indicadores de identidade e acesso.

Referência: ADO Security Scanner no GitHub

ArchUnit

Biblioteca para escrever testes de arquitetura em Java: regras sobre dependências entre pacotes, camadas e convenções, executadas como testes de unidade. Um exemplo prático de fitness function.

Referência: archunit.org

Audit streaming

Recurso do Azure DevOps que envia o log de auditoria da organização, de forma contínua, para Log Analytics, Splunk ou Event Grid. Sem ele, o histórico fica limitado à retenção nativa e a trilha de auditoria se perde.

Referência: Microsoft Learn · Create audit streaming

Azure App Configuration

Serviço gerenciado do Azure para configuração centralizada e feature flags. Permite ligar e desligar funcionalidades em produção sem novo deploy.

Referência: Microsoft Learn · Azure App Configuration

Azure Artifacts

Serviço de feeds de pacotes do Azure DevOps (Maven, npm, NuGet, Python, Universal Packages), com upstream sources para espelhar repositórios públicos e views para promover versões. Peça central para garantir que todo build consuma dependências de fontes controladas.

Referência: Microsoft Learn · Azure Artifacts

Azure Key Vault

Cofre gerenciado do Azure para segredos, chaves e certificados. Neste livro, todo segredo de aplicação mora nele e chega ao pipeline por variable groups vinculados, nunca em variáveis locais.

Referência: Microsoft Learn · Azure Key Vault

Bicep

Linguagem declarativa da Microsoft para infraestrutura como código no Azure, compilada para ARM templates. Alternativa nativa ao Terraform quando a infraestrutura é só Azure.

Referência: Microsoft Learn · Bicep

Branch policies

políticas de branch

Regras do Azure Repos que protegem uma branch: número mínimo de revisores, build validation, work item vinculado, comentários resolvidos e bloqueio de push direto. São o que torna a main imune a atalhos.

Referência: Microsoft Learn · Branch policies and settings

Build validation

validação de build

Branch policy do Azure Repos que exige um pipeline de CI verde antes do merge de um pull request.

Referência: Microsoft Learn · Build validation

Checkov

Ferramenta de código aberto que analisa infraestrutura como código (Terraform, Bicep, Kubernetes, entre outros) em busca de configurações inseguras. Usada como IaC scanning no PR.

Referência: checkov.io

CodeQL

Motor de análise estática do GitHub que trata o código como dados consultáveis. É o SAST do GitHub Advanced Security, inclusive na versão para Azure DevOps.

Referência: codeql.github.com

Conditional Access

acesso condicional

Políticas do Microsoft Entra ID que liberam ou bloqueiam o acesso conforme usuário, dispositivo, local e risco. Aplicadas ao Azure DevOps, impedem acesso de máquinas não gerenciadas.

Referência: Microsoft Learn · Conditional Access

Conventional Commits

Convenção para mensagens de commit (feat:, fix:, feat!:) que permite calcular a próxima versão SemVer e gerar release notes automaticamente.

Referência: conventionalcommits.org

cosign

Ferramenta do projeto Sigstore para assinar e verificar imagens de contêiner e outros artefatos, e para anexar atestações (como provenance in-toto) a eles.

Referência: Sigstore · cosign

CycloneDX

Padrão aberto da OWASP para SBOM e outros inventários de software. É o formato adotado neste livro para os SBOMs gerados no build e enviados ao Dependency-Track.

Referência: cyclonedx.org

Delivery Plans

Visão do Azure Boards que mostra, numa linha do tempo, o trabalho de vários times e as dependências entre eles. Exige que os times compartilhem projeto e convenções.

Referência: Microsoft Learn · Delivery Plans

Dependency-Track

Plataforma de código aberto da OWASP que recebe SBOMs e mantém o inventário vivo dos componentes de cada aplicação, cruzando-os com vulnerabilidades, licenças e fim de vida.

Referência: dependencytrack.org

Environments

Recurso do Azure Pipelines que representa um alvo de deploy (dev, hml, prd) com checks (aprovação, required template, janela de horário) e histórico de quem implantou o quê. Todo deploy em produção passa por um.

Referência: Microsoft Learn · Create and target an environment

Envoy

Proxy de borda e de serviço de código aberto, da CNCF. Citado como forma de espelhar tráfego de produção (shadow traffic) para uma nova versão.

Referência: envoyproxy.io

Git

Sistema de controle de versão distribuído, base dos repositórios do Azure Repos e de todo o fluxo de pull requests descrito neste livro.

Referência: git-scm.com

GitHub Advanced Security

Conjunto de recursos de segurança do GitHub (secret scanning com push protection, dependency scanning e code scanning com CodeQL), disponível também para Azure DevOps.

Referência: Microsoft Learn · GitHub Advanced Security for Azure DevOps

gitleaks

Ferramenta de código aberto que procura segredos (chaves, tokens, senhas) em repositórios Git, no histórico e em cada commit. Alternativa ao push protection.

Referência: gitleaks no GitHub

GitVersion

Ferramenta que calcula a versão SemVer a partir do histórico do Git (branches, tags e mensagens), para que a versão nunca seja digitada à mão.

Referência: gitversion.net

in-toto

Framework da CNCF para atestar cada etapa da cadeia de suprimentos de software. O formato de atestação in-toto é o usado pela provenance do SLSA.

Referência: in-toto.io

Kubernetes

Orquestrador de contêineres de código aberto. No Azure Pipelines, os deployments para Kubernetes suportam nativamente a estratégia canary.

Referência: kubernetes.io

Log Analytics

Serviço do Azure Monitor para armazenar e consultar logs com KQL. Destino recomendado do audit streaming do Azure DevOps.

Referência: Microsoft Learn · Log Analytics

Maven

Ferramenta de build e gerenciador de dependências do ecossistema Java. Citado como um dos tipos de pacote servidos pelo Azure Artifacts.

Referência: maven.apache.org

mdBook

Gerador de livros a partir de Markdown, do ecossistema Rust. É o que publica este livro; a CLI governanca atua como pré-processador dele para ligar páginas e termos do dicionário.

Referência: Documentação do mdBook

Microsoft Entra ID

Serviço de identidade da Microsoft (antigo Azure Active Directory). A organização do Azure DevOps é ligada a ele, e todos os grupos e acessos vêm dele.

Referência: Microsoft Learn · Microsoft Entra ID

nginx

Servidor web e proxy reverso. Citado como forma de trocar o upstream num deploy blue-green ou de espelhar tráfego com a diretiva mirror.

Referência: nginx.org

npm

Gerenciador de pacotes do ecossistema JavaScript/Node.js. Um dos tipos de pacote servidos pelo Azure Artifacts.

Referência: docs.npmjs.com

OpenFeature

Especificação aberta da CNCF para feature flags, com SDKs que isolam o código do fornecedor de flags escolhido.

Referência: openfeature.dev

OpenTelemetry

Padrão aberto da CNCF para traces, métricas e logs. Incluído nas imagens base, garante telemetria uniforme entre serviços e correlação com os eventos de deploy.

Referência: opentelemetry.io

PowerShell

Shell e linguagem de script da Microsoft, multiplataforma. Base do ADO Security Scanner.

Referência: Microsoft Learn · PowerShell

Required template check

Check de um Environment ou service connection do Azure Pipelines que só autoriza pipelines que estendem um template aprovado. É o mecanismo que transforma o template em política.

Referência: Microsoft Learn · Approvals and checks

Rust

Linguagem de programação com foco em segurança de memória e desempenho. A CLI governanca, que valida o modelo e gera o livro, é escrita nela (ADR 0003).

Referência: rust-lang.org

Semgrep

Ferramenta de análise estática de código aberto, com regras fáceis de escrever. Alternativa ao CodeQL para SAST no pull request.

Referência: semgrep.dev

Service connection

conexão de serviço

Credencial que o Azure Pipelines usa para acessar um sistema externo (Azure, registry, cluster). Neste livro, uma por projeto e ambiente, sempre com Workload Identity Federation.

Referência: Microsoft Learn · Service connections

ServiceNow

Plataforma de ITSM. Pode ser integrada ao Azure Pipelines como check de um Environment, para que a abertura e o fechamento da mudança aconteçam no próprio deploy.

Referência: Microsoft Learn · Integrate with ServiceNow change management

SonarQube

Plataforma de qualidade de código: cobertura, duplicação, code smells e vulnerabilidades, com quality gates que podem bloquear o pipeline.

Referência: Documentação do SonarQube

Terraform

Ferramenta de infraestrutura como código da HashiCorp, com estado e plano de mudanças. Usada aqui também para gerenciar a própria organização do Azure DevOps como código.

Referência: developer.hashicorp.com/terraform

Traefik

Proxy reverso e balanceador de carga para ambientes de contêineres. Citado, como o nginx, para trocar o upstream num deploy blue-green.

Referência: doc.traefik.io

Trivy

Scanner de código aberto da Aqua Security para vulnerabilidades em imagens, dependências e infraestrutura como código; também gera SBOM em CycloneDX.

Referência: trivy.dev

Unleash

Plataforma de feature flags de código aberto, que pode ser hospedada pela própria organização.

Referência: docs.getunleash.io

Variable groups

grupos de variáveis

Conjuntos de variáveis compartilhadas entre pipelines do Azure DevOps. Quando vinculados a um Key Vault, entregam segredos ao pipeline sem guardá-los no Azure DevOps.

Referência: Microsoft Learn · Variable groups

Workload Identity Federation

Forma de autenticação em que o pipeline troca um token emitido pelo Azure DevOps por um token do Entra ID, via OpenID Connect. Elimina segredos de longa duração nas service connections.

Referência: Microsoft Learn · Workload identity federation

Conceitos de system design

Agente efêmero

Agente de build criado para um único job e descartado em seguida. Nada vaza de um build para o próximo, o que fecha uma porta comum de ataque à supply chain.

Referência: Microsoft Learn · Managed DevOps Pools · Stateless pools

Artefato imutável

Artefato que, uma vez publicado, nunca é alterado nem sobrescrito: uma nova mudança gera uma nova versão. É o que permite promover exatamente o que foi testado.

Referência: 12factor.net · Build, release, run

Blue-green deployment

Estratégia com dois ambientes de produção idênticos: a nova versão sobe no ocioso e o tráfego é trocado de uma vez. O rollback é trocar de volta.

Referência: Martin Fowler · BlueGreenDeployment

Build once, deploy many

Princípio de compilar o artefato uma única vez e promover esse mesmo artefato por todos os ambientes, mudando só a configuração. O que chega a produção é o que foi testado.

Referência: 12factor.net · Build, release, run

Canary deployment

implantação canário

Liberação gradual da nova versão para uma fração pequena do tráfego, aumentando conforme as métricas confirmam que está saudável.

Referência: Martin Fowler · CanaryRelease

Change management

gestão de mudanças

Processo de avaliar, aprovar e registrar mudanças em produção. Neste livro, mudanças padrão são pré-aprovadas pelo próprio pipeline e o registro é automático.

Referência: Atlassian · Change management

Continuous Deployment

implantação contínua

Extensão da entrega contínua em que toda mudança que passa no pipeline vai para produção sem aprovação manual.

Referência: Martin Fowler · ContinuousDelivery

Dark launch

Colocar uma funcionalidade em produção sem expô-la aos usuários, geralmente atrás de uma feature flag, para testá-la com tráfego real.

Referência: Martin Fowler · DarkLaunching

Deployment freeze

congelamento de deploys

Período em que deploys em produção ficam bloqueados (fechamento contábil, Black Friday). Implementado como check do Environment, não como e-mail.

Referência: Microsoft Learn · Business hours check

Drift

desvio de configuração

Diferença entre a infraestrutura real e a declarada no código, causada por mudanças manuais. Detectada com plan agendado e tratada como incidente.

Referência: HashiCorp · Detecting drift

Everything as code

tudo como código

Princípio de manter pipelines, infraestrutura, políticas e a própria configuração da organização em repositórios versionados, revisados e aplicados por pipeline.

Referência: HashiCorp · Everything as code

Expand/contract

expandir e contrair

Técnica para mudar esquemas e interfaces sem quebrar quem usa: primeiro expande (o novo convive com o antigo), migra os consumidores e só então contrai. Mantém o rollback possível.

Referência: Martin Fowler · ParallelChange

Feature flag

chave de funcionalidade

Mecanismo para ligar e desligar uma funcionalidade em tempo de execução, sem novo deploy. Separa a decisão técnica de implantar da decisão de negócio de liberar.

Referência: Martin Fowler · Feature Toggles

Fitness function

função de aptidão

Verificação automatizada de uma característica arquitetural (dependências, latência, acoplamento), executada no CI para que a arquitetura não se degrade em silêncio.

Referência: Thoughtworks · Fitness function-driven development

Golden path

caminho pavimentado

O caminho padrão, suportado e mais fácil para fazer algo (criar um serviço, um pipeline). Não é obrigatório por decreto: é obrigatório porque é o mais simples.

Referência: Spotify Engineering · How we use Golden Paths

Idempotência

Propriedade de uma operação que produz o mesmo resultado quando executada uma ou várias vezes. Um deploy idempotente pode ser repetido sem medo.

Referência: MDN · Idempotente

Just-in-time

acesso no momento da necessidade

Acesso elevado concedido só quando necessário e por tempo limitado, com aprovação e registro, em vez de permanente. No Azure, implementado com o PIM.

Referência: Microsoft Learn · Privileged Identity Management

Lead time

tempo de entrega

Tempo entre o primeiro commit de uma mudança e sua chegada a produção. Uma das quatro métricas DORA.

Referência: DORA · Software delivery performance metrics

Menor privilégio

Princípio de dar a cada pessoa ou identidade só as permissões necessárias para sua tarefa, pelo tempo necessário.

Referência: NIST · Least privilege

Observabilidade

Capacidade de entender o estado interno de um sistema a partir do que ele emite: logs, métricas e traces. Neste livro, inclui correlacionar cada deploy com a saúde do serviço.

Referência: OpenTelemetry · Observability primer

Plataforma como produto

Tratar a plataforma interna (templates, agentes, ambientes) como um produto, com usuários, roadmap e métricas de adoção, em vez de um conjunto de tickets.

Referência: Team Topologies · Platform as a product

Provenance

proveniência

Atestação assinada de como, onde e a partir de quê um artefato foi construído. Verificada no deploy, impede que algo fora do pipeline chegue a produção.

Referência: SLSA · Provenance

Quality gate

portão de qualidade

Conjunto de condições objetivas (testes, cobertura, vulnerabilidades) que um artefato precisa cumprir para seguir no pipeline. Bloqueante, não informativo.

Referência: SonarQube · Quality gates

Release management

gestão de releases

Planejamento, coordenação e controle de quando e como versões chegam aos usuários.

Referência: Atlassian · Release management

Roll forward

Recuperar de uma falha publicando rapidamente uma correção, em vez de voltar à versão anterior. Preferido quando o rollback é arriscado, como após uma migração de dados.

Referência: Microsoft Learn · Safe deployment practices

Rollback

Voltar para a versão anterior, conhecida como boa, quando a nova falha. Precisa ser testado e rápido; com artefatos imutáveis, é só reimplantar o anterior.

Referência: Microsoft Learn · Safe deployment practices

Rolling update

Estratégia que substitui as instâncias aos poucos, algumas de cada vez, mantendo o serviço no ar.

Referência: Kubernetes · Rolling update

Secret scanning

varredura de segredos

Detecção automática de segredos expostos em código e histórico. Com push protection, o commit é bloqueado antes de chegar ao servidor.

Referência: Microsoft Learn · Secret scanning

Shadow traffic

tráfego espelhado

Duplicar o tráfego real de produção para uma nova versão, sem usar a resposta, para validá-la sob carga real sem afetar usuários.

Referência: Envoy · Request mirroring

Shift-left

Antecipar verificações de qualidade e segurança para o início do fluxo (no PR, no editor), onde corrigir é mais barato.

Referência: Microsoft Learn · Shift left testing

Software supply chain security

segurança da cadeia de suprimentos de software

Proteção de tudo o que entra no software e de como ele é construído: dependências, ferramentas, pipelines e artefatos. SBOM, assinatura e provenance são suas peças centrais.

Referência: SLSA · About

Technology radar

radar de tecnologia

Instrumento para comunicar quais tecnologias adotar, testar, avaliar ou evitar, revisado periodicamente pela governança de arquitetura.

Referência: Thoughtworks Technology Radar

Trunk-based development

desenvolvimento baseado em tronco

Modelo em que todos integram na branch principal com frequência, usando branches de vida curta. Reduz conflitos de merge e é pré-requisito para CI de verdade.

Referência: trunkbaseddevelopment.com

Fonte: modelo/dicionario.yaml.

Modelo de maturidade e auditoria

Cada prática vira um ou mais indicadores mensuráveis, cada um com critério objetivo para os níveis N1 a N5. A organização recebe um nível por domínio (D1 a D9) e um nível geral, calculados a partir de evidências coletadas das APIs do Azure DevOps e das ferramentas da plataforma.

O modelo foi desenhado para ser auditável: todo critério aponta para uma evidência que pode ser extraída e reproduzida por outra pessoa, sem depender de entrevista.

• Níveis, pesos e índice de indicadores (gerado a partir de modelo/indicadores.yaml)
• Coleta automatizada das evidências
• Modelo de relatório de auditoria

Método de pontuação

O nível geral é a média ponderada dos domínios, mas nenhum domínio pode ficar mais de um nível abaixo do resultado: o elo mais fraco limita a nota.

Escopo e janela

• População: repositórios ativos (commit nos últimos 90 dias) e pipelines com execução nos últimos 90 dias. Repos arquivados ficam fora.
• Janela de evidência: 90 dias corridos anteriores à data da auditoria.
• Percentuais são sempre calculados sobre essa população.

Regras

1. Nota do indicador (s): o maior nível cujo critério é atendido por completo. Os critérios são cumulativos; sem evidência, a nota é N1.
2. Indicadores críticos (marcados com ★): o domínio não passa de um nível acima do pior indicador crítico.
3. Nível do domínio (L_d): média das notas dos indicadores, truncada, aplicado o teto dos críticos.
4. Nível geral (L_org): média ponderada dos domínios, arredondada (0,5 para cima), com teto de um nível acima do pior domínio. Aqui se arredonda em vez de truncar porque o teto já pune o domínio mais fraco; truncar puniria duas vezes.

L_d = \min\left( \left\lfloor \frac{1}{n_d}\sum_{i=1}^{n_d} s_i \right\rfloor,\ \min_{i \in \bigstar} s_i + 1 \right)

L_{org} = \min\left( \left\lfloor \frac{\sum_d w_d \, L_d}{\sum_d w_d} + \frac{1}{2} \right\rfloor,\ \min_d L_d + 1 \right)

O cálculo está implementado em ferramentas/src/pontuacao.rs, com aritmética inteira (pesos em centésimos) e é executado com governanca pontuar. Os pesos são uma proposta inicial e podem ser calibrados, desde que fixados antes da auditoria e versionados no YAML.

Níveis, pesos e indicadores

Modelo versão 0.1.0: 9 domínios, 55 indicadores, dos quais 17 críticos (★).

Níveis de maturidade

A passagem de N3 para N4 é o salto mais importante: a prática deixa de depender da disciplina dos times e passa a ser imposta pela plataforma.

Domínios e pesos

Janela de evidência: 90 dias. População: Repositórios com commit e pipelines com execução dentro da janela; repositórios arquivados ficam fora.

Fonte: modelo/indicadores.yaml.

D1 · Estrutura organizacional

• Peso: 1 (base, de baixo risco direto)
• Prática: 02 · Estrutura organizacional

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D2 · Repositórios e fluxo de trabalho

• Peso: 1,5 (porta de entrada de toda mudança)
• Prática: 03 · Repositórios e fluxo de trabalho

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D3 · Pipelines como produto

• Peso: 2 (mecanismo que impõe todos os outros controles)
• Prática: 04 · Pipelines como produto

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D4 · Segurança da supply chain

• Peso: 2 (risco de segurança direto)
• Prática: 05 · Segurança da supply chain

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D5 · Ambientes, agentes e infraestrutura

• Peso: 1,5 (controle de acesso à produção)
• Prática: 06 · Ambientes, agentes e infraestrutura

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D6 · Identidade e acesso

• Peso: 2 (risco de segurança direto)
• Prática: 07 · Identidade e acesso

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D7 · Deploy e release

• Peso: 1 (afeta estabilidade e recuperação)
• Prática: 08 · Estratégias de deploy e release

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D8 · Observabilidade e DORA

• Peso: 1 (base para melhoria contínua)
• Prática: 09 · Observabilidade e métricas

As métricas DORA são avaliadas pela mediana dos serviços em produção. A partir de N3, a coleta tem de ser automática; número levantado à mão só vale para N2.

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

D9 · Governança de arquitetura

• Peso: 1 (efeito de longo prazo)
• Prática: 10 · Governança de arquitetura

N1 significa que o critério de N2 não foi atingido. ★ indica indicador crítico.

Fonte: modelo/indicadores.yaml.

Coleta automatizada das evidências

Um pipeline agendado lê as APIs abaixo, grava um snapshot JSON por auditoria e calcula os níveis; o snapshot é a evidência reproduzível.

Limites da automação

• Algumas políticas de organização (D6.5) e registros do ARB (D9.5) não têm API pública completa: a evidência é captura de tela datada ou ata, anexada ao snapshot.
• Confira a versão das APIs (api-version) na documentação antes de implementar o coletor.
• O ADO Security Scanner (módulo PowerShell ADOScanner, do projeto AzSK) cobre parte dos controles de D2, D3 e D6 e pode acelerar a primeira versão.

Modelo de relatório de auditoria

O relatório começa pelo nível geral e pelo domínio que o limita; detalhes por indicador ficam em anexo, junto com o snapshot. A tabela de scorecard pode ser gerada com governanca pontuar <avaliacao.yaml>.

Cabeçalho

• Organização auditada, data da auditoria, janela de evidência (90 dias) e população (nº de repos e pipelines ativos).
• Auditor e versão do modelo (campo versao de modelo/indicadores.yaml).
• Nível geral: N_ (nome do nível) e domínio limitante.

Scorecard

Fechamento

1. Os 5 gaps de maior impacto, cada um com o indicador, o nível atual e o nível-alvo.
2. Plano de ação com dono e prazo, priorizando primeiro os indicadores críticos (★) que limitam a nota.
3. Data da próxima auditoria (recomendado: trimestral, com a coleta rodando de forma contínua entre elas).

0001 · O template é a política

• Status: aceita
• Data: 2026-10-17
• Decisores: Rogério Figueiredo

Contexto

Padrões publicados apenas como documentos dependem da disciplina de cada time. Com dezenas de times e centenas de repositórios, isso produz divergência, retrabalho e controles de segurança aplicados de forma desigual.

Decisão

Toda regra de segurança, qualidade e conformidade é implementada como código reutilizável (templates de pipeline, módulos de IaC, políticas da organização) e imposta pela plataforma: pipelines usam extends, e os recursos protegidos de produção exigem o template aprovado.

Consequências

• Uma correção no template chega a todos os pipelines sem que cada time precise agir.
• O time de plataforma passa a ser dono de um produto, com versionamento, compatibilidade e suporte.
• Desvios continuam possíveis, mas só como exceção registrada em ADR, com dono e prazo.

0002 · Indicadores como fonte única em YAML

• Status: aceita
• Data: 2026-10-17
• Decisores: Rogério Figueiredo

Contexto

O modelo de maturidade precisa ser lido por pessoas (documentação), validado (estrutura consistente) e usado por máquinas (cálculo dos níveis e, no futuro, o coletor). Manter essas três formas à mão garante que elas divirjam.

Decisão

Os níveis, os pesos dos domínios e todos os indicadores ficam em modelo/indicadores.yaml. A CLI governanca valida o arquivo (tipos estritos e regras de consistência), e modelo/schema.json dá autocompletar e validação no editor. As páginas em docs/maturidade/indicadores/ são geradas a partir dele, e o CI falha se estiverem desatualizadas.

Consequências

• Mudar um limiar é um pull request em um único arquivo, revisado como qualquer código.
• O cálculo de pontuação e o futuro coletor leem a mesma fonte que a documentação.
• As páginas geradas não devem ser editadas à mão.

0003 · Ferramentas em Rust

• Status: aceita
• Data: 2026-10-17
• Decisores: Rogério Figueiredo

Contexto

O repositório precisa de ferramentas para validar o modelo, gerar a documentação e calcular a pontuação. O próximo passo é um coletor que chama as APIs do Azure DevOps e roda em pipelines de várias organizações, onde instalar um runtime e dependências é atrito.

Decisão

As ferramentas são uma única CLI em Rust, governanca, no crate ferramentas/. O modelo é desserializado com tipos estritos (campos desconhecidos são rejeitados) e a pontuação usa aritmética inteira.

Consequências

• Um binário estático, sem runtime, fácil de distribuir para agentes de pipeline.
• Erros de estrutura do modelo são pegos na leitura, antes das regras de consistência.
• O coletor futuro entra como novo subcomando da mesma CLI, reaproveitando o modelo tipado.
• O livro usa o mdBook, gerador do ecossistema Rust; a própria CLI é o pré-processador que ajusta os links.
• Contribuir com código exige toolchain Rust; contribuir com conteúdo continua exigindo só Markdown e YAML.

NNNN · Título curto da decisão

• Status: proposta | aceita | substituída por NNNN | depreciada
• Data: AAAA-MM-DD
• Decisores: nomes ou grupos

Contexto

Qual problema ou força motivou a decisão.

Decisão

O que foi decidido, em uma ou duas frases afirmativas.

Consequências

O que fica mais fácil, o que fica mais difícil e o que precisa acontecer a seguir.

Exceção (se for um desvio do padrão)

• Dono:
• Expira em: AAAA-MM-DD