0xtan0/skills - Fluxo de Infraestrutura em Apresentação

Fluxo de Infraestrutura em Apresentação

Saída: um Artifact HTML privado, com cerca de 8 slides, para uma reunião onde o apresentador fala. Os diagramas carregam o significado. O texto é mínimo. Cada bloco, flecha e afirmação vem do código; nada vem da memória ou apenas de documentação.

Ordem de trabalho: Etapa 0 configurar → Etapa 1 pesquisar e escrever os ledgers → Etapa 2 construir → Etapa 3 verificar até 0 problema(s) → Etapa 4 publicar e relatar.

Etapa 0 — Configurar

1. Copie assets/template.html para um caminho temporário. Cada revisão e cada publicação usa esse mesmo caminho, para que a URL do Artifact permaneça a mesma.
2. Coloque os ledgers (Etapa 1) em um ledger.txt ao lado. assets/ledger.example.txt mostra o formato; os ids e caminhos nele são inventados.
3. Carregue a skill artifact-diagramming antes de desenhar um SVG. Siga o contrato da página Artifact (tokens de tema, sem doctype, margem lateral).

O template é uma apresentação funcional com um exemplo prático: motor de slides, lógica Play/Step/Reset, tiles estilo AWS, caixas de conta e região, um fluxo secundário pontilhado e um tile de logotipo da marca. Altere os dados e as coordenadas; não reescreva o motor.

Fatos do motor:

