Como agentes especializados no GitHub Copilot ajudam a entender estates Natural, Adabas, COBOL e DB2.
O time não escreve do zero. O agente lê, indexa, propõe. O humano revisa, valida, decide, assina.
@archaeologist lê legado · @architect escreve spec · @builder constrói · @evolution operacionaliza.
Recebe issues bem escritas pelo @evolution, executa em background, abre PR draft.
Sistema de Fiscalização e Administração de Pagamentos.
É um exemplo. Pode ser o seu sistema de cobrança, seu core bancário, sua plataforma de RH.
Constante mágica 0.347215 sem origem legal em CADPROG.NSN.
Institucionalizado no DDM como feature.
COD-REGIAO=99 pula todas as validações em VALELEG.NSN.
Filtra silenciosamente ACAO='EX' antes de imprimir auditoria.
Índice consolidado. As tabelas detalhadas (187 regras com fonte arquivo.NSN:Lstart-Lend, classificação EARS e notas) vivem nos 5 fragments em _fragments/, um por par. Não duplicamos as linhas aqui para manter rastreabilidade única.
| Programas Natural lidos | 15 |
| DDMs cruzados | 4 |
| Regras extraídas | 187 |
| Confirmadas (cruzaram com docs) | 43 |
| Inferidas (só código, sem doc) | 104 |
| Mistérios (<!-- mystery: -->) | 44 |
| Divergências críticas doc × código | 9 |
Razão Inferida/Confirmada ≈ 2.4×: a documentação histórica (1997/2008/2012) cobre menos de metade da lógica real. O Estágio 2 trata regras Inferidas como candidatas a entrevista com PO/SME, não como verdade pronta.
| Par | Programas | Regras | Mistérios |
|---|---|---|---|
| 1 · Visão | CADBENEF, CADDEPEND, CADPROG | 32 | 10 |
| 2 · Arquitetura | BATCHCON, BATCHPGT, BATCHREL | 47 | 12 |
| 3 · Implementação | CALCBENF, CALCCORR, CALCDSCT | 44 | 11 |
| 4 · Qualidade | VALBENEF, VALDOCS, VALELEG | 30 | 6 |
| 5 · Operações | CONSBENF, RELAUDIT, RELPGT | 34 | 5 |
| # | Tema | Conflito |
|---|---|---|
| 1 | Limite de dependentes | RN-004 diz 3; CADDEPEND.NSN:L66-L69 aceita 5; CALCBENF aceita >3 |
| 2 | Fórmula do benefício (Fator Familiar) | REGRAS-NEGOCIO-2012 §6 = aditiva; CALCBENF.NSN = multiplicativa |
| 3 | Significado de STATUS-PGTO = P | Doc 2012 = pendente; Manual 2008 = PAGO; RELPGT trata como pago |
| 4 | Arredondamento × truncamento | Manual 2008 §4 arredonda 5 casas; BATCHPGT trunca |
| 5 | Fator K = 0.347215 | Constante mágica em CADPROG.NSN:L81 sem fonte legal/regulatória |
| 6 | Desconto 3% × 30% | Doc cita 3%; BATCHCON aplica 30% |
| 7 | Validação de CPF duplicada em 4 lugares | CADBENEF, CADDEPEND, VALBENEF, VALDOCS reimplementam DV com variações |
| 8 | RELAUDIT oculta ACAO='EX' | Conflita com RN-011 (auditoria completa); flag de compliance |
| 9 | Cap de desconto agregado | CALCDSCT aplica cap; RN-023 manda descartar por prioridade |
| # | Descrição |
|---|---|
| 1 | Fator K = 0.347215 sem origem documentada (Par 1 + 2) |
| 2 | Tabela de 25 fatores regionais 1.0000-1.4000 sem critério legal (Par 3) |
| 3 | Faixas de renda hardcoded (R$ 300/600/1000/1500) sem indexação desde 2013 (Par 3) |
| 4 | Bloco Plano Verão comentado, fatores 2.7500 e 1.4289 (Par 3) |
| 5 | Status S para idade > 75 fora do domínio documentado A/E (Par 1) |
| 6 | CPF 00000000000 aceito em CADDEPEND e por exceção em VALBENEF (Par 1 + 4) |
| 7 | Região 99 ⇒ elegibilidade automática, backdoor em VALELEG (Par 4) |
| 8 | Tabela de prefixos especiais em VALDOCS que anula erros de DV (Par 4) |
| 9 | RELAUDIT oculta exclusões, viola auditoria completa (Par 5) |
| 10 | Tabela IPCA estática 2010-2012, fora dessa janela correção é ignorada (Par 3) |
| ✓ | Todo bloco IF/THEN/ELSE/DECIDE/AT BREAK examinado (15 programas) |
| ✓ | Cada regra tem fonte arquivo.NSN:Lstart-Lend (rastreabilidade nos fragments) |
| ✓ | Regras confirmadas citam seção da doc (43 de 187) |
| ✓ | Mistérios marcados com <!-- mystery: --> (44) |
| ✓ | EARS proposto para cada regra confirmada |
| ✓ | Divergências cross-cutting consolidadas (9) + matriz de rastreio dos 44 |
Adabas não tem tabelas planas com linhas. Tem um FDT, Field Definition Table, onde um registro carrega grupos inteiros dentro de si. Entender isso é entender por que a tradução é difícil.
Relacional: tabelas, linhas planas, chaves estrangeiras, índices B-tree. Um dependente é uma linha em outra tabela.
FDT: um registro de beneficiário carrega até 10 dependentes DENTRO dele. Sem tabela separada, sem JOIN.
Base principal. Grupo periódico de dependentes (máx 10) e o CPF-sentinela 00000000000 vivem aqui.
Tabela paramétrica. O campo FATOR-K (N5.4) está aqui, com ">>> NÃO DOCUMENTADO <<<" gravado no próprio FDT.
Transacional, sem política de purge. Todos os registros desde 1998. Máquina de estados de 7 status num campo só.
Imutável (INSERT ONLY), retenção indefinida por lei. Pares antes/depois em multivalor de até 20 campos.
NUM-CPF é um campo escalar simples. É o único tipo de campo que vira diretamente uma coluna numa tabela relacional. Tudo abaixo dele é o que torna a migração difícil.
Clique nas outras partes do registro →
A resposta não é escrever código mais rápido. É escrever a especificação primeiro, e deixar o agente trabalhar dentro dela.
"Construa o cálculo do benefício." A IA gera código na hora, adivinha a arquitetura, pula os requisitos. Funciona, mas não bate com a regra do legado. 40% do tempo vira retrabalho.
A regra do CALCBENF.NSN vira uma EARS testável, com source_legacy. O agente só implementa o que a spec diz. O que sai é verificável contra o legado.
A metodologia. Define o QUÊ.
O motor. Força o COMO.
Produzido pelo @architect a partir de discovery-report.md §7 e dependency-map.md. Arquitetura-alvo: Modular Monolith (ver ADR-001).
| Hipótese | Coesão | Acoplamento | Freq. mudança | Decisão |
|---|---|---|---|---|
| A · Cálculo + Pagamento como um único contexto financeiro | Baixa | Médio | Divergente | Rejeitado |
| B · Auditoria embutida em cada contexto | Alta (se isolada) | Alto (se embutida) | Estável | Rejeitado |
| C · Cadastro único para Beneficiário + Dependente + Programa | Alta | Baixo (externo) | Coerente | Aceito |
Conclusões: separar Cálculo e Pagamento (juntá-los criaria um módulo com duas razões de mudança). Auditoria vira contexto próprio com interface de escrita publicada. Cadastro é o aggregate raiz de identidade.
| Contexto | Responsabilidade | Dados próprios |
|---|---|---|
| 1 · Cadastro | Ciclo de vida de beneficiários, dependentes e programas; validação de CPF e elegibilidade. | BENEFICIARIO (150) · DEPENDENTE · PROGRAMA_SOCIAL (151) |
| 2 · Cálculo | Valor base, fatores (regional, etário, família, renda, Fator-K), descontos (cap 30% exceto judicial), correção IPCA. | tabelas de config versionadas · resultados efêmeros |
| 3 · Pagamento | Ciclo mensal, remessa CNAB 240, conciliação por match triplo, status G/P/E/R/D. | PAGAMENTO (152, ~180M reg, particionado) |
| 4 · Auditoria | Trilha append-only de todas as ações; relatórios incluindo exclusões (corrige MYS-010). | AUDITORIA (153, append-only, particionada por ano) |
| De | Para | Mecanismo | Dados |
|---|---|---|---|
| Pagamento | Cadastro | Chamada síncrona | Beneficiários elegíveis por competência |
| Pagamento | Cálculo | Chamada síncrona | (beneficiarioId, competencia) → valor calculado |
| Cadastro | Auditoria | Domain event | Inclusão/alteração/exclusão de beneficiário |
| Cálculo | Auditoria | Domain event | Evento batch (BT) de cálculo executado |
| Pagamento | Auditoria | Domain event | Geração de ciclo + conciliação |
Regra: comunicação cross-context só via interface pública ou domain event, nunca acesso direto a repositório de outro módulo (ver ADR-001, anti-corruption layer).
ADR-001 Modular Monolith sobre microservices. Formato MADR, duas opções avaliadas, consequências documentadas.
Context
Cap non-judicial deductions at 30% of gross amount. Judicial deductions are exempt (BR-CDSCT-004).
Source legacy
01-arqueologia/legado-sifap/natural-programs/CALCDSCT.NSN#L142-L148
Acceptance
Files to touch
backend/src/main/java/br/gov/sifap/payment/application/DeductionService.javabackend/src/test/java/br/gov/sifap/payment/application/DeductionServiceTest.javaDo not
Preenchido pela equipe ao final do Estágio 4. Seja honesto: queremos aprender o que funciona e o que não funciona. Avaliação positiva forçada não ajuda ninguém.
| Issue | PR | Arquivos | Testes | Ajuste manual | Merge |
|---|---|---|---|---|---|
#142 Cap descontos 30% | #312 | 4 | Sim | Não | Após revisão |
#143 Auditoria inclui exclusões EX | #318 | 6 | Sim | Pequeno | Após revisão |
| ✗ | Imports incorretos ou circulares (import alucinado) |
| ✗ | Teste que passava sem exercitar a regra |
| ✗ | Scope creep, tocou arquivo fora do pedido |
| ✓ | Todos pegos na revisão humana antes do merge |
| Critério | Nota |
|---|---|
| Corretude do código | 4 |
| Aderência à arquitetura | 4 |
| Qualidade dos testes | 3 |
| Documentação gerada | 4 |
| Média geral | 3.8 |
Sim, para tarefas simples e bem definidas. Para regra fiscal core, sempre com spec, testes de equivalência e revisão humana. O agente é contribuidor da equipe, não aprovador.
| Aspecto | Agent | Chat | Manual |
|---|---|---|---|
| Velocidade | Alta | Média | Baixa |
| Controle | Médio | Alto | Alto |
| Quando usar | Tarefa definida | Exploração | Regra crítica |
| 05/2026 | R$ 1.412,00 | PAGO |
| 04/2026 | R$ 1.412,00 | PAGO |
| 03/2026 | R$ 1.412,00 | PAGO |
CBENF020.NSP agora vive em BeneficiaryController.findByCpf(). Regras BR-CBENF-001..014 cobertas por BeneficiaryServiceTest.A primeira fatia é uma aposta de aprendizado, não de valor. Escolha algo pequeno o bastante para terminar em dias, real o bastante para convencer o time.
Tem regra de negócio clara e testável (ex: cálculo de desconto), poucos integrantes downstream, e alguém vivo que conhece o domínio.
É o motor de pagamento inteiro, toca 180M de registros, ou ninguém sabe explicar por que funciona. Isso vem depois, com o método já provado.
CALCDSCT: o cálculo de descontos. Regra isolada, divergência conhecida (cap 30% vs judicial), e um golden master fácil de montar.
Habilite o GitHub Copilot, suba os 4 agentes custom num repo de teste e rode o @archaeologist na primeira fatia.
Instale o Spec-Kit, transforme os achados em spec assinada e ponha um CI mínimo no GitHub Actions.
Com o método provado, integre o Azure conforme a fatia exigir: runtime, segredos e observabilidade.
✗Big bang: reescrever tudo de uma vez, em paralelo ao legado que segue mudando.
→Fatie. Uma regra por vez, com golden master contra o legado. Strangler fig, não substituição total.
✗Confiar no código como spec: "o sistema é a documentação, vamos só traduzir."
→O código tem 44 mistérios e 9 divergências. Cada um vira [NEEDS CLARIFICATION], não uma suposição.
✗Vibe coding no legado: pedir pro agente "modernizar" sem spec nem teste de equivalência.
→Spec primeiro, validada por schema. O agente só implementa o que a EARS declara, e o teste prova paridade.
✗Corrigir bugs em silêncio: "isso tá errado no legado, vou só consertar no novo."
→Aquele "bug" pode ser regra fiscal de 20 anos. Escale a decisão; preserve ou corrija com respaldo, nunca por palpite.
Qual fatia do seu legado você levaria pro @archaeologist primeiro?
Essa é a fatia que começa segunda de manhã.
Paula Silva
Software Global Black Belt · Microsoft
paulasilva@microsoft.com
Workshop de uma fatia
Um dia, time real, legado real, primeira fatia rodando
agents: - { name: archaeologist, tools: [read, search] } - { name: architect, tools: [read, search, edit] } - { name: builder, tools: [read, search, edit, execute] } - { name: evolution, tools: [read, search, edit, execute, web] } speckit: { version: latest, integration: copilot }