| Bellacosa Mainframe e a metodologia agil uma pequena introdução |
☕ Um Café no Bellacosa Mainframe
🧙 SHIROE E A DUNGEON DA DOCUMENTAÇÃO — QUANDO O PROGRAMADOR COBOL DESCOBRIU QUE ÁGIL NÃO SIGNIFICA PROGRAMAR SEM MAPA
Agile Modeling, COBOL, documentação, conhecimento tribal, Bus Factor, CICS, Db2, VSAM, JCL, modelos, legado, IA — e o dia em que Shiroe descobriu que um comentário escrito em 1989 podia valer mais que um documento de 400 páginas.
🎬 PRÓLOGO — BEM-VINDO A ELDER TALE
Imagine acordar dentro de um sistema que existe há quarenta anos.
Não um MMORPG.
Pior.
Um sistema corporativo.
Você abre o inventário:
3.842 programas COBOL
1.927 copybooks
674 JCLs
283 PROCs
416 tabelas Db2
138 arquivos VSAM
91 transações CICS
37 filas MQ
12 sistemas externosE uma documentação chamada:
DOCUMENTACAO_FINAL_V7_DEFINITIVA_REV3_ULTIMA.docData da última atualização:
17/08/2004Shiroe ajusta os óculos.
— Não confie no nome do arquivo.
O jovem programador COBOL pergunta:
— Então vamos documentar tudo novamente?
Shiroe olha para os milhares de componentes.
— Não.
— Então não vamos documentar nada?
— Também não.
Bem-vindo ao problema que o Agile Modeling tenta resolver.
🏰 CAPÍTULO 1 — O MONSTRO NÃO É A DOCUMENTAÇÃO
Quando alguém começa a estudar desenvolvimento ágil, existe uma interpretação perigosa:
“Ágil significa pouca documentação.”
Não.
Outra interpretação é ainda pior:
“Ágil significa nenhuma documentação.”
Também não.
O material que deu origem à nossa investigação apresenta Agile Modeling, ou AM, como uma abordagem para tornar modelagem e documentação mais eficientes. A preocupação central é evitar produzir e manter artefatos que não entregam valor suficiente ao projeto.
A ideia fundamental é simples:
DOCUMENTAR
↓
custa tempo
↓
custa dinheiro
↓
precisa ser atualizado
↓
portanto
↓
PRECISA TER UTILIDADEImagine que alguém passe oito horas criando um belíssimo diagrama UML.
Ele é impresso.
Colocado numa pasta.
Arquivado.
Nunca mais ninguém olha para ele.
Tecnicamente houve documentação.
Economicamente talvez tenha ocorrido apenas desperdício.
Agora imagine o contrário.
Um programador escreve três linhas:
* REGRA CRIADA PARA CONTRATOS ANTERIORES A 1994.
* NAO REMOVER SEM VALIDACAO COM FATURAMENTO.
* REF: NORMA FIN-047.Trinta anos depois, alguém encontra esse comentário.
Ele impede que uma regra aparentemente inútil seja removida.
Três linhas acabaram de salvar uma manutenção.
Qual documentação possuía mais valor?
Shiroe sorriria.
Essa é a pergunta correta.
🧙 CAPÍTULO 2 — O QUE É AGILE MODELING?
Agile Modeling não deve ser confundido com uma metodologia completa de desenvolvimento.
O próprio material destaca essa diferença: AM concentra-se na modelagem, podendo complementar tanto abordagens ágeis quanto processos mais prescritivos.
Pense assim:
DESENVOLVIMENTO DE SOFTWARE
┌─────────────────────────────────────┐
│ │
│ Scrum / XP / Kanban / outros │
│ │
│ ┌─────────────────────┐ │
│ │ AGILE MODELING │ │
│ │ │ │
│ │ entender │ │
│ │ modelar │ │
│ │ comunicar │ │
│ │ validar │ │
│ │ documentar │ │
│ └─────────────────────┘ │
│ │
└─────────────────────────────────────┘Agile Modeling pergunta:
Qual é a maneira mais eficiente de representar determinado conhecimento?
Às vezes será UML.
Às vezes será uma tabela.
Às vezes será um fluxograma.
Às vezes será um protótipo.
Às vezes será um desenho feito no quadro branco.
Às vezes será o próprio código.
Isso nos leva a uma ideia fundamental.
🗺️ CAPÍTULO 3 — O MAPA NÃO É A DUNGEON
Shiroe conhece mapas.
Mas nenhum jogador de Log Horizon confundiria o mapa de Elder Tale com Elder Tale.
O mapa é uma representação simplificada da realidade.
Software funciona da mesma maneira.
Considere:
CLIENTE
│
▼
API
│
▼
z/OS Connect
│
▼
CICS
│
▼
COBOL
│
├───────────┐
▼ ▼
Db2 VSAMIsso não contém cada programa, variável, tabela, chamada ou transação.
E não precisa.
Seu propósito pode ser simplesmente responder:
“Como uma requisição externa chega ao programa COBOL?”
Se respondeu isso, cumpriu sua missão.
O documento original define um modelo ágil por características como atender ao propósito, ser inteligível e possuir detalhamento suficiente, evitando complexidade adicional que não contribua para a comunicação.
Essa expressão é importantíssima:
suficientemente detalhado.
Não é:
minimamente detalhado.
Também não é:
absurdamente detalhado.
É suficiente para a missão.
⚔️ CAPÍTULO 4 — MODELE COM UM PROPÓSITO
Antes de criar qualquer documento, Shiroe colocaria uma pergunta na mesa:
POR QUE?Por que estamos fazendo este diagrama?
Por que estamos escrevendo este documento?
Por que precisamos desta planilha?
Por que estamos descrevendo esta interface?
As respostas possíveis podem ser:
entender o sistema
comunicar uma arquitetura
explicar uma regra
treinar uma pessoa
registrar uma decisão
atender auditoria
planejar uma alteração
operar produção
recuperar um processamento
investigar incidenteTudo isso pode justificar documentação.
Agora compare com:
“Porque o processo manda.”
Temos um problema.
Um artefato deve possuir consumidor e finalidade.
Uma pergunta Bellacosa extremamente útil seria:
QUEM VAI USAR ISSO
E PARA TOMAR QUAL DECISÃO?Se ninguém souber responder, investigue antes de produzir cinquenta páginas.
🎒 CAPÍTULO 5 — VIAJE COM POUCA BAGAGEM
Entre os princípios apresentados pelo material está a ideia de “viajar com pouca bagagem”, juntamente com simplicidade, aceitação de mudanças, incrementos, feedback rápido e modelagem com propósito.
Isso é perigoso quando interpretado por alguém muito empolgado.
O jovem aventureiro poderia dizer:
— Shiroe! Descobri! Vamos apagar os documentos!
— Por quê?
— Para viajar com pouca bagagem!
— Aquela pasta contém o procedimento de recuperação do faturamento.
— Ah.
— E aquela contém o mapeamento das interfaces bancárias.
— Ah...
— E você acabou de deletar o procedimento de restart do batch.
— Posso restaurar?
😂
Pouca bagagem não significa entrar numa dungeon sem espada, comida e mapa.
Significa não levar quinze armaduras quando você precisa de uma.
No desenvolvimento:
DOCUMENTAÇÃO ENXUTA
≠
AUSÊNCIA DE DOCUMENTAÇÃOUma definição melhor seria:
DOCUMENTAÇÃO ENXUTA
=
MENOR CONJUNTO DE INFORMAÇÕES
CAPAZ DE PRESERVAR O CONHECIMENTO
NECESSÁRIO🦖 CAPÍTULO 6 — O COBOL DE 1989
Agora Shiroe abre um programa.
3100-CALCULA-TAXA.
IF WS-TIPO-CLIENTE = 'E'
COMPUTE WS-TAXA =
WS-TAXA * 0.8735
END-IF.O iniciante observa.
— Entendi.
Shiroe pergunta:
— Entendeu o quê?
— Clientes do tipo E recebem multiplicação por 0.8735.
— Por quê?
Silêncio.
Eis uma das grandes dificuldades do legado.
Código é excelente para responder:
COMO?
Mas frequentemente é insuficiente para responder:
POR QUÊ?
Talvez 0.8735 represente uma norma de 1989.
Talvez seja uma condição comercial.
Talvez seja compatibilidade com um sistema aposentado.
Talvez seja correção de algum erro histórico.
Ou talvez seja realmente uma porcaria que deveria ter desaparecido em 1997.
Não sabemos.
O código preservou o algoritmo.
Não preservou necessariamente a intenção.
Essa diferença é gigantesca.
🧠 CAPÍTULO 7 — SOFTWARE É CONHECIMENTO FOSSILIZADO
Um sistema legado não é simplesmente código velho.
Ele é uma espécie de arqueologia corporativa.
Dentro dele existem décadas de:
decisões
leis
contratos
exceções
fusões
produtos
clientes
incidentes
migrações
limitações técnicas
decisões arquiteturais
gambiarras
correçõesPor isso um programa de 1987 ainda pode estar executando em 2026.
Não necessariamente porque ninguém conseguiu substituí-lo.
Às vezes porque ele contém uma quantidade absurda de conhecimento acumulado.
Imagine:
IF ESTADO = 'SP'
AND PRODUTO = 17
AND DT-CONTRATO < 19940701
PERFORM 7300-REGRA-ESPECIAL
END-IF.Um iniciante pode pensar:
Que regra horrorosa.
Talvez seja.
Mas antes de apagá-la precisamos descobrir por que existe.
Shiroe diria:
Primeiro descubra as regras do mundo. Depois tente mudá-las.
📚 CAPÍTULO 8 — O CÓDIGO TAMBÉM É DOCUMENTAÇÃO
Agora considere:
01 CUSTOMER-RECORD.
05 CUSTOMER-ID PIC 9(10).
05 CUSTOMER-NAME PIC X(30).
05 CUSTOMER-BALANCE PIC S9(7)V99 COMP-3.
05 CUSTOMER-STATUS PIC X.Alguém cria um documento:
CUSTOMER-ID 10 posições
CUSTOMER-NAME 30 posições
CUSTOMER-BALANCE decimal
CUSTOMER-STATUS 1 posiçãoParece útil.
Mas agora existem duas fontes:
COPYBOOK
+
DOCUMENTOAlguém muda:
05 CUSTOMER-NAME PIC X(40).E esquece o Word.
Nasce uma criatura terrível:
DOCUMENTAÇÃO ZUMBI.
Ela parece viva.
Ela parece oficial.
Ela está errada.
E documentação errada pode ser mais perigosa que nenhuma documentação.
🧟 CAPÍTULO 9 — A DOCUMENTAÇÃO ZUMBI ATACA ELDER TALE
Imagine o manual:
PGM001 chama PGM002.Mas a produção evoluiu:
PGM001
↓
PGM017
↓
MQ
↓
PGM002Chega um incidente.
O analista consulta a documentação.
Começa procurando no lugar errado.
Resultado:
DOCUMENTAÇÃO DESATUALIZADA
↓
HIPÓTESE ERRADA
↓
INVESTIGAÇÃO ERRADA
↓
TEMPO PERDIDO
↓
MTTR MAIORA documentação que deveria reduzir risco tornou-se fonte de risco.
Por isso devemos evitar duplicar indiscriminadamente informações que já possuem uma fonte autoritativa.
Se o copybook define o layout, talvez a documentação deva dizer:
Layout oficial:
COPY CUSTOMER01em vez de copiar cinquenta campos para outro lugar.
👥 CAPÍTULO 10 — O RAID BOSS CHAMADO CONHECIMENTO TRIBAL
O material original traz outra ideia essencial: conhecimento deve ser coletivo, evitando que somente uma pessoa domine todo o processo.
Shiroe encontra a equipe:
— Quem conhece o fechamento mensal?
Todos apontam para Alfredo.
— Quem conhece o programa FATU047?
Alfredo.
— Quem sabe reiniciar o JOB FATNIGHT?
Alfredo.
— Quem conhece aquela interface VSAM?
Alfredo.
Shiroe pergunta:
— Onde está Alfredo?
— Aposentou ontem.
...
Temos um problema.
Hoje costumamos relacionar essa situação ao conceito de Bus Factor: quantas pessoas podem ficar indisponíveis antes que determinado conhecimento crítico desapareça da equipe?
Não precisamos matar ninguém.
A pessoa pode simplesmente:
mudar de projeto;
mudar de empresa;
aposentar;
entrar de férias;
ficar indisponível;
esquecer detalhes depois de anos.
Conhecimento tribal excessivamente concentrado é dívida operacional.
⏰ CAPÍTULO 11 — 03:17
Produção cai.
Relógio:
03:17Easter egg encontrado.
No console:
ICH408I USER(PROD01)
ACCESS INTENT(READ)
ACCESS ALLOWED(NONE)Telefone toca.
— Quem conhece essa aplicação?
Silêncio.
— Onde está o runbook?
Silêncio.
— Como reinicia?
Silêncio.
— Qual foi o último checkpoint?
Mais silêncio.
Nesse momento ninguém quer um UML com 600 classes.
Queremos:
1. O QUE CAIU?
2. QUAL IMPACTO?
3. COMO CONFIRMAR?
4. COMO RECUPERAR?
5. PODE RESTARTAR?
6. DE QUAL STEP?
7. EXISTE RISCO DE DUPLICIDADE?
8. QUEM PRECISA SER ACIONADO?Esse pequeno runbook pode possuir valor operacional gigantesco.
Agile Modeling não mede documentação pela quantidade.
Mede pela utilidade.
🧪 CAPÍTULO 12 — PROVE COM CÓDIGO
O texto inclui entre suas práticas a consideração da testabilidade e a recomendação de “provar com código”.
Isso é fantástico.
Imagine uma reunião:
— Será que COBOL → CICS → MQ → sistema externo suporta 500 transações por segundo?
Podemos criar 47 slides.
Ou criar uma POC.
LOAD GENERATOR
↓
CICS
↓
COBOL
↓
MQ
↓
MOCK EXTERNOAgora medimos:
latência
TPS
CPU
filas
erros
timeouts
retries
locksO PowerPoint dizia:
A arquitetura deverá suportar a carga.
O teste diz:
487 TPS
p95 = 83 ms
CPU = 41%
erro = 0,03%Qual informação ajuda mais na decisão?
Shiroe ajusta os óculos novamente.
— Dados derrotam opiniões com frequência assustadora.
🧩 CAPÍTULO 13 — UM MODELO NÃO PRECISA SER BONITO
Imagine desenhar no quadro:
AUTORIZAÇÃO
↓
CAPTURA
↓
COMPENSAÇÃO
↓
LIQUIDAÇÃOQuatro caixas.
Cinco minutos.
Um iniciante finalmente entende o ciclo de pagamentos.
Missão cumprida.
Não precisamos necessariamente:
EnterpriseArchitectureUltimateFinalDiagram-v23.drawioUm modelo deve comunicar.
Isso significa que podemos utilizar:
ASCII
quadro branco
papel
UML
BPMN
tabela
fluxograma
Markdown
planilha
código
protótipoA ferramenta é secundária.
O conhecimento transmitido é primário.
O próprio material enfatiza que conteúdo é mais importante que representação e recomenda conhecer modelos e ferramentas sem transformar a ferramenta no objetivo.
🏦 CAPÍTULO 14 — MAS E AUDITORIA?
Aqui aparece uma exceção que todo programador precisa compreender.
Imagine um banco.
Alguém pergunta:
— Quem aprovou esta mudança?
Não podemos responder:
“A equipe conversou perto da máquina de café.”
Existem ambientes nos quais documentação serve para:
auditoria
compliance
segurança
rastreabilidade
segregação de funções
regulamentação
continuidade
evidênciaNesse caso o consumidor do documento talvez nem seja o programador.
Pode ser:
auditor
regulador
segurança
jurídico
gestão de riscoO princípio continua exatamente igual:
MODELE E DOCUMENTE COM PROPÓSITO.
A diferença é que o propósito mudou.
Agilidade não elimina governança.
Boa agilidade tenta evitar governança burra.
🤖 CAPÍTULO 15 — SHIROE ENCONTRA UMA INTELIGÊNCIA ARTIFICIAL
Agora chegamos a 2026.
Shiroe recebe:
800 programas COBOL
300 JCLs
150 copybooks
80 tabelasUma IA pode ajudar a descobrir:
CALL GRAPH
DEPENDÊNCIAS
ACESSOS Db2
ARQUIVOS VSAM
FLUXOS BATCH
COPYBOOKS
SQL
INTERFACES
REGRAS CANDIDATASImagine:
SOURCE COBOL
↓
IA
↓
ANÁLISE
↓
MAPAIsso muda profundamente a economia da documentação.
Antes talvez fossem necessárias semanas para reconstruir parte do sistema.
Agora máquinas podem ajudar a acelerar a descoberta.
Mas existe um problema crítico.
A IA lê:
IF WS-TYPE = 'P'
PERFORM CALC-047
END-IFe responde:
“P provavelmente significa cliente premium.”
Provavelmente?
A palavra é importante.
Pode significar:
Premium
Pessoa
Parcelado
Provisório
Produto
PendênciaA IA fez uma inferência.
Não descobriu um fato.
Portanto documentação assistida por IA deveria distinguir claramente:
FATO ENCONTRADO NO SOURCE
↓
INFERÊNCIA TÉCNICA
↓
HIPÓTESE
↓
REGRA CONFIRMADAMisturar essas categorias cria documentação extremamente convincente — e potencialmente falsa.
🧭 CAPÍTULO 16 — PASSO A PASSO: VOCÊ RECEBEU 800 PROGRAMAS COBOL
Não comece abrindo PGM0001.CBL.
Primeiro descubra o mundo.
Passo 1 — Faça o mapa territorial
SISTEMA
│
┌──────────┼──────────┐
▼ ▼ ▼
ONLINE BATCH INTERFACES
│ │ │
CICS JES MQ/API
│ │ │
└──────────┼──────────┘
▼
DADOS
Db2 / VSAMPasso 2 — Descubra entradas
Quem chama o sistema?
3270?
API?
arquivo?
MQ?
outro batch?Passo 3 — Descubra saídas
Para onde o sistema envia informação?
Passo 4 — Identifique dados críticos
Db2
VSAM
sequential datasets
MQPasso 5 — Descubra programas centrais
Procure:
CALL
LINK
XCTL
START
MQPUT
MQGET
EXEC SQL
READ
WRITE
REWRITEPasso 6 — Mapeie jornadas críticas
Por exemplo:
TRANSAÇÃO CICS
↓
PROGRAMA A
↓
PROGRAMA B
↓
SELECT Db2
↓
MQPUT
↓
COMMITPasso 7 — Documente o conhecimento que o código não consegue explicar
Especialmente:
POR QUE?Esse é o ouro.
🟢 CAPÍTULO 17 — O INVENTÁRIO DE SHIROE
Podemos classificar documentação assim:
| Classe | Exemplo | Tratamento |
|---|---|---|
| 🟢 Vital | arquitetura crítica | preservar |
| 🟢 Negócio | regras e exceções | preservar |
| 🟢 Operacional | restart/runbook | preservar |
| 🟢 Segurança | acessos e responsabilidades | preservar |
| 🟡 Temporária | desenho de discussão | descartar quando perder função |
| 🟡 Histórica | decisão antiga relevante | arquivar |
| 🔴 Duplicada | copybook copiado em Word | questionar |
| 🔴 Zumbi | documentação incorreta | corrigir ou eliminar |
| 🔴 Cerimonial | documento sem consumidor | questionar |
Não transforme essa tabela em religião.
Ela própria deve obedecer ao princípio:
Use aquilo que possui valor.
🏛️ CAPÍTULO 18 — DOCUMENTAÇÃO É MEMÓRIA ORGANIZACIONAL
Agora chegamos à conclusão mais profunda.
Um sistema possui várias camadas de conhecimento:
┌───────────────────────────────────┐
│ NEGÓCIO │
│ Por que fazemos isso? │
├───────────────────────────────────┤
│ ARQUITETURA │
│ Como as partes se relacionam? │
├───────────────────────────────────┤
│ IMPLEMENTAÇÃO │
│ Como foi programado? │
├───────────────────────────────────┤
│ OPERAÇÃO │
│ Como funciona em produção? │
└───────────────────────────────────┘O código normalmente preserva muito bem a implementação.
Mas não necessariamente preserva:
intenção
história
decisões
alternativas rejeitadas
restrições
motivações
procedimentos humanosPor isso documentação continua necessária.
O segredo não é documentar tudo.
É descobrir qual conhecimento desapareceria se determinada pessoa saísse amanhã.
Essa pergunta é brutalmente eficiente.
💡 CAPÍTULO 19 — DICAS PARA O PADAWAN COBOL
Quando entrar numa aplicação antiga, não comece julgando.
Pergunte.
Quando encontrar uma regra estranha, não remova imediatamente.
Investigue.
Quando encontrar documentação antiga, não confie cegamente.
Compare com produção.
Quando criar documentação, pergunte quem vai utilizá-la.
Quando copiar informação, pergunte se está criando uma segunda fonte da verdade.
Quando desenhar um modelo, pare quando ele já responder à pergunta para a qual foi criado.
Quando encontrar conhecimento tribal, espalhe esse conhecimento pela equipe.
Quando a IA explicar código, trate inferências como inferências.
E quando o telefone tocar às...
03:17...torça para alguém ter criado um runbook decente.
🥚 CURIOSIDADE — O DOCUMENTO DE 2003 QUE CONTINUA CONVERSANDO COM 2026
Há algo particularmente interessante no material estudado.
Suas referências registram consultas realizadas em abril de 2003.
Estamos olhando para uma discussão produzida quando o movimento ágil ainda era extremamente jovem.
Naquela época era necessário explicar:
“Não estamos dizendo para abandonar documentação.”
Décadas depois continuamos tendo de explicar exatamente a mesma coisa.
A tecnologia mudou:
CASE
↓
UML
↓
Agile
↓
DevOps
↓
Cloud
↓
Containers
↓
LLMs
↓
Agentes de IAMas o problema humano continua:
COMO PRESERVAR
E TRANSMITIR
CONHECIMENTO?Talvez essa seja a verdadeira dungeon.
🧙 EPÍLOGO — SHIROE FECHA O GRIMÓRIO
O jovem programador finalmente pergunta:
— Mestre Shiroe, então qual é a quantidade certa de documentação?
Shiroe permanece alguns segundos olhando para o terminal 3270.
Na tela:
READYEntão responde:
— A suficiente para que alguém consiga entender, decidir, modificar, operar ou recuperar aquilo que precisa... sem obrigá-lo a manter conhecimento que ninguém utiliza.
— Então documentação não é o objetivo?
— Não.
— O código é o objetivo?
Shiroe ajusta os óculos.
— Também não.
O programador estranha.
— Então qual é?
Shiroe aponta para o sistema funcionando.
Resolver o problema.
Código é uma representação.
Diagramas são representações.
Documentos são representações.
Testes são representações.
Modelos são representações.
Até aquele velho comentário COBOL de 1989 é uma representação.
O verdadeiro patrimônio da empresa é o conhecimento que permite que o sistema continue cumprindo sua função.
O material estudado termina reforçando justamente que Agile Modeling não pretende ser solução milagrosa, não substitui competência, não é uma metodologia completa e, sobretudo, não constitui um ataque à documentação ou às ferramentas.
Essa é a lição que vale atravessar décadas.
No mainframe encontramos programas mais velhos que muitos dos profissionais que hoje os mantêm.
Alguns começaram em cartões.
Passaram por terminais 3270.
Sobreviveram a cliente-servidor.
Sobreviveram à Internet.
Sobreviveram ao Java.
Sobreviveram ao “mainframe vai morrer”.
Sobreviveram à cloud.
Agora estão conhecendo inteligência artificial.
E provavelmente sobreviverão a mais algumas revoluções.
Não porque possuam documentação infinita.
Mas porque alguém, em algum momento, preservou conhecimento suficiente para que a próxima geração pudesse continuar a aventura.
Shiroe fecha o grimório.
O terminal continua piscando.
ENTER COMMAND ===>E lá no topo daquele programa COBOL esquecido desde o século passado existe um comentário:
*---------------------------------------------------------*
* NAO REMOVER ESTA REGRA.
* EXISTE POR CAUSA DO FECHAMENTO ANUAL.
* VER INCIDENTE 1989-047.
*---------------------------------------------------------*Três linhas.
Trinta e sete anos.
Milhares de execuções.
Talvez nenhum diagrama UML no mundo conseguisse substituí-las.
Porque Agile Modeling nunca foi simplesmente sobre produzir menos documentação.
Era sobre algo muito mais importante:
preservar o conhecimento e eliminar o ritual.
E essa, jovem aventureiro do COBOL, é uma regra que vale tanto em Elder Tale quanto numa LPAR às 03:17 da manhã.
☕ Bem-vindo ao Bellacosa Mainframe.
Sem comentários:
Enviar um comentário