YAML na Prática : O guia do Programador COBOL Padawan para dominar configurações, automação e infraestrutura sem provocar um ABEND na indentação

 

Bellacosa Mainframe e o yaml na pratica e sem misterios

☕ Um Café no Bellacosa Mainframe

YAML na Prática sem Mistérios

O guia do Programador COBOL Padawan para dominar configurações, automação e infraestrutura sem provocar um ABEND na indentação

Imagine a seguinte cena.

Você passou anos navegando pelos corredores seguros do IBM Z. Conhece JCL, COBOL, CICS, Db2, VSAM, SDSF, RACF e talvez até tenha algumas cicatrizes de batalhas contra um S0C7 ocorrido às três da manhã.

Então, certo dia, alguém da equipe DevOps aparece e diz:

— Precisamos alterar o arquivo YAML do pipeline.

Você olha para a tela e encontra algo parecido com isto:

aplicacao:
  nome: CONTAS
  linguagem: COBOL
  ambiente: homologacao

Não há IDENTIFICATION DIVISION.

Não há ponto final obrigatório.

Não há colunas 7, 8 ou 72.

Não há //SYSIN DD *.

Mesmo assim, aqueles espaços aparentemente inocentes controlam aplicações, pipelines, containers, provisionamento de infraestrutura e processos automatizados.

Bem-vindo ao universo do YAML.

Para o programador mainframe, aprender YAML não significa abandonar COBOL, JCL ou o IBM Z. Significa construir uma ponte entre o processamento corporativo tradicional e o mundo de automação, APIs, Git, CI/CD, Ansible, Kubernetes, z/OSMF, Zowe e infraestrutura como código.

O YAML pode parecer simples, mas possui uma regra implacável:

A máquina não enxerga beleza estética. Ela enxerga estrutura.

Um espaço colocado no lugar errado pode alterar completamente o significado do documento.

Pegue sua caneca de café, ajuste os sensores da Enterprise e prepare-se. Vamos explorar YAML do básico ao laboratório prático.

---

1. Afinal, o que é YAML?

YAML é uma linguagem de serialização de dados legível por humanos, muito utilizada para representar configurações e estruturas de informação.

A versão oficial da especificação é a YAML 1.2.2, publicada para corrigir erros e esclarecer pontos da versão 1.2, sem introduzir mudanças normativas fundamentais.

Serializar dados significa representar informações estruturadas em um formato que possa ser:

• gravado em arquivo;

• transmitido entre sistemas;

• interpretado por programas;

• armazenado em repositórios;

• usado para configurar ferramentas;

• convertido para objetos em diferentes linguagens.

A sigla YAML significa:

YAML Ain’t Markup Language

Ou, em português:

YAML não é uma linguagem de marcação.

Trata-se de um acrônimo recursivo, uma brincadeira clássica da cultura da computação.

Isso procura deixar claro que YAML não foi criado para formatar páginas como HTML. Seu objetivo principal é representar dados.

Um arquivo YAML pode descrever:

• servidores;

• aplicações;

• ambientes;

• parâmetros de execução;

• pipelines;

• inventários;

• jobs;

• containers;

• permissões;

• tarefas de automação;

• configurações de testes;

• serviços e dependências.

No universo mainframe, ele pode representar:

• nomes de datasets;

• subsistemas CICS;

• regiões IMS;

• bibliotecas de carga;

• parâmetros de compilação;

• aplicações COBOL;

• ambientes de desenvolvimento;

• comandos TSO;

• tarefas do Ansible;

• definições de pipelines;

• informações de deploy;

• configurações do Zowe;

• chamadas ao z/OSMF;

• propriedades usadas pelo IBM Dependency Based Build.

---

2. YAML não é uma linguagem de programação

Esse ponto é essencial.

YAML não possui, por si só:

• comandos executáveis;

• estruturas de repetição;

• processamento de arquivos;

• cálculos;

• acesso a banco de dados;

• chamadas de subprogramas;

• controle transacional;

• gerenciamento de memória.

Ele apenas descreve dados.

Considere:

programa:
  nome: PGMPAG01
  linguagem: COBOL
  compilacao: obrigatoria

Esse documento não compila o programa.

Ele apenas declara informações.

Outra ferramenta poderá ler esse arquivo e decidir:

1. localizar o fonte PGMPAG01;

2. executar uma compilação;

3. realizar o bind do programa;

4. publicar o módulo de carga;

5. iniciar os testes.

Portanto, pense no YAML como um SYSIN moderno e estruturado.

No mainframe, é comum entregar parâmetros para um utilitário:

//SYSIN DD *
  DELETE CLIENTES
  DEFINE CLUSTER(...)
  LISTCAT
