Pular para o conteúdo

Padrões de engenharia que dá para conferir

Developer Portal · Portal interno e padrões de engenharia

Inventário, blueprint, padrões e score de engenharia de cada repositório, acompanhados com a equipe AIUBY. Sobre o grafo de entrega, o catálogo de software diz quem é o dono de cada serviço, os scorecards dão nota com evidência, os golden paths geram o serviço novo dentro do padrão, e as extensões trazem ambientes sob pedido com custo previsto, plugins e tipos de entidade do seu jeito.

O problema

O que este produto resolve

Padrão de engenharia escrito numa wiki não muda o repositório: cada time interpreta do seu jeito.

Sem um catálogo confiável, ninguém responde rápido que serviço depende de qual, quem é o dono nem onde está o runbook.

E cada serviço novo nasce de um repositório copiado, carregando os desvios do anterior.

atualizado em

Quem usa e para quê

Perfis típicos, sem nomes de clientes. Cada uso leva o status da funcionalidade que o atende.

  • Liderança técnica de um time em crescimentoEscrever os padrões de engenharia no repositório e medir cada time contra eles.Engineering standards
  • Time de plataformaSaber que serviço depende de qual, quem é o dono e qual a nota de cada um nas regras da casa.Service catalog
  • Pessoa desenvolvedora que vai criar um serviçoGerar o esqueleto no padrão do time a partir de um template, e receber o pull request em rascunho.Self-service

Funcionalidades

O que o produto faz

Contratação pela conta, em autoatendimento.

  • Engineering standards

    Inventário, blueprint, padrões e score de engenharia acompanhados com a equipe AIUBY.

  • Service catalog

    Serviços, sistemas, APIs e donos (time ou pessoa) sobre o grafo de entrega, com lifecycle, tier, links e o descritor aiuby.yaml lido do repositório (só leitura).

  • Scorecards

    Regras declarativas (dono, runbook, SLO, achados críticos, dependências, rollout progressivo, CI) avaliadas sobre o grafo: nota por serviço e por time, histórico semanal e a evidência de cada regra.

  • Self-service

    Golden paths: templates com parâmetros tipados geram arquivos por substituição de texto (nada é executado), para baixar em zip ou patch, ou como proposta que vira PR em rascunho pelo Code Automation após a aprovação de outra pessoa. Ambiente sob pedido, que dispara pipeline, fica com os blueprints das extensões do portal.

  • Portal adoption

    Quanto do catálogo está preenchido (dono, descritor, repositório, lifecycle), quantos serviços têm nota e quanto os golden paths são usados, com a série das últimas 12 semanas. Só contagens do que o portal guarda: não mede visita de tela nem mostra número por pessoa.

  • Portal extensions

    Regras de agregação entre fontes, blueprints de ambiente com custo previsto, pedido de ambiente com quatro olhos que dispara o pipeline, plugins por HTTPS e tipos de entidade próprios.

Engineering standards, com a equipe AIUBY: em detalhe

  • Diagnóstico da engenharia
  • Instalação no repositório
  • Transformação entre times
  • Acompanhamento mensal
  • Capacitação no repositório real

O que ele não faz

  • É serviço, não software: tudo entra por pull request no seu Git.
  • Não é execução de features nem sustentação de aplicação.

Como funciona

Do começo ao registro

  1. Levante e padronize

    A equipe AIUBY levanta o inventário com o seu time e escreve o blueprint e os padrões no repositório, por pull request.

  2. Meça a rodada

    O score de engenharia é publicado com histórico, por squad, e comparado com o ponto de partida.

  3. Descreva o serviço

    Um arquivo aiuby.yaml no repositório declara dono, tier, lifecycle, sistema, dependências, APIs e links.

  4. Sincronize o catálogo

    A plataforma lê o descritor com credencial só de leitura e liga o serviço ao repositório, no grafo de entrega.

  5. Avalie com regras

    Os scorecards conferem dono, runbook, SLO, achados, CI e rollout, e guardam a nota da semana com a evidência.

  6. Crie pelo caminho pronto

    O template gera os arquivos do serviço novo; a proposta aprovada por outra pessoa vira pull request em rascunho.

  7. Peça o ambiente

    O blueprint mostra o custo mensal previsto; aprovado por outra pessoa, o pedido dispara o pipeline que sobe o ambiente.

Funcionalidades

Funcionalidade por funcionalidade

O que cada uma faz, como funciona, um exemplo tirado da documentação e o que ela não faz. O selo de cada bloco vem do catálogo.