• player(svgId, prefix, steps, idleCaption) executa um slide Play. Prefixo '' usa #play/#back/#next/#reset/#cap; 'n' usa #nplay/…/#ncap (rede), 'i' usa #iplay/…/#icap (IAM), 'r' usa #rplay/…/#rcap (release). Coloque seu valor retornado em stops. Um passo é {n:[ids de nós], a:[ids de flechas], c:'legenda'}; a pode estar vazio. player() se registra em window.__players; scripts/check.py lê isso, então mantenha a linha.
• tile(id,cx,cy,color,glyph,label,sub,side): side é falso (rótulo abaixo), 'l', 't' ou verdadeiro (direita). Um rótulo abaixo bloqueia qualquer linha vertical através dessa coluna. Mova-o para o lado.
• chipRow(cy, items, x0) desenha chips de concessão ao lado de um tile de função. Cada item é [texto, cor da faixa, id, negar?]; cada chip é um .node, então um passo Play pode iluminá-lo, e negar? adiciona o contorno vermelho. Um chip tem 360px de largura; a verificação falha se o texto ultrapassá-lo.
• Os marcadores de flecha vivem em um único svg oculto-mas-renderizado no topo do body. Nunca adicione defs() dentro de um slide: um marcador em um slide display:none não é pintado em outros slides.
• Classes de linha: .arr flecha sólida de fluxo principal (cada uma deve estar em um passo Play); .arr deny tracejada vermelha, para uma Negação explícita ou um limite de permissões; .mon pontilhada fluxo secundário; .deploy repositório → conta; .uses uso entre contas. Caminhos usam apenas M H V L absolutos.
• Glifos em G: core clock, ecs, lambda, ssm, kms, sqs, rpc, hash, cube, target; rede alb, nat, igw, ep, ec2, db, waf, r53, logs, user; identidade role, gcp; release branch, cloud; IA brain; marcas github, vercel, discord, pagerduty, slack. Glifos de marca são brancos: dê ao tile a cor da marca (github #24292f, vercel #000000, discord #5865F2, pagerduty #06AC38; slack é em cor, tile #ffffff). Adicione uma marca apenas como seu caminho de logotipo real.
• Os slides de rede, IAM, release e matriz estão no template como seções comentadas. Descomente a seção, preencha #net, #iam, #rel ou a tabela .mx, e registre cada Play com player().

Etapa 1 — Pesquisar o sistema no código (obrigatório, antes de desenhar)

Pesquise no branch de deploy: o branch cujo merge se aplica à produção. Compare com o branch padrão apenas para notar desvios; desenhe o que a produção executa. Delegue a um subagente se o repositório for grande. Peça a ele um resumo factual com caminhos de arquivo.

1. Leia os arquivos AGENTS.md / README do repositório, depois o IaC (Terraform, CDK, etc.), o código do serviço, os contratos e os documentos de deploy. Siga referências para repositórios irmãos.
2. Decida o que o diagrama deve mostrar. Comece pelo fluxo principal que o usuário pergunta. Liste os elementos que ele toca, de ponta a ponta, e mantenha apenas o que o público precisa entender desse fluxo. Tipos típicos de elemento:
   • Componentes de runtime: tarefas, funções, serviços, workers, monitores, jobs.
   • Gatilhos: agendadores, filas, eventos, webhooks, usuários.
   • Dados e configuração: armazenamentos de parâmetros, segredos, bancos de dados, filas.
   • Confiança e assinatura: armazenamentos de chaves, signatários, funções que cruzam um limite.
   • Partes externas: provedores RPC/API, ferramentas de chat/alertas, chains, serviços de terceiros.
   • Limites: contas, regiões, redes, on-chain vs off-chain. Diga quais elementos você deixa de fora e por quê.
3. Para cada elemento que você mantém, encontre no código o que importa para o diagrama. Apenas os fatos que se tornam um bloco, uma flecha ou uma legenda: o que o inicia; o que ele lê; o que ele escreve ou envia; quem assina ou autoriza por ele e com quê; quem paga por ele (taxas, gás, proprietário do custo; procure exceções); em qual limite ele está.
4. Propriedade. Faça uma tabela de contas × regiões, e de repositórios → o que cada um implanta onde, apenas se o sistema tiver mais de uma conta ou mais de uma região. Se não tiver, pule esta tabela e o slide de propriedade.
5. Rede. Leia o IaC de rede completamente: VPC e subnets (CIDRs, número de AZs, em qual camada cada recurso está), tabelas de rota, NAT e gateways de internet, endpoints privados (e se o DNS privado está ativado), cada grupo de segurança e cada regra (origem, porta, CIDR ou referência SG), balanceadores de carga (interno ou voltado para internet, ação padrão do listener), tipo de origem CDN, descoberta de serviço, bastion ou outro acesso humano, logs de fluxo. Anote o que está nas subnets públicas. Anote quais chamadas de API cloud saem através do NAT porque não existe endpoint. Escreva o resultado como um ledger de borda antes de desenhar: uma linha por par de regra de grupo de segurança e por grupo de destino do balanceador de carga, como origem → destino :porta (arquivo:linha). Grepe por cada recurso de regra (para AWS: aws_vpc_security_group_ingress_rule, aws_vpc_security_group_egress_rule, blocos ingress/egress, aws_lb_target_group, aws_lb_listener, aws_vpc_endpoint) através da raiz e de cada módulo que ele chama. Não construa o ledger a partir de um resumo ou da memória.
6. IAM. Grepe cada função, política, anexo de política, documento de política, política de confiança e limite de permissões na raiz e seus módulos. Escreva um ledger IAM, uma linha por função: função | confiado por + cada condição | principais concessões | negações explícitas, limite | arquivo:linha. Condições são fatos que o público precisa: id do repositório OIDC, ref, ambiente, ExternalId, SourceAccount, nome da sessão. Depois escolha:
   • Funções principais: funções que cruzam um limite (outra conta, CI, um cliente), podem alterar infraestrutura, ou tocam dados do cliente. Funções que apenas escrevem seus próprios logs são deixadas de fora (relate-as).
   • Políticas críticas (0–5): declarações Deny explícitas, limites de permissões, recursos *, iam:PassRole, sts:AssumeRole entre contas. Cite o sid. Se nenhuma existir, diga isso; não invente uma.
7. Caminho de release. Leia cada workflow CI: gatilho (pull_request ou push, branches, paths), o ambiente CI, a função que ele assume, proteções de fork PR, etapas de build antes do apply, e dispatch manual. Leia as regras do repositório sobre quem faz merge de releases. Para imagens de aplicativos, leia as funções de deployer (ref de confiança, o que elas podem enviar e atualizar) e se o IaC ignora mudanças na definição de tarefa. Workflows de repositórios de aplicativo fora deste repositório são NÃO CONFIRMADOS a menos que você os leia.
8. Armazenamentos de dados. Liste cada armazenamento que contém dados de cliente, auditoria ou segredos: bancos de dados, buckets, o estado do IaC, grupos de log, armazenamentos de segredos. Para cada um: chave de criptografia (KMS do cliente, gerenciado pela cloud, gerenciado pelo armazenamento) e TLS, retenção (backups, Object Lock, versionamento, lifecycle, dias de log, proteção contra exclusão, janela de recuperação de segredo), disponibilidade (Multi-AZ, cópias em outra região ou conta), exposição, quem pode ler os dados (não a configuração) incluindo CI após suas negações, e auditoria (eventos de dados, logs de banco de dados). Classifique cada célula como forte, parcial ou lacuna, com um arquivo:linha.
9. Estado ativo. Para cada elemento de computação, leia sua contagem desejada (ou réplicas, ou agendamento) e a barreira na frente dele (ação padrão do WAF, regra do listener, feature flag). Um serviço com zero, ou bloqueado na borda, está estacionado; a apresentação diz isso.
10. Exposição pública. Grepe public_access_block, principals com "*", acl, publicly_accessible, associate_public_ip_address, internal = false, CIDRs abertos de grupos de segurança. Liste cada objeto público, endpoint ou relaxamento em toda a conta, e o que ele custa (por exemplo, um bucket que perde uma camada de proteção).
11. Feito à mão. Grepe por consultas de dados de âncoras de confiança (zonas DNS, provedores OIDC, buckets de estado, conexões, configurações de conta) e por "console", "à mão", "out of band", "apply manual" em comentários e guias de deploy. Mantenha uma lista: "feito à mão, fora do IaC".
12. Marque tudo o que você não pode confirmar no código como NÃO CONFIRMADO. Informe o usuário sobre isso. Não desenhe como um fato.
13. Obtenha a ordem das etapas a partir do código, não da lista do usuário. Se a ordem do código diferir, use-a e diga isso.

Em seguida, escreva ledger.txt para a verificação a partir dos ledgers de borda e IAM: arrowId | origem -> destino :porta | arquivo:linha, ou - | deixado de fora: motivo | arquivo:linha.

Etapa 2 — Construir a apresentação

Slides:

1. Título.
2. Diagrama de fluxo principal com Play. Blocos do primeiro gatilho até o efeito final. Botões Play, Step back, Step next e Reset, mais uma legenda por passo.
3. Diagrama de fluxo de rede com Play. Uma VPC, desenhada uma vez (não uma vez por AZ; escreva o número de AZs e os CIDRs das subnets nos títulos das caixas). Faixas: subnets públicas, subnets privadas. Fora da VPC: o CDN ou cliente, o operador, a internet. Passos Play, nesta ordem: tráfego de entrada (origem CDN, SG do balanceador de carga, SGs de tarefa), aplicativo para dados (SGs de banco de dados, balanceadores de carga internos), tráfego de saída (egresso de tarefa, rota para NAT, gateway de internet), caminhos isolados (funções sem rota de internet, endpoints), acesso humano (bastion, encaminhamentos de porta). Coloque a porta ao lado de cada flecha como um texto .tag (:443, :5432). Logs de fluxo e outros observadores são pontilhados e não estão no Play. Pule este slide se o sistema não tiver rede própria (por exemplo, apenas serviços serverless gerenciados) e diga isso no relatório.
4. Funções IAM principais com Play. Três colunas: quem pode assumir (repositório e branch, serviço cloud, outra conta) → tile da função (Segurança #DD344C) → o que ela alcança (tiles de recurso ou chips). Coloque as condições de confiança como texto .tag na flecha de confiança (ref: main, ExternalId). Desenhe cada política crítica como uma linha vermelha .arr deny para o que ela bloqueia, com o sid ou a ação como uma tag (Deny ssm:*). Um passo Play por grupo de funções (CI, deployers, runtime, entre contas), depois um passo por política crítica. Use os mesmos nomes dos outros slides.
5. Como uma mudança chega à produção, com Play. Tiles de branch na linha superior (rótulos acima), um tile de conta abaixo de cada branch ao qual se aplica, repositórios de aplicativo e funções de deployer em uma faixa inferior. Tags de flecha dizem a barreira (PR + plan, merge: apply, push to main). Passos seguem a ordem real; diga quais passos uma pessoa faz manualmente.
6. Onde os dados vivem (matriz). Uma tabela HTML (.mx), não um SVG. Uma linha por armazenamento, colunas: criptografia, retenção, disponibilidade, exposição, quem pode ler os dados, auditoria. Cada célula começa com um ícone de status e rótulo (✓ forte, ◐ parcial, ✕ lacuna) e usa os tokens de status --good/--warn/--crit, nunca cores de série. Cada célula tem um title com sua origem. Um rodapé informa lacunas transversais (nenhuma cópia em outra região, CI que pode editar suas próprias negações). A matriz mantém seus próprios tamanhos de fonte; ela deve caber no slide sem rolagem.
7. Contas, regiões e repositórios. Um diagrama estático. Apenas se a Etapa 1, Propriedade, se aplicar.
8. Pontos-chave, 3–5 linhas curtas. Use apenas afirmações que você verificou na Etapa 1. Inclua uma afirmação de rede se for verdadeira (por exemplo, o que está nas subnets públicas). A lista "feito à mão" vai aqui ou no slide de contas.

Regras (aprendidas com revisão; siga todas)

Precisão

• Desenhe toda relação de assinatura que o código tem. Quando um armazenamento de chaves (por exemplo KMS) faz a assinatura, cada componente que o usa recebe sua própria flecha para ele. Procure por mais de um signatário.
• Não escreva uma afirmação absoluta ("X nunca paga", "Y não contém segredos", "Z sempre…") até que você procure no código por exceções. Se uma exceção existir, diga-a ou descarte a afirmação.
• Toda propriedade de segurança ou confiabilidade em um slide deve vir do código ou da configuração. Não adicione garantias plausíveis (quóruns, retentativas, redundância) que você não encontrou.
• Desenhe todo gatilho e toda leitura/escrita para cada elemento que você mantém. Não desenhe apenas os no caminho principal.

Escopo e ruído

• Não copie o mesmo diagrama uma vez por ambiente (dev/staging/prod lado a lado). Mostre um ambiente, por padrão o de produção, e diga isso.
• Se a produção for multi-região, mostre-a. Coloque caixas de região dentro de cada conta e rotule cada região com seu papel (primária, réplica, standby, backup).
• Fluxo principal vs fluxos secundários. Os passos Play cobrem apenas o fluxo principal que o usuário perguntou. Desenhe outros fluxos que compartilham a mesma infraestrutura (monitoramento, alertas, admin ou jobs batch) como linhas pontilhadas. Mantenha-os fora dos passos Play e dê a eles uma legenda curta.

Cobertura (verifique antes de cada publicação)

• Em um slide que abrange ambientes (caminho de release, contas), leia todas as raízes, não apenas a de produção. Um caminho de deploy criado por um módulo que toda raiz chama (uma função de deployer, um pipeline, uma confiança) alcança todo ambiente: desenhe uma flecha por ambiente, com o branch ou condição que cada um confia. "Apenas prod" precisa de prova de que as outras raízes não o chamam.
• Um balanceador de carga, proxy, gateway, endpoint ou fila nunca é o fim de uma flecha. Desenhe-o e o componente atrás dele, com o segundo salto como sua própria flecha e passo.

…

[truncado para tradução]