/*

No mundo da automação, uma ferramenta pode receber parâmetros em YAML:

operacao: criar
dataset: USER01.TESTE.COBOL
tipo: biblioteca
formato:
  recfm: FB
  lrecl: 80

O princípio é parecido:

O arquivo descreve o que desejamos. Outra ferramenta interpreta e executa.

---

3. Onde um mainframer encontrará YAML?

YAML aparece com frequência crescente na modernização do IBM Z.

Ansible

Playbooks do Ansible são normalmente escritos em YAML.

- name: Verificar datasets
  hosts: zos
  tasks:
    - name: Consultar biblioteca COBOL
      ibm.ibm_zos_core.zos_data_set:
        name: USER01.COBOL
        state: present

Pipelines de CI/CD

GitHub Actions, GitLab CI, Azure DevOps e outras plataformas usam YAML para descrever pipelines.

jobs:
  compilar:
    steps:
      - name: Compilar COBOL
        run: python compilar.py

Kubernetes

Objetos como pods, deployments, services e configurações são frequentemente declarados em YAML.

Zowe

Arquivos de perfil e configurações de ferramentas do ecossistema Zowe podem envolver estruturas YAML.

IBM Dependency Based Build

Configurações de build e processos de automação podem utilizar YAML direta ou indiretamente, dependendo da arquitetura adotada.

Testes automatizados

Ferramentas podem usar YAML para definir:

• massa de testes;

• valores de entrada;

• resultados esperados;

• ambientes;

• parâmetros de conexão.

Infraestrutura como código

YAML também aparece em ferramentas que provisionam, configuram ou descrevem ambientes de infraestrutura.

Por isso, conhecer YAML é como aprender a interpretar painéis de uma nave moderna. Você talvez não tenha construído o motor de dobra, mas precisa entender os controles.

---

4. O primeiro segredo: YAML é uma árvore

Um arquivo YAML deve ser imaginado como uma árvore hierárquica.

Veja:

aplicacao:
  nome: PAGAMENTOS
  plataforma: IBM Z
  componentes:
    - COBOL
    - CICS
    - Db2

A raiz possui uma chave chamada aplicacao.

Dentro dela existem:

• nome;

• plataforma;

• componentes.

E componentes contém uma lista.

Podemos imaginar:

aplicacao
├── nome
├── plataforma
└── componentes
    ├── COBOL
    ├── CICS
    └── Db2

Essa visão ajuda muito o programador COBOL.

Pense em uma estrutura semelhante a uma área de dados:

01 WS-APLICACAO.
   05 WS-NOME          PIC X(20).
   05 WS-PLATAFORMA    PIC X(10).
   05 WS-COMPONENTES.
      10 WS-COMPONENTE OCCURS 3 TIMES PIC X(10).

Não é uma correspondência perfeita, mas a analogia é excelente para começar.

---

5. Os componentes fundamentais

5.1 Chave e valor

A estrutura mais comum é:

chave: valor

Exemplo:

programa: PGMCAD01
linguagem: COBOL

O espaço depois dos dois-pontos é importante.

Prefira:

programa: PGMCAD01

Evite:

programa:PGMCAD01

5.2 Mapas

Um mapa agrupa pares de chave e valor.

programa:
  nome: PGMCAD01
  tipo: batch
  linguagem: COBOL

programa contém um mapa com três propriedades.

Em COBOL, isso lembra um grupo de nível 01 com campos subordinados.

5.3 Listas

As listas são indicadas por hífens:

bibliotecas:
  - USER01.COBOL
  - USER01.COPYBOOK
  - USER01.JCL

Isso se aproxima conceitualmente de uma tabela OCCURS.

05 WS-BIBLIOTECA OCCURS 3 TIMES PIC X(44).

5.4 Lista de objetos

Podemos ter vários elementos complexos:

programas:
  - nome: PGMCAD01
    tipo: batch
    linguagem: COBOL

  - nome: PGMCIC01
    tipo: online
    linguagem: COBOL

Cada item da lista possui suas próprias propriedades.

5.5 Booleanos

ativo: true
compilar: false

Para arquivos modernos, prefira true e false.

Evite depender de palavras como yes, no, on e off, pois bibliotecas baseadas em versões ou esquemas diferentes do YAML podem tratá-las de formas distintas.

Quando houver dúvida sobre o tipo, use aspas:

resposta: "yes"
estado: "on"

5.6 Números

timeout: 30
quantidade_retentida: 10
percentual: 99.5

5.7 Valores nulos

responsavel: null

Isso representa ausência de valor.

5.8 Comentários

# Aplicação responsável pelo cadastro de clientes
aplicacao: CLIENTES

Comentários começam com #.

Eles são úteis, mas não devem substituir uma documentação adequada.

---

6. A Lei Suprema da Indentação

Em COBOL tradicional, a coluna sempre teve grande importância.

YAML também é profundamente sensível ao posicionamento, porém usa indentação para representar hierarquia.

Observe:

aplicacao:
  nome: FATURAMENTO
  ambiente: producao

Os campos nome e ambiente pertencem a aplicacao.

Agora veja:

aplicacao:
  nome: FATURAMENTO
ambiente: producao

Aqui, ambiente não pertence mais a aplicacao. Ele está no nível principal do documento.

O arquivo pode continuar sintaticamente válido, mas seu significado mudou.

Esse é um dos erros mais perigosos em YAML: o documento pode ser aceito pelo parser, mas representar outra estrutura.

Nunca use TAB para indentar

Use espaços.

A especificação do YAML trabalha com espaços na indentação, não com caracteres de tabulação.

Uma convenção segura é usar dois espaços por nível:

aplicacao:
  banco:
    nome: DB2P
    tabelas:
      - CLIENTES
      - CONTAS

Não existe obrigação universal de usar exatamente dois espaços, mas a consistência é obrigatória.

É como trabalhar com níveis COBOL:

01 REGISTRO.
   05 CLIENTE.
      10 NOME.
      10 CONTA.

O nível informa a estrutura. No YAML, a indentação cumpre esse papel.

---

7. Aspas: quando usar?

Muitos valores não precisam de aspas:

nome: FATURAMENTO
ambiente: producao

Entretanto, há situações nas quais as aspas evitam ambiguidades.

Strings que parecem números

codigo: "00123"

Sem aspas, um parser poderá tratar o valor como número e perder os zeros à esquerda.

Para um mainframer, isso é crítico. 00123 pode ser um código, não o número cento e vinte e três.

Datas

data_processamento: "2026-07-18"

Colocar datas entre aspas impede que determinadas bibliotecas façam conversões automáticas inesperadas.

Valores com caracteres especiais

descricao: "Processamento: fechamento mensal"

Valores semelhantes a booleanos

estado: "on"
resposta: "no"

Senhas ou tokens

Mesmo usando aspas, não grave segredos diretamente no YAML:

senha: "MinhaSenhaSecreta"

Isso continua sendo texto visível.

Aspas não criptografam.

O correto é usar:

• gerenciadores de segredos;

• variáveis de ambiente;

• cofres de credenciais;

• mecanismos protegidos pelo pipeline;

• soluções corporativas integradas ao RACF ou à plataforma utilizada.

---

8. Textos com várias linhas

YAML possui recursos muito úteis para textos longos.

Preservando as quebras de linha com |

descricao: |
  Este processo executa o fechamento diário.
  Em caso de falha, consulte o runbook.
  Não reinicie sem verificar o checkpoint.

O | preserva as quebras de linha.

Dobrando as linhas com >

descricao: >
  Este processo executa o fechamento diário
  e deve ser acompanhado pela equipe
  responsável pela aplicação.

O > normalmente transforma as quebras em espaços, formando um parágrafo.

Isso pode ser útil para:

• descrições;

• comandos;

• mensagens;

• procedimentos operacionais;

• instruções de deploy.

---

9. Laboratório no Windows

Vamos montar um ambiente prático.

Precisaremos de:

• Windows 10 ou Windows 11;

• Visual Studio Code;

• extensão YAML;

• Python;

• biblioteca PyYAML;

• Prompt de Comando ou PowerShell.

A documentação oficial do Python informa que o gerenciador de instalação para Windows pode ser obtido pela Microsoft Store ou pelos canais oficiais do Python.

A extensão YAML da Red Hat para Visual Studio Code oferece recursos como validação, detecção de erros, conclusão automática, visão estrutural do documento e suporte a esquemas.

Passo 1 — Criar a pasta do projeto

Abra o Prompt de Comando:

mkdir C:\yaml-mainframe
cd C:\yaml-mainframe

Essa será nossa USS local — uma pequena base de operações no Windows.

Passo 2 — Verificar o Python

Execute:

python --version

Em instalações mais novas do Windows, também poderá funcionar:

py --version

Depois, confirme o gerenciador de pacotes:

py -m pip --version

Passo 3 — Criar um ambiente virtual

No diretório do projeto:

py -m venv .venv

Ative o ambiente no Prompt de Comando:

.venv\Scripts\activate

No PowerShell:

.\.venv\Scripts\Activate.ps1

Quando o ambiente estiver ativo, o terminal normalmente exibirá algo semelhante a:

(.venv) C:\yaml-mainframe>

O ambiente virtual isola as dependências do projeto. Isso evita instalar bibliotecas globalmente sem necessidade.

Passo 4 — Instalar o PyYAML

python -m pip install pyyaml

PyYAML é uma biblioteca para ler e gerar YAML usando Python, e sua instalação pode ser realizada por meio do pip.

Passo 5 — Abrir o projeto no Visual Studio Code

code .

Caso o comando code não esteja disponível, abra o VS Code manualmente e selecione:

Arquivo → Abrir Pasta → C:\yaml-mainframe

Passo 6 — Instalar a extensão YAML

No VS Code:

1. abra a área de extensões;

2. pesquise por YAML;

3. selecione a extensão publicada pela Red Hat;

4. clique em instalar.

Agora teremos realce de sintaxe e auxílio na identificação de erros.

---

10. Nosso projeto: inventário de aplicações mainframe

Crie o arquivo:

inventario-mainframe.yaml

Digite:

---
empresa: Bellacosa Galactic Bank
ambiente: homologacao
responsavel: equipe-mainframe

zos:
  sistema: ZOS1
  versao: "3.1"
  sysplex: BELLAPLEX
  lpar: ZHML01

subsistemas:
  cics:
    ativo: true
    regioes:
      - nome: CICSHML1
        tipo: AOR
        porta: 30101

      - nome: CICSHML2
        tipo: TOR
        porta: 30102

  db2:
    ativo: true
    subsistema: DB2H
    versao: "13"
    databases:
      - CLIENTES
      - CONTAS
      - PAGAMENTOS

aplicacoes:
  - nome: CADASTRO-CLIENTES
    codigo: "APL001"
    tipo: online
    linguagem: COBOL
    transacao_cics: CCLI
    programa_principal: PGMCIC01
    bibliotecas:
      fonte: USER01.COBOL
      copybook: USER01.COPYLIB
      carga: USER01.LOAD
    dependencias:
      - Db2
      - CICS
      - VSAM
    compilacao:
      obrigatoria: true
      compilador: Enterprise COBOL
      opcoes:
        - RENT
        - SSRANGE
        - TEST

  - nome: FECHAMENTO-DIARIO
    codigo: "APL002"
    tipo: batch
    linguagem: COBOL
    programa_principal: PGMFEC01
    jcl: JOBFEC01
    bibliotecas:
      fonte: USER01.BATCH.COBOL
      copybook: USER01.COPYLIB
      carga: USER01.BATCH.LOAD
    dependencias:
      - Db2
      - DFSORT
    janela:
      inicio: "22:00"
      termino: "23:30"
    compilacao:
      obrigatoria: false
      compilador: Enterprise COBOL
      opcoes:
        - RENT
        - OPTFILE

politicas:
  permitir_deploy_manual: false
  exigir_aprovacao: true
  reter_backups: 10

mensagem_operacional: |
  Antes de executar qualquer deploy:
  1. verificar o resultado da compilação;
  2. conferir os testes automatizados;
  3. validar o plano de retorno;
  4. consultar o responsável pela mudança.

easter_egg:
  nave: USS Enterprise
  computador: LCARS-Z
  mensagem: "A lógica é apenas o começo da sabedoria."
...

Agora vamos entender o documento.

---

11. Explicando cada parte

Marcador inicial

---

Os três hífens indicam o início de um documento YAML.

Não são sempre obrigatórios, mas tornam o arquivo mais explícito, especialmente quando existe mais de um documento no mesmo fluxo.

Informações gerais

empresa: Bellacosa Galactic Bank
ambiente: homologacao
responsavel: equipe-mainframe

São propriedades simples no nível raiz.

Estrutura do z/OS

zos:
  sistema: ZOS1
  versao: "3.1"

zos é um mapa.

A versão foi colocada entre aspas para preservar seu significado como identificador textual, não como número para cálculos.

Subsistemas

subsistemas:
  cics:
  db2:

Temos um mapa chamado subsistemas, contendo outros mapas.

Regiões CICS

regioes:
  - nome: CICSHML1
    tipo: AOR

regioes é uma lista.

Cada item possui:

• nome;

• tipo;

• porta.

Aplicações

aplicacoes:
  - nome: CADASTRO-CLIENTES

aplicacoes é uma lista de objetos complexos.

Cada aplicação contém propriedades próprias.

Bibliotecas

bibliotecas:
  fonte: USER01.COBOL
  copybook: USER01.COPYLIB
  carga: USER01.LOAD

Aqui usamos um mapa porque cada biblioteca possui uma função diferente.

Dependências

dependencias:
  - Db2
  - CICS
  - VSAM

É uma lista simples.

Opções de compilação

opcoes:
  - RENT
  - SSRANGE
  - TEST

Outro exemplo de lista.

Não estamos executando o compilador. Estamos documentando ou parametrizando quais opções uma automação deverá usar.

Mensagem operacional

mensagem_operacional: |

O símbolo | preserva as linhas, criando um pequeno runbook dentro do arquivo.

Final do documento

...

Os três pontos podem indicar o encerramento explícito do documento.

Assim como ---, são opcionais em muitos casos.

---

12. Criando o programa Python que lerá o YAML

Crie o arquivo:

ler_inventario.py

Digite:

from pathlib import Path
import sys

import yaml


ARQUIVO_YAML = Path("inventario-mainframe.yaml")


def carregar_yaml(caminho: Path) -> dict:
    """Carrega um arquivo YAML com tratamento básico de erros."""

    if not caminho.exists():
        raise FileNotFoundError(
            f"O arquivo {caminho} não foi encontrado."
        )

    with caminho.open("r", encoding="utf-8") as arquivo:
        dados = yaml.safe_load(arquivo)

    if not isinstance(dados, dict):
        raise ValueError(
            "O documento YAML deve possuir um mapa no nível principal."
        )

    return dados


def validar_inventario(dados: dict) -> list[str]:
    """Verifica a presença de campos obrigatórios."""

    erros = []

    campos_obrigatorios = [
        "empresa",
        "ambiente",
        "zos",
        "aplicacoes",
    ]

    for campo in campos_obrigatorios:
        if campo not in dados:
            erros.append(f"Campo obrigatório ausente: {campo}")

    aplicacoes = dados.get("aplicacoes", [])

    if not isinstance(aplicacoes, list):
        erros.append("O campo 'aplicacoes' deve ser uma lista.")
        return erros

    for indice, aplicacao in enumerate(aplicacoes, start=1):
        if not isinstance(aplicacao, dict):
            erros.append(
                f"A aplicação {indice} deve ser representada por um mapa."
            )
            continue

        for campo in ["nome", "codigo", "tipo", "linguagem"]:
            if campo not in aplicacao:
                erros.append(
                    f"Aplicação {indice}: campo '{campo}' ausente."
                )

    return erros


def exibir_relatorio(dados: dict) -> None:
    """Apresenta um resumo legível do inventário."""

    print("=" * 70)
    print("INVENTÁRIO GALÁCTICO DE APLICAÇÕES MAINFRAME")
    print("=" * 70)

    print(f"Empresa........: {dados['empresa']}")
    print(f"Ambiente.......: {dados['ambiente']}")
    print(f"Sistema z/OS...: {dados['zos']['sistema']}")
    print(f"Sysplex........: {dados['zos']['sysplex']}")
    print(f"LPAR...........: {dados['zos']['lpar']}")
    print()

    aplicacoes = dados["aplicacoes"]

    print(f"Aplicações encontradas: {len(aplicacoes)}")
    print("-" * 70)

    for aplicacao in aplicacoes:
        print(f"Nome...........: {aplicacao['nome']}")
        print(f"Código.........: {aplicacao['codigo']}")
        print(f"Tipo...........: {aplicacao['tipo']}")
        print(f"Linguagem......: {aplicacao['linguagem']}")
        print(f"Programa.......: {aplicacao['programa_principal']}")

        dependencias = aplicacao.get("dependencias", [])
        print(f"Dependências...: {', '.join(dependencias)}")

        opcoes = aplicacao.get("compilacao", {}).get("opcoes", [])
        print(f"Opções COBOL...: {', '.join(opcoes)}")
        print("-" * 70)


def main() -> int:
    try:
        dados = carregar_yaml(ARQUIVO_YAML)

        erros = validar_inventario(dados)

        if erros:
            print("O inventário possui inconsistências:")

            for erro in erros:
                print(f"- {erro}")

            return 8

        exibir_relatorio(dados)
        return 0

    except yaml.YAMLError as erro:
        print(f"Erro de sintaxe YAML: {erro}")
        return 12

    except (FileNotFoundError, ValueError, KeyError) as erro:
        print(f"Erro ao processar inventário: {erro}")
        return 16


if __name__ == "__main__":
    sys.exit(main())

---

13. Por que usamos safe_load?

No código temos:

dados = yaml.safe_load(arquivo)

Essa escolha é muito importante.

Evite usar indiscriminadamente:

yaml.load(arquivo)

Alguns carregadores YAML podem interpretar tags capazes de criar objetos específicos da linguagem ou executar comportamentos indesejados.

Quando o arquivo vem de origem externa ou não confiável, o risco aumenta.

safe_load limita o carregamento a tipos básicos e seguros, como:

• mapas;

• listas;

• strings;

• números;

• booleanos;

• valores nulos.

É o equivalente a aplicar o princípio de menor privilégio:

Não entregue autoridade de sistema a um arquivo de configuração apenas porque sua extensão termina em .yaml.

---

14. Executando o laboratório

No terminal, com o ambiente virtual ativo:

python ler_inventario.py

O resultado deverá ser semelhante a:

======================================================================
INVENTÁRIO GALÁCTICO DE APLICAÇÕES MAINFRAME
======================================================================
Empresa........: Bellacosa Galactic Bank
Ambiente.......: homologacao
Sistema z/OS...: ZOS1
Sysplex........: BELLAPLEX
LPAR...........: ZHML01

Aplicações encontradas: 2
----------------------------------------------------------------------
Nome...........: CADASTRO-CLIENTES
Código.........: APL001
Tipo...........: online
Linguagem......: COBOL
Programa.......: PGMCIC01
Dependências...: Db2, CICS, VSAM
Opções COBOL...: RENT, SSRANGE, TEST
----------------------------------------------------------------------
Nome...........: FECHAMENTO-DIARIO
Código.........: APL002
Tipo...........: batch
Linguagem......: COBOL
Programa.......: PGMFEC01
Dependências...: Db2, DFSORT
Opções COBOL...: RENT, OPTFILE
----------------------------------------------------------------------

Parabéns.

Você acabou de:

1. criar um documento YAML;

2. representar um ambiente mainframe;

3. modelar aplicações batch e online;

4. descrever bibliotecas e dependências;

5. ler o documento com Python;

6. validar campos obrigatórios;

7. transformar dados declarativos em um relatório.

Isso já é a base de muitas automações reais.

---

15. Provocando um erro de propósito

Todo bom laboratório precisa de um Kobayashi Maru.

Altere:

aplicacoes:
  - nome: CADASTRO-CLIENTES

Para:

aplicacoes:
 - nome: CADASTRO-CLIENTES
     codigo: "APL001"

Execute novamente:

python ler_inventario.py

O parser deverá informar um erro de sintaxe ou estrutura.

Agora teste um erro mais perigoso.

Remova o campo codigo de uma aplicação, mas mantenha a sintaxe válida:

- nome: CADASTRO-CLIENTES
  tipo: online
  linguagem: COBOL

Nesse caso, o parser consegue ler o YAML, porém nossa validação retorna algo semelhante a:

Aplicação 1: campo 'codigo' ausente.

Isso ensina uma diferença essencial:

Validação sintática

Pergunta:

O documento está escrito de maneira compreensível para o parser?

Validação semântica

Pergunta:

O documento contém os dados corretos para nossa aplicação?

Um YAML pode ser sintaticamente perfeito e operacionalmente inútil.

Da mesma forma, um JCL pode passar por determinadas validações e ainda apontar para o dataset errado.

---

16. YAML Schema: o copybook do YAML

À medida que os documentos crescem, validar tudo manualmente torna-se difícil.

É aí que entram os esquemas.

Um schema pode definir:

• quais campos são obrigatórios;

• quais tipos são permitidos;

• quais valores são aceitos;

• qual estrutura deve ser seguida;

• quais propriedades são proibidas;

• quais listas podem ficar vazias.

Para o mainframer, um schema funciona conceitualmente como uma combinação de:

• copybook;

• layout de arquivo;

• contrato de interface;

• regras de validação.

Sem schema:

porta: banana

O YAML é válido, pois banana é uma string.

Mas, se o sistema espera uma porta TCP numérica, o conteúdo está errado.

Com um schema, o editor poderá avisar:

A propriedade porta deve ser um número inteiro.

Esse recurso é especialmente importante em:

• pipelines;

• Kubernetes;

• APIs;

• Ansible;

• grandes inventários;

• configurações corporativas.

---

17. Anchors e aliases: o COPY do YAML

YAML possui anchors e aliases, que permitem reutilizar blocos.

Exemplo:

configuracao_padrao: &padrao_cobol
  compilador: Enterprise COBOL
  opcoes:
    - RENT
    - SSRANGE
    - TEST

aplicacoes:
  - nome: CLIENTES
    compilacao: *padrao_cobol

  - nome: CONTAS
    compilacao: *padrao_cobol

O símbolo:

&padrao_cobol

cria uma âncora.

O símbolo:

*padrao_cobol

faz referência a ela.

É tentador pensar nisso como um COPY do COBOL.

Entretanto, tenha cuidado.

Anchors podem reduzir repetição, mas também tornar o documento mais difícil de entender. Algumas ferramentas possuem suporte parcial ou adotam comportamentos específicos.

Use anchors quando:

• houver repetição significativa;

• a equipe conhecer o recurso;

• a ferramenta suportá-lo corretamente;

• o ganho de manutenção superar a perda de clareza.

Não transforme seu YAML em um labirinto Klingon.

---

18. Boas práticas para mainframers

Use dois espaços por nível

aplicacao:
  nome: CLIENTES

A consistência vale mais que a preferência individual.

Nunca use TAB

Configure o editor para substituir TAB por espaços.

Prefira nomes claros

Evite:

apl:
  nm: CLI
  tp: O

Prefira:

aplicacao:
  nome: CLIENTES
  tipo: online

Use uma convenção de nomes

Escolha um padrão:

programa_principal

ou:

programa-principal

Evite misturar:

programa_principal:
programa-principal:
ProgramaPrincipal:

Coloque códigos entre aspas

codigo: "000123"

Coloque horários entre aspas

inicio: "08:00"

Coloque datas entre aspas quando desejar tratá-las como texto

data: "2026-07-18"

Não grave segredos

Nunca faça:

usuario: ADMIN
senha: SENHA123

Valide antes do commit

O fluxo ideal é:

editar → validar → revisar → testar → commit → pipeline

Mantenha arquivos pequenos

Um YAML com milhares de linhas torna-se difícil de revisar.

Considere separar por:

• ambiente;

• aplicação;

• domínio;

• equipe;

• finalidade.

Documente a intenção

# Ativada somente em homologação para testes de integração
simular_falha_db2: true

O comentário explica o motivo, não apenas repete o nome do campo.

Use controle de versão

Arquivos YAML devem ser armazenados no Git sempre que fizer sentido.

Assim você consegue saber:

• quem mudou;

• o que mudou;

• quando mudou;

• por que mudou;

• qual versão estava funcionando.

---

19. Cuidados que evitam desastres

Um espaço pode mudar a hierarquia

Revise sempre o diff antes do commit.

Valores podem ser interpretados automaticamente

Quando o tipo for importante, use aspas ou schemas.

YAML válido não significa configuração válida

Teste com a ferramenta que realmente consumirá o arquivo.

Ambientes não devem compartilhar segredos

Produção, homologação e desenvolvimento precisam de separação adequada.

Copiar da internet exige revisão

Um exemplo encontrado em um fórum pode:

• usar outra versão;

• depender de outra ferramenta;

• conter parâmetros obsoletos;

• assumir permissões inexistentes;

• expor credenciais;

• executar ações destrutivas.

IA também pode errar a indentação

Um YAML gerado por inteligência artificial deve passar por:

• revisão humana;

• lint;

• schema;

• teste em ambiente controlado;

• análise de segurança.

Nunca envie um arquivo gerado automaticamente direto para produção.

Cuidado com comandos multilinha

Um comando embutido em YAML pode parecer correto, mas ser interpretado de forma diferente pelo shell.

Cuidado com duplicidade de chaves

Observe:

ambiente: teste
ambiente: producao

Dependendo da biblioteca, o segundo valor pode sobrescrever o primeiro sem o aviso esperado.

Para uma mudança de produção, isso pode ser desastroso.

Use validadores capazes de detectar chaves duplicadas.

---

20. Como evoluir depois deste laboratório

Depois de dominar este exemplo, o Programador COBOL Padawan pode avançar por uma trilha segura.

Nível 1 — Leitura

Aprenda a identificar:

• mapas;

• listas;

• strings;

• números;

• booleanos;

• valores nulos;

• comentários;

• hierarquia.

Nível 2 — Validação

Use:

• extensão YAML no editor;

• schemas;

• linters;

• scripts Python;

• testes automatizados.

Nível 3 — Automação local

Crie scripts que leiam YAML para:

• gerar JCL;

• produzir relatórios;

• montar parâmetros;

• validar inventários;

• criar documentação;

• comparar ambientes.

Nível 4 — Git

Armazene arquivos em repositórios e pratique:

• branch;

• commit;

• pull request;

• diff;

• revisão de código.

Nível 5 — CI/CD

Use YAML para criar pipelines de:

• compilação;

• testes;

• análise estática;

• empacotamento;

• deploy;

• rollback.

Nível 6 — Ansible para z/OS

Aprenda playbooks que possam:

• criar datasets;

• copiar arquivos;

• submeter jobs;

• consultar resultados;

• executar comandos;

• automatizar tarefas administrativas.

Nível 7 — Infraestrutura declarativa

Explore ferramentas que transformam YAML em estado operacional.

Aqui ocorre uma mudança importante de mentalidade.

Em vez de dizer apenas:

Execute este comando.

Você passa a declarar:

Quero que o ambiente permaneça neste estado.

---

21. Comparando YAML, JCL, JSON e XML

YAML

Excelente para arquivos legíveis e configurações hierárquicas.

programa:
  nome: PGMCAD01
  tipo: batch

JSON

Muito usado em APIs e comunicação entre aplicações.

{
  "programa": {
    "nome": "PGMCAD01",
    "tipo": "batch"
  }
}

A estrutura de dados é semelhante, mas JSON exige mais sinais de pontuação.

XML

Possui tags de abertura e fechamento.

<programa>
  <nome>PGMCAD01</nome>
  <tipo>batch</tipo>
</programa>

É mais verboso, porém muito utilizado em integrações corporativas e sistemas legados.

JCL

Descreve a execução de trabalhos no z/OS:

//STEP01 EXEC PGM=PGMCAD01
//STEPLIB DD DSN=USER01.LOAD,DISP=SHR

YAML não substitui automaticamente o JCL.

Uma automação poderá ler YAML e gerar ou submeter JCL, mas o JES continuará precisando compreender o trabalho no formato adequado.

A ponte pode ser:

YAML
  ↓
Pipeline ou script
  ↓
JCL
  ↓
JES2
  ↓
Programa COBOL

---

22. Curiosidades para a tripulação

YAML nasceu para ser legível

Seu desenho privilegia estruturas que humanos possam editar com relativa facilidade.

JSON pode ser visto como um subconjunto estrutural do YAML 1.2

A compatibilidade com o modelo de dados do JSON foi um dos objetivos importantes da linha YAML 1.2.

A extensão preferida é .yaml

Também é comum encontrar:

.yml

Porém, .yaml é mais explícita.

YAML não é automaticamente simples

Documentos pequenos são agradáveis.

Documentos gigantes, com anchors, merges, múltiplos documentos e regras implícitas, podem tornar-se difíceis de manter.

Indentação é estrutura, não decoração

No COBOL, uma indentação visual ruim pode dificultar a leitura.

No YAML, uma indentação errada pode mudar o significado.

A melhor configuração é aquela que pode ser validada

Quanto mais crítica for a automação, menos você deve depender apenas da leitura humana.

---

23. Easter egg: o arquivo de missão da Enterprise

Crie:

missao-enterprise.yaml

---
nave:
  nome: USS Enterprise
  registro: NCC-1701
  capitao: James T. Kirk

tripulacao:
  - nome: Spock
    funcao: ciencia
    linguagem_preferida: YAML

  - nome: Montgomery Scott
    funcao: engenharia
    linguagem_preferida: JCL

  - nome: Nyota Uhura
    funcao: comunicacoes
    linguagem_preferida: JSON

missao:
  destino: Sistema IBM Z
  objetivo: modernizar_sem_destruir
  diretriz_principal: |
    Integrar o novo ao legado.
    Preservar aquilo que funciona.
    Automatizar aquilo que se repete.
    Documentar aquilo que ninguém mais compreende.

alertas:
  tab_encontrado: vermelho
  segredo_no_repositorio: vermelho
  deploy_sem_teste: vermelho
  yaml_validado: verde

mensagem_final: >
  Vida longa ao COBOL,
  prosperidade ao mainframe
  e atenção absoluta à indentação.
...

Observe o detalhe:

objetivo: modernizar_sem_destruir

Essa talvez seja a missão mais importante de toda modernização mainframe.

Modernizar não significa jogar fora décadas de regras de negócio.

Significa:

• entender;

• proteger;

• documentar;

• integrar;

• automatizar;

• evoluir.

---

24. Conclusão: o YAML como nova ponte do mainframe

YAML não substituirá o COBOL.

Não substituirá o JCL.

Não substituirá o CICS, o Db2, o IMS ou o z/OS.

Sua função é diferente.

YAML permite descrever configurações e intenções de uma forma que ferramentas modernas conseguem interpretar.

Para o mainframer, ele representa uma nova camada de comunicação entre:

• o código COBOL;

• os pipelines;

• os repositórios Git;

• os processos de build;

• as ferramentas de automação;

• os ambientes distribuídos;

• a infraestrutura;

• as equipes modernas de desenvolvimento.

O veterano que conhece COBOL possui uma vantagem enorme.

Ele já entende:

• estruturas hierárquicas;

• contratos de dados;

• processamento previsível;

• validação;

• disciplina operacional;

• ambientes controlados;

• importância da compatibilidade;

• consequências de um erro em produção.

Aprender YAML não é começar do zero.

É traduzir conhecimentos antigos para uma nova interface.

O programador que entende um copybook consegue compreender um schema.

Quem entende um SYSIN consegue compreender um arquivo declarativo.

Quem entende JCL consegue compreender pipelines.

Quem conhece PROC e parâmetros consegue compreender templates.

Quem respeita produção aprende rapidamente a respeitar indentação.

A verdadeira transformação não ocorre quando o mainframer abandona sua experiência.

Ela ocorre quando usa essa experiência para dominar novas ferramentas.

Portanto, abra o editor, crie seus primeiros arquivos, provoque erros em ambiente controlado, valide cada estrutura e coloque o YAML para trabalhar ao lado do COBOL.

Porque, no fim das contas, seja dentro de uma LPAR, de um container ou da USS Enterprise, uma regra continua universal:

Configuração sem validação é apenas um futuro incidente esperando sua janela de produção.

Vida longa ao COBOL.

Prosperidade ao IBM Z.

E que nenhum TAB clandestino atravesse os escudos da sua indentação.

 

Bellacosa Mainframe e a documentação de software

☕ Um Café no Bellacosa Mainframe

📚 MYNE E A BIBLIOTECA PERDIDA DO MAINFRAME — QUANDO O COBOL DESCOBRIU QUE CÓDIGO SEM DOCUMENTAÇÃO TAMBÉM PODE VIRAR UM LIVRO ESQUECIDO

Documentação, COBOL, auditoria, Configuration Management, Git, runbooks, dívida documental, conhecimento institucional, IA generativa — e o dia em que Myne descobriu que o maior risco do sistema não estava no programa, mas na cabeça do único programador que sabia como ele funcionava.

---

🎬 PRÓLOGO — MYNE ENCONTROU UM PROGRAMA COBOL

Myne abriu os olhos.

Não estava em Ehrenfest.

Não havia templo.

Não havia Ferdinand.

Não havia sequer uma biblioteca.

Diante dela existia uma tela preta com letras verdes.

READY

DSN SYSTEM(DB2P)

IKJ56700A ENTER USERID -

— Onde estão os livros?

Um velho programador apontou para milhares de datasets.

HLQ.PROD.COBOL
HLQ.PROD.COPYLIB
HLQ.PROD.JCL
HLQ.PROD.PROCLIB
HLQ.PROD.PARMLIB

Myne arregalou os olhos.

— Então... isso tudo é conhecimento?

— Mais ou menos.

— Onde está a documentação?

Silêncio.

O programador olhou para o teto.

Outro fingiu que estava analisando um dump.

Um terceiro tomou café.

Finalmente alguém respondeu:

— Pergunta para o Carlos.

Myne imediatamente percebeu que havia encontrado um problema muito mais grave do que a falta de livros.

A empresa possuía milhares de programas.

Mas parte importante do conhecimento necessário para compreendê-los estava armazenada em um dispositivo extremamente sofisticado, porém perigosamente volátil:

a memória dos funcionários.

Bem-vindo, jovem programador COBOL, à dungeon da documentação.

---

📜 CAPÍTULO 1 — CÓDIGO NÃO É DOCUMENTAÇÃO

Existe uma frase muito repetida no desenvolvimento:

“O código é a documentação.”

Ela contém alguma verdade, mas também pode esconder uma armadilha.

Veja:

       IF WS-TIPO-CLIENTE = 'E'
           PERFORM 8200-CALCULO-ESPECIAL
       END-IF.

Mesmo um iniciante consegue perceber o comportamento básico.

Se WS-TIPO-CLIENTE for igual a E, o programa executa 8200-CALCULO-ESPECIAL.

Ótimo.

Mas agora Myne começa a fazer perguntas.

— O que significa E?

— Especial.

— O que é um cliente especial?

— Não sei.

— Quem decidiu isso?

— Não sei.

— Por que ele recebe cálculo diferente?

— Também não sei.

— Desde quando?

— Talvez 2004.

— Posso remover?

— NÃO!

E encontramos a diferença entre código e conhecimento.

O código descreve muito bem aquilo que o computador precisa executar.

Mas nem sempre preserva:

• por que determinada decisão foi tomada;

• qual requisito originou a regra;

• quem solicitou a alteração;

• quais impactos foram considerados;

• quais sistemas dependem dela;

• quais procedimentos operacionais existem;

• como recuperar o sistema quando algo dá errado.

Imagine encontrar:

      * ALTERADO JOAO 14/06/2004

Excelente.

Descobrimos que João esteve ali.

Infelizmente, João não deixou pistas sobre aquilo que estava pensando.

Myne suspira.

Um livro que diz apenas:

“Capítulo alterado por João.”

não preserva conhecimento suficiente para reconstruir sua história.

---

🧠 CAPÍTULO 2 — A EMPRESA POSSUI UMA MEMÓRIA

Uma organização também possui memória.

Só que ela não fica em um único lugar.

Pode estar espalhada por:

Código-fonte
     │
     ├── COBOL
     ├── JCL
     ├── COPYBOOKS
     ├── procedimentos
     ├── tickets
     ├── diagramas
     ├── e-mails
     ├── Wikis
     ├── runbooks
     ├── atas
     ├── manuais
     └── pessoas

O último elemento merece atenção especial.

Imagine:

CONHECIMENTO DO SISTEMA XPTO

20% documentação
30% código
50% Carlos

Temos um problema.

Carlos pode:

• sair da empresa;

• mudar de departamento;

• entrar de férias;

• esquecer detalhes;

• aposentar-se;

• simplesmente não estar disponível durante um incidente.

Isso transforma Carlos em algo parecido com um Single Point of Failure humano.

Existe inclusive uma expressão informal usada em engenharia de software: bus factor.

Ela procura representar quantas pessoas poderiam ficar indisponíveis antes que um projeto perdesse conhecimento crítico.

Se a resposta for:

uma,

temos enorme concentração de conhecimento.

Myne ficaria horrorizada.

Para alguém que passou a vida tentando preservar livros, colocar conhecimento crítico exclusivamente na memória humana seria equivalente a possuir apenas um exemplar de um livro importantíssimo e guardá-lo ao lado de uma lareira.

---

⚔️ CAPÍTULO 3 — POR QUE PROGRAMADORES NÃO GOSTAM DE DOCUMENTAR?

Durante décadas, gestores perguntaram:

Como fazer os programadores documentarem?

É uma pergunta compreensível.

Mas pode ser a pergunta errada.

É fácil responder:

— Programador não gosta de escrever.

Alguns realmente não gostam.

Outros têm dificuldade para transformar raciocínio técnico em texto compreensível.

Mas existe um problema organizacional muito mais interessante.

Imagine dois programadores.

Programador A

Codificação ............ 8 horas
Testes ................. 3 horas
Documentação ........... 2 horas
-------------------------------
Total .................. 13 horas

Programador B

Codificação ............ 8 horas
Testes ................. 2 horas
Documentação ........... 0 horas
-------------------------------
Total .................. 10 horas

Se a empresa medir produtividade apenas pela velocidade da entrega, quem parece melhor?

B.

Portanto, não documentar pode ser perfeitamente racional dentro de um sistema de incentivos mal construído.

A empresa publica:

“Documentação é fundamental.”

Mas o projeto comunica:

PRAZO > DOCUMENTAÇÃO

E o funcionário aprende rapidamente qual regra realmente vale.

Myne percebe algo importante:

cultura organizacional não é aquilo que está escrito no manual. É aquilo que a organização recompensa, tolera e pune.

---

🏰 CAPÍTULO 4 — DOCUMENTAÇÃO NÃO DEVERIA SER UMA TAREFA POSTERIOR

Um projeto tradicional frequentemente funciona assim:

REQUISITO
    ↓
ANÁLISE
    ↓
DESENVOLVIMENTO
    ↓
TESTE
    ↓
PRODUÇÃO
    ↓
"Esquecemos da documentação."

Nesse modelo, documentação virou a última obrigação antes da libertação do programador.

Resultado?

Ele está cansado.

O prazo terminou.

Outro projeto já começou.

O gerente quer implantação.

E alguém pergunta:

— Você pode escrever o manual?

Nasce então o clássico:

MANUAL_SISTEMA_FINAL.DOC

Seguido, meses depois, por:

MANUAL_SISTEMA_FINAL2.DOC
MANUAL_SISTEMA_NOVO.DOC
MANUAL_SISTEMA_NOVO_FINAL.DOC
MANUAL_SISTEMA_NOVO_FINAL_OK.DOC

Isso não é versionamento.

É arqueologia digital.

A solução conceitual é colocar documentação dentro do ciclo de desenvolvimento:

REQUISITO
    ↓
DESIGN
    ↓
CÓDIGO
    +
DOCUMENTAÇÃO
    ↓
TESTE
    +
TESTE DA DOCUMENTAÇÃO
    ↓
REVIEW
    ↓
DEPLOY

Agora surge uma regra poderosa:

mudança no sistema pode significar mudança na documentação.

Não necessariamente toda alteração muda todo documento.

Mas toda alteração deveria provocar a pergunta:

Quais informações precisam ser atualizadas por causa desta mudança?

---

🔗 CAPÍTULO 5 — UMA ALTERAÇÃO COBOL NUNCA ESTÁ SOZINHA

O iniciante frequentemente imagina:

PROGRAMA COBOL

Mas sistemas corporativos são ecossistemas.

Uma alteração pode atingir:

REQUISITO
   │
   ├── COBOL
   ├── COPYBOOK
   ├── JCL
   ├── PROC
   ├── VSAM
   ├── Db2
   ├── CICS
   ├── MQ
   ├── API
   ├── batch
   ├── procedimento operacional
   ├── troubleshooting
   └── manual do usuário

Imagine aumentar um campo:

05 CLIENTE-ID PIC 9(06).

para:

05 CLIENTE-ID PIC 9(08).

Parece simples.

Mas Myne pergunta:

— O copybook compartilhado mudou?

— Sim.

— Arquivos VSAM?

— Talvez.

— Layout de interface?

— Sim.

— Programa consumidor?

— Também.

— Documentação?

Silêncio novamente.

Essa é a essência da análise de impacto.

Documentação não está fora do sistema.

Ela faz parte do conjunto de artefatos que descrevem o sistema.

---

🧙 CAPÍTULO 6 — MYNE DESCOBRE CONFIGURATION MANAGEMENT

Chegamos a um conceito importante para quem está começando no mainframe:

Configuration Management.

Simplificando bastante, Configuration Management procura responder perguntas como:

O que existe?
Qual versão existe?
Qual versão está em produção?
Quem alterou?
Quando alterou?
Por que alterou?
O que depende disso?
Qual era a configuração anterior?

Você provavelmente já percebeu que isso não interessa somente ao código.

Imagine:

RUNBOOK-PAGAMENTOS

Versão: 4.7
Sistema: PAY001
Owner: Payments Operations
Aprovador: Production Control
Última revisão: 23/09/2026
Próxima revisão: 23/03/2027
Change: CHG-98472
Status: APPROVED

Agora temos algo auditável.

Podemos perguntar:

Qual procedimento estava válido em 14 de março?

E recuperar aquela versão.

Essa capacidade é essencial.

---

💀 CAPÍTULO 7 — ÀS 03:17, A DOCUMENTAÇÃO VIRA PRODUÇÃO

03:17.

Sim, jovem padawan.

Você encontrou o easter egg.

O telefone toca.

INCIDENTE CRÍTICO
SISTEMA DE PAGAMENTOS

O operador consulta o procedimento.

1. Localizar JOB PAYR001.
2. Cancelar execução.
3. Executar PAYREC01.
4. Verificar mensagem PAY003I.

Ele está prestes a executar o passo 3 quando alguém grita:

— NÃO EXECUTA!

— Por quê?

— PAYREC01 foi aposentado.

— Quando?

— Ano passado.

— O procedimento manda executar.

Silêncio.

A documentação está oficialmente publicada.

Mas descreve um sistema que já não existe.

Temos então duas verdades:

VERDADE EXECUTÁVEL
        ≠
VERDADE DOCUMENTADA

Esse fenômeno poderia ser chamado de documentation drift ou deriva documental.

E aqui aparece uma conclusão contraintuitiva:

documentação errada pode ser pior que documentação inexistente.

Se não houver documentação, o operador sabe que precisa investigar.

Quando existe um procedimento aparentemente oficial, ele pode confiar nele.

---

🧪 CAPÍTULO 8 — DOCUMENTAÇÃO TAMBÉM PRECISA SER TESTADA

Essa ideia é extraordinariamente importante.

Considere:

1. Entre no SDSF.
2. Localize o job.
3. Execute comando X.
4. Confirme mensagem Y.
5. Reinicie componente Z.

Um especialista lê e afirma:

— Perfeito.

Mas entregue isso a alguém que nunca executou o procedimento.

Ele pergunta:

— Em qual painel?

— Como localizo o job?

— Qual comando?

— Onde aparece Y?

— E se Y não aparecer?

Descobrimos cinco buracos em trinta segundos.

Portanto, documentação operacional pode possuir algo parecido com teste funcional.

Uma pessoa representativa do público-alvo tenta realizar a tarefa utilizando somente as instruções.

Isso revela:

• passos ausentes;

• pressupostos ocultos;

• terminologia inadequada;

• ambiguidades;

• comandos errados;

• dependências não documentadas.

Myne aprovaria.

Não basta imprimir o livro.

Precisamos verificar se o leitor consegue utilizá-lo.

---

📚 CAPÍTULO 9 — MAIS DOCUMENTAÇÃO NÃO SIGNIFICA MELHOR DOCUMENTAÇÃO

Existe outra pergunta antiga:

Quanto devemos documentar?

Resposta errada:

Tudo.

Outra resposta errada:

O mínimo possível.

O objetivo é:

DOCUMENTAÇÃO NECESSÁRIA
        +
CORRETA
        +
ATUAL
        +
ENCONTRÁVEL
        +
COMPREENSÍVEL
        +
ADEQUADA À TAREFA

Um manual de 900 páginas pode ser praticamente inútil durante um incidente.

O operador talvez precise de duas páginas.

Diferentes necessidades exigem diferentes documentos:

Necessidade	Informação
compreender arquitetura	Architecture Overview
desenvolver	Developer Guide
operar	Runbook
investigar falha	Troubleshooting Guide
integrar	Interface/API Specification
recuperar desastre	Disaster Recovery Procedure
utilizar aplicação	User Guide
modificar	Design/Change Documentation
aprender sistema	Onboarding Guide
auditar	evidências e histórico

A antiga ideia de colocar tudo no gigantesco Manual do Sistema frequentemente cria documentos impossíveis de consumir.

---

🗺️ CAPÍTULO 10 — DOCUMENTAÇÃO PRECISA SER ENCONTRÁVEL

Myne finalmente recebe uma boa notícia.

— Temos documentação!

— Onde?

— Share.

— Qual?

— Não lembro.

— Nome?

— Alguma coisa como PAY...

Depois de vinte minutos:

\\server\departamento\projetos\old\sistemas\pagamentos\
documentacao\backup\antigo\

Myne quase desmaia.

Informação que existe mas não pode ser encontrada possui valor operacional próximo de zero.

Portanto, governança documental envolve também:

• taxonomia;

• pesquisa;

• nomes consistentes;

• metadados;

• owners;

• classificação;

• links;

• relacionamentos;

• controle de versão.

Bibliotecas descobriram isso séculos atrás.

Não basta possuir livros.

Precisamos saber onde eles estão e como encontrá-los.

---

🏛️ CAPÍTULO 11 — CENTRALIZAR OU DESCENTRALIZAR?

O problema já existia décadas atrás.

Deveríamos possuir um departamento central de documentação?

Ou documentadores dentro das equipes?

Centralizado

          DOCUMENTAÇÃO
               │
     ┌─────────┼─────────┐
     ↓         ↓         ↓
 SISTEMA A  SISTEMA B  SISTEMA C

Excelente para:

• padrões;

• qualidade;

• independência;

• governança;

• consistência.

Mas pode ficar distante da tecnologia.

Descentralizado

TIME A → documentação A
TIME B → documentação B
TIME C → documentação C

Excelente proximidade.

Mas pode produzir três dialetos diferentes.

Uma solução interessante é o modelo federado:

          GOVERNANÇA CENTRAL
                 │
       padrões e ferramentas
                 │
       ┌─────────┼─────────┐
       ↓         ↓         ↓
     TIME A    TIME B    TIME C
       │         │         │
     OWNER     OWNER     OWNER

O centro define regras.

As equipes preservam conhecimento local.

---

👑 CAPÍTULO 12 — TODO DOCUMENTO PRECISA DE UM DONO

Uma regra simples evita enorme quantidade de caos:

todo documento relevante deve possuir owner.

Owner não significa necessariamente autor.

O owner responde pela validade.

Pense assim:

DOCUMENTO
   ↓
OWNER
   ↓
REVISÃO
   ↓
APROVAÇÃO
   ↓
PUBLICAÇÃO
   ↓
USO
   ↓
NOVA REVISÃO
   ↓
ARQUIVAMENTO

Documento sem proprietário tende a virar órfão.

E órfãos digitais envelhecem silenciosamente.

---

🧹 CAPÍTULO 13 — DOCUMENTO OBSOLETO PRECISA MORRER

Esse ponto é pouco discutido.

Criar documentação é importante.

Mas aposentar documentação também é.

Imagine encontrar:

RUNBOOK-PAY-2019
RUNBOOK-PAY-2021
RUNBOOK-PAY-NOVO
RUNBOOK-PAY-FINAL
RUNBOOK-PAY-ATUAL

Qual é válido?

Se ninguém souber, temos risco operacional.

Um processo maduro deveria permitir estados como:

DRAFT
REVIEW
APPROVED
PUBLISHED
SUPERSEDED
ARCHIVED

Assim sabemos que determinado documento existe historicamente, mas não deve mais orientar operações atuais.

Myne chamaria isso de diferença entre:

arquivo histórico e livro de uso corrente.

---

💳 CAPÍTULO 14 — DÍVIDA DOCUMENTAL

Programadores conhecem Technical Debt.

Mas existe outra dívida:

Documentation Debt.

Toda mudança não refletida na documentação cria um pequeno débito.

No começo ninguém percebe.

Mudança 1 → documento quase correto
Mudança 2 → pequeno erro
Mudança 3 → faltam dois procedimentos
Mudança 4 → diagrama incorreto
Mudança 5 → ninguém confia mais

Finalmente acontece algo curioso:

“Não consulte a Wiki porque está desatualizada.”

Pronto.

A organização perdeu confiança em seu próprio repositório de conhecimento.

Podemos imaginar:

Documentation Debt ↑

MTTR ↑
Onboarding ↑
Dependência de especialistas ↑
Retrabalho ↑
Risco operacional ↑
Risco de auditoria ↑

O custo economizado ontem reaparece com juros.

---

🔍 CAPÍTULO 15 — ENTRA O AUDITOR

Agora o auditor chega.

Um auditor fraco pergunta:

— Vocês possuem documentação?

A equipe mostra cinquenta PDFs.

Check.

Auditor satisfeito.

Myne não.

Um auditor melhor pergunta:

“Mostre uma alteração recente em produção.”

Escolhemos:

CHG-98472

Agora reconstruímos:

REQUISITO
    ↓
ANÁLISE
    ↓
CHANGE
    ↓
ALTERAÇÃO COBOL
    ↓
TESTE
    ↓
APROVAÇÃO
    ↓
DEPLOY
    ↓
DOCUMENTAÇÃO
    ↓
COMUNICAÇÃO

Depois fazemos o contrário.

Escolhemos um programa em produção:

PAYB0031

E perguntamos:

Qual versão?
Qual change colocou isso aqui?
Quem aprovou?
Quais testes existem?
Qual requisito originou?
Qual documentação foi atualizada?

Isso é rastreabilidade.

Não estamos procurando papel.

Estamos procurando evidência de controle.

---

⚔️ CAPÍTULO 16 — O AUDITOR PROCURA A EMPRESA REAL

Existe uma diferença fundamental entre:

PROCESSO DOCUMENTADO

e:

PROCESSO REAL

O manual diz:

Em incidentes críticos consultar RUNBOOK-PAY.

O auditor entrevista operadores.

— O que você faz quando PAY cai?

— Chamo o Zé.

— E o runbook?

— Ah... aquilo está velho.

Bingo.

Encontramos uma diferença entre governança formal e comportamento operacional.

A empresa pensa que possui:

INCIDENTE
   ↓
RUNBOOK
   ↓
RESOLUÇÃO

Na realidade possui:

INCIDENTE
   ↓
WhatsApp
   ↓
"CHAMA O ZÉ"

Zé virou middleware humano.

E não possui redundância.

---

🤖 CAPÍTULO 17 — MYNE CONHECE A INTELIGÊNCIA ARTIFICIAL

Então chega 2026.

Myne encontra uma máquina extraordinária.

Ela recebe:

• COBOL;

• JCL;

• copybooks;

• diagramas;

• tickets;

• commits;

• logs.

E produz explicações.

— Ela escreve livros?!

Quase.

IA generativa pode ajudar enormemente na documentação.

Por exemplo, pode transformar:

       EVALUATE WS-STATUS
          WHEN 'A'
             PERFORM 1000-ATIVO
          WHEN 'B'
             PERFORM 2000-BLOQUEADO
          WHEN OTHER
             PERFORM 9000-ERRO
       END-EVALUATE.

em uma explicação preliminar.

Pode ainda:

• resumir código;

• explicar campos;

• gerar diagramas preliminares;

• converter tickets em release notes;

• comparar versões;

• identificar documentação possivelmente afetada;

• criar perguntas para revisão;

• produzir rascunhos de runbooks.

Fantástico.

Mas existe uma armadilha gigantesca.

---

☠️ CAPÍTULO 18 — IA PODE DOCUMENTAR PERFEITAMENTE UMA COISA ERRADA

Imagine a IA afirmar:

“O campo E representa cliente empresarial.”

Texto bonito.

Gramática impecável.

Completamente errado.

Na verdade:

E = CLIENTE ESPECIAL

Esse é um novo tipo de risco.

Antigamente tínhamos documentação ruim obviamente ruim.

Agora podemos possuir documentação errada extremamente convincente.

Portanto:

IA
 ↓
RASCUNHO
 ↓
SME TÉCNICO
 ↓
USUÁRIO
 ↓
VALIDAÇÃO
 ↓
APROVAÇÃO
 ↓
PUBLICAÇÃO

Nunca:

IA
 ↓
PRODUÇÃO

A inteligência artificial reduz o custo de produção.

Ela não transfere responsabilidade pela verdade.

---

🧰 CAPÍTULO 19 — DOCUMENTATION AS CODE

Agora Myne encontra Git.

E quase pede Ferdinand em casamento novamente.

Porque finalmente os livros possuem histórico automático.

Podemos organizar:

docs/
├── architecture/
├── development/
├── operations/
├── troubleshooting/
├── interfaces/
└── security/

Uma alteração começa:

git checkout -b CHG-98472

O programador altera:

src/PAYB0031.cbl

e também:

docs/operations/payment-runbook.md

Então:

CODE
  +
DOC
  ↓
PULL REQUEST
  ↓
REVIEW
  ↓
PIPELINE
  ↓
RELEASE

Isso é poderoso porque aproxima documentação do mesmo fluxo utilizado pelo software.

Temos:

• versionamento;

• histórico;

• autoria;

• comparação;

• revisão;

• aprovação;

• automação.

Código e conhecimento começam a viajar juntos.

---

🧪 CAPÍTULO 20 — UM PASSO A PASSO PARA O PROGRAMADOR COBOL

Você recebeu uma alteração.

Não pense apenas:

“Qual linha COBOL vou mudar?”

Faça algo parecido com isto.

Passo 1 — descubra o motivo

Pergunte:

Qual problema estamos resolvendo?

Passo 2 — descubra o impacto

Liste:

COBOL?
COPYBOOK?
JCL?
Db2?
VSAM?
CICS?
MQ?
API?
batch?
usuário?
operação?

Passo 3 — localize documentação relacionada

Procure:

Architecture
Developer Guide
Runbook
Interface Specification
User Guide
Troubleshooting

Passo 4 — altere código e conhecimento juntos

Não espere três meses.

Passo 5 — teste ambos

O programa funciona?

A instrução também?

Passo 6 — peça revisão

Técnico revisa tecnologia.

Usuário revisa significado.

Operação revisa execução.

Passo 7 — preserve rastreabilidade

Relacione:

REQUISITO → CHANGE → CÓDIGO → TESTE → DOCUMENTAÇÃO

Passo 8 — retire informação obsoleta

Não deixe armadilhas históricas disponíveis como instrução atual.

---

🧙‍♀️ CAPÍTULO 21 — MYNE CRIA AS DEZ REGRAS DA BIBLIOTECA DO MAINFRAME

Depois de observar aquela organização, Myne escreve:

I. Código não substitui contexto.

II. Toda mudança deve avaliar impacto documental.

III. Todo documento crítico precisa de owner.

IV. Documentação precisa possuir versão.

V. Informação precisa ser encontrável.

VI. Procedimentos críticos precisam ser testados.

VII. Documento obsoleto precisa ser claramente aposentado.

VIII. IA pode escrever rascunhos; humanos continuam responsáveis pela verdade.

IX. Conhecimento crítico não pode existir somente na cabeça de uma pessoa.

X. Documentação faz parte do produto.

Ferdinand lê.

Fica em silêncio.

— Onze regras seriam mais completas.

Myne fecha o livro.

— Dez ficam melhores num slide.

---

☕ EPÍLOGO — O ÚLTIMO LIVRO DE CARLOS

Alguns meses depois, Carlos anunciou aposentadoria.

Ninguém entrou em pânico.

Durante meses, a equipe havia transformado seu conhecimento em:

Architecture Guides
Runbooks
Troubleshooting Guides
Decision Records
Diagramas
README
Procedimentos
Histórico de mudanças

Mais importante: outras pessoas haviam utilizado e testado aquele conhecimento.

No último dia, Carlos deixou sobre a mesa uma pequena folha.

Myne encontrou.

Nela estava escrito:

03:17

Se PAYB0031 apresentar S0C7 depois do fechamento,
não reinicie imediatamente.

Verifique primeiro o arquivo PAY.IN.TRANS.

E não acredite no procedimento de 2019.

Myne sorriu.

Digitalizou a informação.

Criou um ticket.

Atualizou o troubleshooting.

Relacionou ao sistema.

Mandou revisar.

E destruiu a folha.

Porque finalmente aquela empresa havia compreendido algo que bibliotecários sabem há séculos:

conhecimento que não pode ser encontrado não está verdadeiramente disponível.

Conhecimento que não pode ser verificado não é confiável.

Conhecimento que depende de uma única pessoa não pertence realmente à organização.

E conhecimento que não acompanha a evolução do sistema lentamente se transforma em ficção.

Para um programador COBOL iniciante, talvez essa seja uma das lições mais importantes da carreira.

Você não herdará apenas programas.

Herdará decisões tomadas por pessoas que talvez nunca conheça.

Encontrará campos criados antes de você nascer.

COPYBOOKs compartilhados por dezenas de aplicações.

JCLs cujo comentário mais recente terá quinze anos.

Regras de negócio que sobreviveram a três presidentes da empresa, quatro arquiteturas e seis gerações de programadores.

Um dia alguém também encontrará o seu código.

E encontrará algo como:

      *---------------------------------------------------------*
      * CHG-98472 - 23/09/2026                                 *
      * ALTERADA REGRA DE CLIENTE ESPECIAL.                    *
      * MOTIVO: NOVA REGRA CONTRATUAL.                          *
      * DOCUMENTACAO: DOC/PAYMENTS/RULES-CLIENTE-ESPECIAL.MD    *
      *---------------------------------------------------------*

Essa pessoa talvez nunca saiba seu nome.

Mas saberá por que aquilo existe.

E existe algo profundamente bonito nisso.

Porque mainframes são máquinas construídas para sobreviver ao tempo.

COBOL também.

Mas sistemas de cinquenta anos não sobrevivem apenas porque o hardware continua funcionando.

Eles sobrevivem porque sucessivas gerações de profissionais conseguem receber, compreender, modificar e transmitir conhecimento.

Somos temporários.

O sistema pode continuar.

O código fica.

As decisões ficam.

A documentação deveria ficar também.

E talvez Myne, olhando para milhões de linhas COBOL preservadas durante décadas, finalmente percebesse que havia encontrado uma biblioteca muito diferente daquela que sempre sonhou construir.

Uma biblioteca na qual alguns livros são executáveis.

E onde esquecer de atualizar uma página pode, às 03:17 da manhã, derrubar produção.

Bem-vindo à Biblioteca do Mainframe.

Seu próximo commit também é uma página da história.