Engineering standards

Padrões escritos no repositório e um score que mostra a evolução

A equipe AIUBY levanta com o seu time o inventário da engenharia, desenha o blueprint de arquitetura, escreve os padrões e mede cada rodada num score. Os padrões e o blueprint entram no seu repositório por pull request, revisado por quem é dono do código.

Na área logada da organização ficam o inventário, o blueprint, os indicadores por squad e o score com o histórico, sempre com o carimbo de quando a equipe publicou a leitura.

Como funciona

  • Inventário do que existe na engenharia: itens instalados, itens novos da rodada e padrões reutilizáveis.
  • Blueprint de arquitetura com o estado de cada item, publicado junto com a rodada.
  • Score de engenharia de 0 a 100, com nível, histórico por semana e a comparação com o ponto de partida.
  • Indicadores por squad na mesma publicação, para comparar times com a mesma régua.
  • Só a rodada publicada aparece para a organização: rascunho da equipe nunca chega à tela.
  • Tudo o que muda no repositório entra por pull request que o seu time revisa e mescla.

Exemplo de uso

Uma empresa com cinco squads tem padrões de engenharia numa wiki que cada time lê de um jeito. A equipe AIUBY levanta o inventário, escreve o blueprint e os padrões no repositório por pull request e publica o primeiro score. A cada rodada a liderança abre a área logada, compara o score com o ponto de partida e vê em qual squad o padrão não entrou.

O que não faz

  • Não é autoatendimento: o levantamento e a publicação de cada rodada são feitos pela equipe AIUBY.
  • O score não é recalculado sozinho a cada commit; ele muda quando uma nova rodada é publicada.
  • Não se contrata pela conta: o trabalho é um serviço de engenharia, combinado com a equipe.

Service catalog

Quem é o dono, do que depende e onde está o runbook

O catálogo de software é uma visão sobre o grafo de entrega da plataforma: serviços, sistemas, APIs, donos, dependências e repositórios são entidades e arestas do mesmo grafo que recebe implantações, incidentes e achados. Nada é copiado para uma base paralela.

Cada serviço pode ser descrito num arquivo aiuby.yaml na raiz da branch padrão do repositório. A plataforma lê o arquivo pela API do GitHub, com credencial só de leitura, e aplica lifecycle, tier, dono, sistema, dependências, APIs e links.

Como funciona

  • Dono do tipo time ou pessoa: o time é o mesmo rótulo usado na adoção de IA, e pessoa só vale para quem enxerga o workspace.
  • Lifecycle (experimental, production, deprecated) e tier de 1 a 4, em que 1 é o mais crítico.
  • Dependência para um serviço que não existe no catálogo volta como aviso, sem erro, e fica visível para correção.
  • Um repositório não altera um serviço construído de outro repositório: a sincronização responde com conflito.
  • Leitor de YAML restrito: recusa âncoras, tags, blocos multilinha, chaves repetidas e campo fora do formato, com teto de 32 KB e 1.000 linhas.
  • Leitura por API v1, CLI (aiuby catalog list e aiuby catalog get) e servidor MCP, com chave de escopo engineering:read.
Descritor no repositório O arquivo aiuby.yaml descreve o serviço; a sincronização cria ou atualiza a entrada do catálogo e a liga ao repositório.
apiVersion: aiuby.dev/v1
kind: Service
metadata:
  slug: checkout                 # identificador do serviço no catálogo
  description: Pagamento do carrinho
spec:
  lifecycle: production          # experimental | production | deprecated
  tier: 1                        # 1 (mais crítico) a 4
  owner: team:Pagamentos         # team:<nome do time> ou user:<e-mail de quem é do workspace>
  system: commerce               # identificador do sistema
  dependsOn: [catalog, payments-gateway]
  apis:
    - name: checkout-api
      type: openapi              # openapi | grpc | graphql | asyncapi | other
  links:
    - title: Runbook
      type: runbook              # runbook | docs | dashboard | repo | oncall | other
      url: https://wiki.example.com/checkout/runbook

O que não faz

  • Não descobre o aiuby.yaml em todos os repositórios sozinho: a sincronização é por repositório, pedida por quem administra o workspace.
  • Não escreve nada no repositório e não busca os links cadastrados; a definição da API é só uma referência, não é lida.
  • Não tem tipos de entidade customizados nem plugins.
  • Só quem administra o workspace edita o catálogo; os demais leem.

Scorecards

Uma nota por serviço, com a evidência de cada regra

Um scorecard é uma lista de regras declarativas, com peso, avaliadas sobre fatos que a plataforma conhece: dono no grafo, links do serviço, SLOs, achados de segurança abertos, pipelines e implantações. Nenhum código do cliente é executado para chegar à nota.

A avaliação é determinística. A nota é o peso das regras que passaram dividido pelo peso das que valem para o serviço, e cada resultado traz o texto da evidência e a referência do achado, do SLO, da execução do pipeline ou da entidade.

Como funciona

  • Nove verificações de uma lista fechada: dono, link por tipo (runbook, por exemplo), SLO, achados abertos por severidade, dependências com correção, rollout progressivo, CI passando, descritor e tier.
  • Cada regra tem peso de 1 a 10 e pode valer só para certos lifecycles e tiers; fora do alvo, a regra não conta na nota.
  • Regras versionadas: mudar o scorecard sobe a versão.
  • Histórico de uma nota por scorecard, serviço e semana; a reavaliação semanal é feita pelo worker, e quem administra pode avaliar na hora.
  • Nota por time: média das notas dos serviços cujo dono é o time.
  • Leitura por API v1, pela CLI (aiuby scorecard) e pelo servidor MCP (tipo scorecard).
Pela CLI e pela API As rotas são só de leitura e pedem chave com o escopo engineering:read.
# Notas de um serviço, com a evidência de cada regra
aiuby scorecard <serviço>

# Scorecards do workspace, com a média da última semana
GET /api/v1/engineering/portal/scorecards

# Regras com fórmula, nota por serviço e por time, histórico
GET /api/v1/engineering/portal/scorecards/{id ou slug}

O que não faz

  • Não aceita verificação escrita pelo cliente: as regras saem da lista fechada.
  • Serviço sem repositório ligado falha nas verificações de achados e de CI, porque não há como provar.
  • A nota por time usa o dono do momento da avaliação; o histórico de posse não é guardado.
  • Não tem regras de agregação entre scorecards; o teto é de 20 scorecards por workspace.

Self-service

Serviço novo nasce no padrão, sem copiar e colar repositório

Golden paths são templates com parâmetros tipados e arquivos com marcadores. Quem cria um serviço preenche os parâmetros, e a plataforma gera os arquivos por substituição de texto numa única passada: o valor inserido nunca é reprocessado nem executado.

A geração sai como download (zip ou patch para git apply) ou como proposta: outra pessoa aprova, e o resultado vira um pull request em rascunho no repositório, criado pelo mesmo escritor do Code Automation. Nada é mesclado pela plataforma.

Como funciona

  • Parâmetros com tipo e formato: texto (slug, identificador ou texto livre), número com mínimo e máximo, booleano e lista de opções.
  • Filtros de caixa nos marcadores (upper, lower, kebab, snake, pascal); expressões de outras ferramentas, como as do GitHub Actions, ficam intactas.
  • Template com marcador para parâmetro não declarado é recusado ao salvar; valor fora do formato ou com quebra de linha é recusado ao gerar.
  • Caminho de cada arquivo conferido depois da troca: relativo, sem subir de pasta, sem .git e sem repetição.
  • Proposta com separação de papéis: quem pediu não aprova, e o hash dos arquivos precisa ser o mesmo que foi aprovado.
  • O pull request só leva arquivos novos; arquivo que existe na branch base faz a criação ser recusada.

Exemplo de uso

O time de plataforma publica um template de serviço HTTP com os parâmetros nome, time dono e porta. Uma pessoa desenvolvedora preenche os três, confere os arquivos gerados e envia como proposta; a líder técnica aprova, e o pull request em rascunho aparece no repositório com o pipeline, o Dockerfile e o aiuby.yaml preenchidos. O time revisa e mescla como qualquer outro PR.

O que não faz

  • O template não executa pipeline nem cria ambiente: gera arquivos. Ambiente sob pedido fica com os blueprints das extensões do portal.
  • Não altera arquivo existente nem mescla o pull request.
  • A proposta que vira PR depende do Code Automation ligado e da credencial de escrita cadastrada no workspace; sem isso, a entrega é por download.
  • Tetos: 30 parâmetros e 50 arquivos por template, 50 templates ativos e 200 gerações por dia por workspace.

Portal adoption

Saber se o portal está sendo usado, com números do próprio portal

A tela de adoção responde três perguntas do time de plataforma: quanto do catálogo está preenchido, quantos serviços têm nota nos scorecards e quantas vezes os golden paths geraram código. Tudo é contado na hora, das tabelas que o portal mantém.

Como funciona

  • Preenchimento do catálogo: serviços com dono, com descritor aiuby.yaml sincronizado, com repositório ligado e com lifecycle informado.
  • Cobertura dos scorecards ativos: serviços com nota na última semana avaliada e a média dessas notas.
  • Uso dos golden paths: gerações, propostas de pull request, pull requests criados e propostas recusadas.
  • Série de 12 semanas (segunda-feira, UTC) com gerações, pull requests, serviços com nota e nota média.
  • Avisos do que falta para o portal ser usado: catálogo vazio, nenhum scorecard ativo ou nenhum golden path.
  • Leitura pela API v1 com o escopo engineering:read.
Pela API A rota é só de leitura e pede chave com o escopo engineering:read.
# Adoção do portal no workspace da chave
GET /api/v1/engineering/portal/adoption

O que não faz

  • Não mede visita de tela, busca nem tempo de uso: só o que fica gravado no portal.
  • Nenhum número é por pessoa; a tela mostra apenas quantas pessoas geraram a partir de um template.
  • A leitura do catálogo para em 500 serviços por workspace, e a série tem 12 semanas fixas.

Portal extensions

Um portal moldado ao jeito do seu time.

As extensões do portal cobrem o que muda de empresa para empresa: de qual ferramenta confiar em cada campo, quais ambientes um time pode pedir sozinho e quanto eles custam, que informação de fora aparece ao lado de um serviço e quais tipos de coisa o catálogo precisa conhecer além dos padrões.

O pedido de ambiente fecha o autosserviço que os golden paths começam: o time de plataforma descreve o ambiente uma vez, com o custo previsto, e quem desenvolve pede quando precisa. Nada sobe antes de outra pessoa aprovar, e o que sobe é o pipeline que o próprio time de plataforma escreveu.

Como funciona

  • Regras de agregação: para um campo de um tipo, a ordem de confiança das fontes; a entidade agregada junta o que cada fonte diz, campo a campo, e mostra de onde veio cada valor.
  • Blueprints de ambiente: tamanho do Compute, réplicas, horas por mês, custo fixo extra, workspace de IaC e pipeline de criação, com o custo mensal previsto pela tabela de preços antes de qualquer criação.
  • Pedido de ambiente com quatro olhos: quem pede não aprova; aprovado por quem administra o workspace, o pipeline do blueprint é disparado com os parâmetros do pedido.
  • Plugins por HTTPS: o endpoint recebe o resumo da entidade e devolve até 10 cartões de texto, com rede interna bloqueada, sem redirecionamento, resposta em até 4 s e 32 KB, e nenhuma credencial enviada.
  • Tipos de entidade próprios (fila, conta de nuvem, contrato, o que o seu catálogo precisar), com até 30 campos tipados (texto, número, sim ou não, endereço) e dono do catálogo.

Exemplo de uso

O time de plataforma cria o blueprint de homologação com dois contêineres pequenos e o pipeline que sobe o ambiente. Uma pessoa de produto pede um ambiente para a branch dela e vê o custo mensal previsto; a líder técnica aprova e o pipeline começa, com a branch como variável.

O que não faz

  • Nada é criado na nuvem sem a aprovação de uma pessoa diferente de quem pediu.
  • Plugin não roda código na AIUBY nem devolve HTML: só cartões de texto.
  • A estimativa usa a tabela do Compute e o custo fixo informado; outros custos de nuvem ficam fora da conta.
  • Tetos por workspace: 100 regras de agregação, 50 blueprints, 20 plugins, 30 tipos e 2.000 entidades próprias.

Governança e segurança

Regras que o código impõe

  • Tudo o que entra no seu repositório entra por pull request, revisado pelo seu time; a plataforma não mescla nada.
  • O descritor aiuby.yaml é lido com credencial só de leitura, e um repositório não altera serviço construído de outro repositório.
  • Só quem administra o workspace edita catálogo, scorecards e templates; os demais leem.
  • As regras de scorecard saem de uma lista fechada de verificações: nenhum código do cliente é executado para dar nota.
  • A geração de arquivos é substituição de texto numa única passada: o valor inserido nunca é reprocessado nem executado.
  • Na proposta de golden path, quem pediu não aprova, e o pull request só leva arquivos novos, com o mesmo hash que foi aprovado.
  • No pedido de ambiente, quem pede não aprova, e o pipeline só é disparado depois da aprovação de quem administra o workspace.
  • Plugins são chamados por HTTPS sem credencial, com rede interna bloqueada e resposta limitada a cartões de texto.
  • API v1, CLI e servidor MCP são só leitura, com chave de escopo próprio.

Integrações

Com o que se conecta

Só integrações que existem no código. Cada uma leva o status da funcionalidade que a usa.

  • GitHubO descritor aiuby.yaml é lido da branch padrão do repositório, só leitura.Service catalog
  • Grafo de entregaServiços, sistemas, APIs, donos e dependências são entidades do grafo da plataforma.Knowledge Graph
  • Scanners, SLOs e pipelinesAchados abertos, SLOs e a última execução de cada pipeline são as fontes das regras.Scorecards
  • Code AutomationA proposta aprovada vira pull request em rascunho pelo mesmo escritor, com as mesmas travas.Self-service
  • Pipelines e ComputeO blueprint aponta o pipeline que sobe o ambiente e usa a tabela do Compute para prever o custo mensal.Portal extensions
  • Plugins HTTPSUm endpoint seu recebe o resumo da entidade e devolve cartões de texto mostrados ao lado do serviço.Portal extensions
  • API v1 e CLICatálogo e notas por rota de leitura e pelos comandos aiuby catalog e aiuby scorecard.API, CLI & keys
  • Servidor MCPServiços com dono, sistema, links e notas, e o tipo scorecard, para assistentes de código.MCP server

Perguntas frequentes

Respostas diretas

O que já dá para usar hoje?

Disponível: Engineering standards, Service catalog, Scorecards, Self-service, Portal adoption, Portal extensions. Contratação pela conta, em autoatendimento.

É um portal de autosserviço completo?

Disponível: Self-service, Portal extensions, Engineering standards. O autosserviço tem duas partes. Os golden paths geram os arquivos de um serviço novo, para download ou para um pull request em rascunho depois da aprovação de outra pessoa. Os blueprints de ambiente deixam pedir um ambiente com o custo mensal previsto; aprovado por outra pessoa, o pedido dispara o pipeline que o time de plataforma definiu. Os padrões de engenharia são acompanhados pela equipe AIUBY.

Por que não dá para contratar pela conta?

Disponível: Engineering standards, Service catalog, Scorecards, Self-service. Porque os padrões de engenharia dependem de trabalho da equipe no seu repositório; os serviços de engenharia têm escopo e faixa de preço em Serviços. Catálogo, scorecards, golden paths e extensões usam o contrato Cortex e são configurados com a equipe.

Importa o catálogo ou os plugins de outro portal?

Disponível: Service catalog, Portal extensions. Não. O catálogo tem formato próprio, o aiuby.yaml, e não roda plugins de interface de outro portal. Dá para estender do jeito da AIUBY: tipos de entidade próprios com campos tipados, regras de qual fonte vale para cada campo e plugins por HTTPS que devolvem cartões de texto. Serviços, repositórios, donos e dependências vivem no mesmo grafo que recebe implantações, incidentes e achados.

O que um scorecard consegue verificar?

Disponível: Scorecards. Nove verificações de uma lista fechada: dono, link por tipo (runbook, por exemplo), SLO, achados abertos por severidade, dependências com correção, rollout progressivo, CI passando, descritor sincronizado e tier. Cada regra tem peso, e o resultado mostra a evidência. Verificação escrita pelo cliente não é aceita.

O golden path cria o repositório e sobe o serviço sozinho?

Disponível: Self-service. Não. Ele gera arquivos por substituição de texto e entrega como zip, patch ou pull request em rascunho com arquivos novos. Nada é executado, nenhum arquivo existente é alterado e o merge é do seu time.

Onde ficam os padrões, o catálogo e as notas?

Disponível: Engineering standards, Service catalog, Scorecards. Os padrões, o blueprint e o descritor de cada serviço ficam no seu repositório. O inventário, o score, o catálogo e o histórico das notas ficam na área logada da organização, e saem também pela API v1, pela CLI e pelo servidor MCP, só para leitura.

Como começo?

Disponível: Engineering standards. Por uma conversa com a equipe, que define os repositórios do levantamento. Não há nada para instalar: o trabalho acontece no repositório, por pull request, e o acompanhamento na área logada.

Funciona junto com

  • Software DeliveryPipelines e implantações com rollout progressivo são fatos que as regras dos scorecards conferem.
  • Security TestingOs achados abertos dos scanners, por severidade, entram na nota de cada serviço.
  • Incident ManagementOs SLOs do serviço contam nas regras, e o dono do catálogo é o time que responde pelo serviço.

Developer Portal

Contratação pela conta, em autoatendimento.